Skip to content
IdentityFlow

Audit trail

AUDIT TAB · AUDITOR BUSINESS TAB · VIEWER Event history immutable Evidence entry without payload Business data and step summaries becomes derives
AUDIT TAB · AUDITOR BUSINESS TAB · VIEWER Event history immutable Evidence entry without payload Business data and step summaries becomes derives
Each event becomes one evidence entry for auditors, without its payload; viewers see the instance’s business data and step summaries on the Business tab.

The audit trail shows, for each workflow run, every recorded event in order with its time and the account that caused it. Reading it needs the auditor access function for the workflow family. First step: open an instance and choose the Audit tab.

Two limits matter before you rely on it: a refused action leaves no entry, and 0.3.0 records no version per event or step, only the version the instance last ran on. What IdentityFlow records explains the version, What the audit trail does not show the other gaps, and the end of this page what to keep when you pass the record on to an auditor or a customer.

Where to read it

Section titled “Where to read it”

In the web application

Section titled “In the web application”

Open the instance and choose the Audit tab, /instances/<id>/events. The page Audit evidence shows <name>@v<version> · <release channel>, the status, the number of events, and one entry per event with:

  • the action, which is the event type, such as STEP_CONTINUING for an answered dialog, and the time;
  • a result and a reason: allow and assigneeRelation for a dialog answered by a signed-in account, otherwise recorded and workflowEvent;
  • Resource: the instance or step the event concerns;
  • Account: who caused it, or Workflow Engine;
  • Authority: for an answered dialog, the provider, the matched principal if one is disclosed, and the policy version, such as actor-bound-command/v1; for every other event, the workflow engine.

Through GraphQL

Section titled “Through GraphQL”

The audit view returns the same record for your own tools:

  • audit.list returns one summary per instance: id, workflowId, workflowName, workflowVersion, workflowReleaseChannel, status, createdAt, updatedAt and eventCount. It can be filtered by status and workflow name.
  • audit.find(id) adds evidence, one entry per event: id, action, resource (kind and id), at, actorAccountId, reason, result and authority (kind, providerId, matchedPrincipal, policyVersion).

The audit view does not return event payloads such as start parameters, dialog answers or step results. Details are in the GraphQL API reference.

What IdentityFlow records

Section titled “What IdentityFlow records”

Every change to an instance is stored as an event: the instance started, a step started, completed or errored, a dialog was answered, an operator paused the instance or reassigned a dialog. Events are immutable and ordered; nothing edits or deletes them. The current state you see in the web application is derived from them.

For each instance, the audit trail gives you:

  • the Workflow Definition’s name, version and release channel;
  • every event in order, with its type, time and the step or instance it concerns;
  • the account that caused each event, or the workflow engine for events it wrote itself;
  • for a dialog answer, the authority it was accepted under: the provider and the principal of the account that matched the dialog’s assignees;
  • the instance’s status and the number of events.

The version shown is the one the instance last ran on. A running instance moves to the newest compatible version of its definition each time it continues, so earlier steps may have run on an earlier version of the same major; see Versions and changed bundles. 0.3.0 shows no version per event or per step, in the web application or through GraphQL. To reconstruct which code ran a step, keep a record of which versions were deployed when.

What the audit trail does not show

Section titled “What the audit trail does not show”
  • Refused actions. A command or read that IdentityFlow refuses leaves no entry you can read, in the web application or through GraphQL.
  • Replayed failed work. Replay failed work appends no event to the instance.
  • Business data. The audit view excludes event payloads such as parameters, answers and step results. The Business tab shows the instance’s business data and step summaries to accounts with the viewer access function.

Keep evidence without leaking data

Section titled “Keep evidence without leaking data”

When you pass evidence on, keep:

  • the instance ID and the definition name and version;
  • how each step ended, and the event types in order;
  • the account and the matched principal for each decision a person made.

Leave out what the question does not need. Principal subjects, names and business data identify people. If the question is “did the right kind of person approve this”, you rarely need the name to answer it, and a redacted record is one you can share.

Keep secrets out of what a workflow records in the first place. Step results, dialog answers and parameters are stored in events, and an event cannot be changed afterwards.

For a call to another system, the event shows what your step returned, not what the other system did. Return the other system’s confirmation, such as a booking ID, from the step, so the record shows that the other side accepted the work; see Errors and retries. For a change event, keep its eventId and the status IdentityFlow answered with, including duplicate.