Operate running workflows
This page shows what an operator can do with running
instances in the IdentityFlow web application:
pause, resume or terminate an instance, hand a waiting dialog to other people,
and read what happened. Operating needs the operator
access function for the workflow
family. First step: open Operations and
find the instance.
Then choose the task:
- stop or continue a run: Pause, resume and terminate;
- the assigned people cannot answer: Reassign a pending dialog;
- assignees could not be worked out: Replay failed work;
- see what happened: Read an instance’s history.
Who may do what lists every access function with its pages and GraphQL operations; The same actions through GraphQL lists the mutations for your own tools.
Needs the operator access function for the workflow family. On a new
installation, Operations appears only after the first instance starts.
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.
Needs operator. Each action takes an optional reason, up to 1024 characters in the web
application, and records an
event with the reason and your account. Viewers of the instance see the reason
of a pause or a termination on its Business tab.
| 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.
Pausing does not extend an instance’s time limit. An instance started with a time limit that passes while it is paused stays paused; when it resumes, by Resume instance or at the end of a timed pause, it ends right away as timed out.
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.
Needs operator. 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.
Needs operator. 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.
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.
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 HTTP status 200 with
an error code: FORBIDDEN for an instance you can see but may not operate,
NOT_FOUND for one you may not see, and the others listed under
Errors.
| 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.