Class TemporalScheduleAdminService

constructor

• new TemporalScheduleAdminService(
      args: {
          background: boolean;
          internalEventPublisher: InternalEventPublisher | null;
          temporalClient: TemporalWorkflowClient;
          temporalScheduleClient: TemporalScheduleClient;
      },
  ): TemporalScheduleAdminService

  internalEventPublisher is null for a deploy's schedule sync, which has no topic and whose changes are not an operator's activity.

  Parameters

  • args: {
        background: boolean;
        internalEventPublisher: InternalEventPublisher | null;
        temporalClient: TemporalWorkflowClient;
        temporalScheduleClient: TemporalScheduleClient;
    }

    • background: boolean

      Schedules start on background-worker's queue rather than the platform worker's.

    • internalEventPublisher: InternalEventPublisher | null

    • temporalClient: TemporalWorkflowClient

    • temporalScheduleClient: TemporalScheduleClient

  Returns TemporalScheduleAdminService

Staticinstance

create

• create(
      args: {
          policies?: TemporalSchedulePolicyInput;
          scheduleId: string;
          spec: TemporalScheduleSpecInput;
          state?: { note: string; paused: boolean };
          taskQueue?: string;
          workflowArgs?: unknown[];
          workflowType: string;
      },
  ): Promise<
      | { ok: true; value: { scheduleId: string } }
      | { error: ServiceError; ok: false },
  >

  Parameters

  • args: {
        policies?: TemporalSchedulePolicyInput;
        scheduleId: string;
        spec: TemporalScheduleSpecInput;
        state?: { note: string; paused: boolean };
        taskQueue?: string;
        workflowArgs?: unknown[];
        workflowType: string;
    }

    • Optionalpolicies?: TemporalSchedulePolicyInput

    • scheduleId: string

    • spec: TemporalScheduleSpecInput

    • Optionalstate?: { note: string; paused: boolean }

      Set by a deploy to create a schedule that starts held. Omitted → running.

    • OptionaltaskQueue?: string

    • OptionalworkflowArgs?: unknown[]

      Arguments the scheduled workflow starts with. Defaults to none.

    • workflowType: string

  Returns Promise<
      | { ok: true; value: { scheduleId: string } }
      | { error: ServiceError; ok: false },
  >

delete

• delete(
      args: { scheduleId: string },
  ): Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >

  Remove a schedule. Runs it already started are left to finish. Only the worker's registry calls this, for an id a registry entry replaces.

  Parameters

  • args: { scheduleId: string }

  Returns Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >

describe

• describe(scheduleId: string): Promise<TemporalScheduleStatus>

  Describe a single schedule. Returns status: "not_scheduled" (not an error) when the schedule does not exist — the create-bootstrap affordance keys off exactly this.

  Past runs come back with outcome: "started"; call enrichRuns to resolve terminal outcomes (a per-run workflow describe).

  Parameters

  • scheduleId: string

  Returns Promise<TemporalScheduleStatus>

enrichRuns

• enrichRuns(runs: ScheduleRun[]): Promise<ScheduleRun[]>

  Resolve terminal outcomes for the given runs by describing each workflow execution once. Best-effort per run: a run whose execution can't be described (retention-aged-out, transient) keeps its prior outcome. Runs already "running" are left as-is.

  Parameters

  • runs: ScheduleRun[]

  Returns Promise<ScheduleRun[]>

getRunTimeline

• getRunTimeline(
      args: { runId: string; workflowId: string },
  ): Promise<WorkflowRunTimeline | undefined>

  One run's input, activities and failure, read from its event history. undefined when the run does not exist or has aged out of retention; infra faults throw.

  Parameters

  • args: { runId: string; workflowId: string }

  Returns Promise<WorkflowRunTimeline | undefined>

listWorkflowRuns

• listWorkflowRuns(
      args: {
          excludeWorkflowIdInfix?: string;
          limit?: number;
          workflowIdPrefix?: string;
          workflowType: string;
      },
  ): Promise<
      {
          outcome: | "started"
          | "running"
          | "completed"
          | "failed"
          | "timed_out"
          | "canceled"
          | "terminated"
          | "continued_as_new";
          runId: string;
          startedAt: Date;
          workflowId: string;
      }[],
  >

  List recent executions of a workflow type via Temporal visibility, optionally narrowed to a workflowId prefix (client-side filter — prefix operators aren't portable across visibility stores). Newest-first.

  Surfaces runs the schedule doesn't track (e.g. manually started backfills). Like describe, this is a read: infra faults (temporal-api or Temporal unreachable) throw.

  Parameters

  • args: {
        excludeWorkflowIdInfix?: string;
        limit?: number;
        workflowIdPrefix?: string;
        workflowType: string;
    }

    • OptionalexcludeWorkflowIdInfix?: string

      Skip ids containing this substring. Both filters run inside the paging loop, before limit is counted — a caller excluding fan-out children (whose ids extend their parent's, so they share its prefix and can outnumber it 80:1) would otherwise get a page of nothing but children.

    • Optionallimit?: number

    • OptionalworkflowIdPrefix?: string

    • workflowType: string

  Returns Promise<
      {
          outcome: | "started"
          | "running"
          | "completed"
          | "failed"
          | "timed_out"
          | "canceled"
          | "terminated"
          | "continued_as_new";
          runId: string;
          startedAt: Date;
          workflowId: string;
      }[],
  >

pause

• pause(
      args: { note: string; scheduleId: string },
  ): Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >

  Pause a schedule with an audit note (carries the actor id).

  Parameters

  • args: { note: string; scheduleId: string }

  Returns Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >

runNow

• runNow(
      scheduleId: string,
  ): Promise<
      | { ok: true; value: { scheduleId: string } }
      | { error: ServiceError; ok: false },
  >

  Trigger a single immediate run, overriding the overlap policy for this one action so a manual run is never silently dropped by a SKIP policy. Returns SCHEDULE_NOT_FOUND (not a throw) when the schedule is missing, so the UI can steer the operator to create it first.

  Parameters

  • scheduleId: string

  Returns Promise<
      | { ok: true; value: { scheduleId: string } }
      | { error: ServiceError; ok: false },
  >

undoPauseOnFailure

• undoPauseOnFailure(
      args: { scheduleId: string },
  ): Promise<
      | { error: ServiceError; ok: false }
      | {
          ok: true;
          value: { policyTurnedOff: boolean; resumed: boolean; scheduleId: string };
      },
  >

  Undo pause-on-failure on one schedule in a single update: turn the policy off, and resume the schedule if Temporal itself paused it after a failed run. An operator's pause stays, as does everything else on the schedule. Skips the write when neither applies, which is every boot after the first.

  Parameters

  • args: { scheduleId: string }

  Returns Promise<
      | { error: ServiceError; ok: false }
      | {
          ok: true;
          value: { policyTurnedOff: boolean; resumed: boolean; scheduleId: string };
      },
  >

unpause

• unpause(
      args: { note: string; scheduleId: string },
  ): Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >

  Resume a paused schedule with an audit note (carries the actor id).

  Parameters

  • args: { note: string; scheduleId: string }

  Returns Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >

updateSpec

• updateSpec(
      args: {
          note?: string;
          policies?: TemporalSchedulePolicyInput;
          scheduleId: string;
          spec: TemporalScheduleSpecInput;
          workflowArgs?: unknown[];
      },
  ): Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >

  Edit a schedule's cadence and policies in place. The workflow action (type / task queue) is preserved from the existing schedule; only the spec, policies, and (when given) workflow args the operator controls are replaced. workflowArgs replaces the action's args wholesale — pass the complete argument list, not a patch. Pause-on-failure is always written off, whatever the schedule carried.

  note stamps the schedule's state note the same way pause / unpause do, so a cadence edit leaves the same audit trail as a pause. Temporal has no dedicated note argument on update, so it is written through state.note; omitting it preserves whatever note is already there rather than clearing another actor's stamp.

  Parameters

  • args: {
        note?: string;
        policies?: TemporalSchedulePolicyInput;
        scheduleId: string;
        spec: TemporalScheduleSpecInput;
        workflowArgs?: unknown[];
    }

  Returns Promise<
      | { error: ServiceError; ok: false }
      | { ok: true; value: { scheduleId: string } },
  >