Operate running workflows
This page shows what an operator can do with running instances in the IdentityFlow web application, and which GraphQL mutation does the same from your own tools. Start with who may do what, then find the instance in Operations.
IdentityFlow grants access per workflow family through four
access functions, defined in your
authorization.ts. The navigation shows a section once the signed-in account
can see at least one item through the matching access function. Instances
and Operations therefore appear on a new installation only after the first
instance starts.
| Access function | Web application | GraphQL |
|---|---|---|
starter | Workflow catalog (/workflows) | startCatalog, startWorkflow |
viewer | Instances (/instances), the Business tab of an instance | business |
operator | Operations (/analytics), Failed work (/dead-letters), reassigning a dialog | operations, deadLetters, pauseInstance, resumeInstance, terminateInstance, reassignDialog, replayDeadLetter |
auditor | the Audit tab of an instance (/instances/<id>/events) | audit |
Every signed-in account also sees Assigned to me (/tasks), the dialogs it
may answer, My work (/my), and My access (/access). Answering a
dialog depends on being one of its assignees, not on an access function.
Each command checks the operator’s access again when it is submitted, with principals freshly read from the provider.
Operations lists the instances you may operate, newest first, 100 per
page. Filter by Status (Active, Paused, Errored, Terminated, Completed) and
Workflow, then choose Apply filters. Each row shows the workflow name,
its status, v<version> · <release channel> and when it was created and last
updated.
The section Operational metrics shows the completion rate, the error rate and the number of finished instances. It counts completed, errored and terminated instances; active and paused ones are not included.
Select an instance to open its operations page, /analytics/<id>:
- Timing: created, updated, scheduled until and finished.
- Diagnostics: the number of steps, the number of errored steps and the instance’s message.
- Operator controls: pause, resume and terminate, shown while the instance is neither completed nor terminated.
Each action takes an optional reason, up to 1024 characters in the web application, and records an event with the reason and your account.
| Action | Allowed when the instance is | Recorded event |
|---|---|---|
| Pause instance | Active | INSTANCE_PAUSED |
| Resume instance | Paused | INSTANCE_RESUMED |
| Terminate instance | Active or Paused | INSTANCE_TERMINATED |
If the instance changed state in the meantime, the page shows
The Workflow Instance state changed; refresh before retrying. Terminating is
final; a terminated instance cannot be resumed.
Terminate instance is also shown on an errored instance, but the command is refused there with the same message.
An instance becomes errored when a step fails its last retry and the workflow code does not catch the error; see Errors and retries. 0.3.0 has no command that retries or resumes an errored instance. Find the cause under Diagnostics and in the instance’s events, fix it, and start a new instance.
Use this when the people assigned to a dialog cannot answer it, for example because someone is absent.
- Open the instance under Instances,
/instances/<id>. - On a pending dialog step, choose Reassign this Dialog.
- Choose the Provider, enter the New Assignees, one principal subject
per line (for example
role:vacation-coverage), and enter a Reason. - Choose Reassign.
The new list replaces the dialog’s assignees; whoever holds one of those
principals may answer. The reason is required. The instance must be active or
paused and the dialog still pending. IdentityFlow records a
STEP_ASSIGNEES_UPDATED event with the reason and your account.
Failed work holds jobs that could not work out a pending dialog’s
assignees from an assignee source,
after changes.maxAttempts attempts or a permanent error. Failed steps and
errored instances do not appear here.
- Open Failed work and enter the instance ID.
- Choose Inspect failed work. Each row shows the failure code, when it failed, the number of attempts and the dialog it belongs to.
- Enter a Replay reason and choose Replay.
Replay resets the job so the assignees are worked out again. It needs a reason, an active or paused instance, a still-pending dialog, and the row as you saw it: if the job changed since you loaded the page, the replay is refused. Replay records who replayed the job and why, but appends no event to the instance, so it does not appear in the instance’s audit evidence.
An instance page, /instances/<id>, has up to three tabs, depending on your
access:
- Business: the instance’s business data and its Business steps, with
each step’s status and times. The line under the title shows
<name>@v<version> · <release channel>. - Audit: every recorded event in order, with the account that caused it; see Audit trail.
- Operations: the operations page described above.
My access (/access) shows your account, the principals IdentityFlow
last read from your provider and when, and a table of the workflow families you reach with
each access function. It is built by running each view with your own access,
so it cannot show rights you do not have.
The same commands exist as GraphQL mutations on /graphql, and each checks
access exactly like the web application. 0.3.0 authenticates GraphQL only
through the identity_flow_session cookie of a browser sign-in; it has no API
tokens for unattended tools. A refused command returns Unexpected error.
with HTTP status 200.
| Mutation | Input |
|---|---|
pauseInstance | instanceId, optional until (the time at which IdentityFlow resumes the instance by itself), optional reason |
resumeInstance | instanceId, optional reason |
terminateInstance | instanceId, optional reason |
reassignDialog | dialogId, assignees as a list of { providerId, subject }, reason |
replayDeadLetter | deadLetterId, expectedRevision (the revision you read), reason |
Authentication, error responses and the read views are described in the GraphQL API reference.