Skip to content

Retention

Finished process instances, and the tokens, variables, incidents and tasks they own, accumulate for the life of a site. Retention deletes them automatically once they are older than a configured age, keeping the runtime tables bounded.

The durable history is not lost: the audit log records what happened and survives instance deletion, so retention prunes only the operational runtime data, not the record of it.

Configuration

Retention is opt-in and off by default. On the Orchestra settings page, under Retention, set how long to keep instances of each terminal state:

  • Completed
  • Canceled
  • Failed (often kept longer, for diagnosis)

Each is a number of seconds or an ISO-8601 duration (e.g. P30D for 30 days). Leaving a field empty is how you keep that state forever, and it is the only way to ask for it: an age of 0 keeps instances for no time at all, so the next cron run purges every instance in that state. An age the site cannot measure with is refused when you save it, rather than stored and read later as "keep forever". The matching settings are retention_completed, retention_canceled and retention_failed.

Per-workflow and per-tenant overrides

The site-wide ages are the default. A workflow or a tenant can override them on its own configuration, so the override travels with the entity on export and is removed when the entity is deleted. Each override either:

  • sets its own per-state ages, overriding the default for that scope; or
  • holds the scope, exempting it from purging entirely.

A workflow override takes precedence over its tenant's, which takes precedence over the site default, and it does so per state: an override that names an age for one state and leaves the others empty overrides only that state, and the empty ones keep falling back. A hold on an instance's workflow or its tenant means it is never purged, whatever the ages say, until the hold is lifted, for audits, litigation or compliance freezes.

Edit a workflow's override on its Retention tab. Edit a tenant's override from the Tenants list (under the Orchestra admin menu), which links each tenant to its own Retention form and shows its effective override at a glance.

The same shape elsewhere

Read access, which decides who besides a requester may read a run, is configured exactly this way: a site default, a per-tenant override on the Tenants list, a per-workflow override on the workflow's own tab, and the workflow wins over the tenant, which wins over the site. Learn the precedence once and it holds for both.

Preview (dry run)

Each retention form, site-wide, per workflow and per tenant, shows a live dry run: how many instances the current policy would purge right now, in that form's scope, without deleting anything. Use it to check the impact of an age or a hold before relying on the scheduled cron purge. The same count is available from the command line with drush orchestra:purge-instances --dry-run.

What is purged

On each cron run a bounded batch of eligible instances is deleted (so a large backlog clears over several runs). An instance is eligible only when it is:

  • terminal (completed, canceled or failed), never running;
  • older than its state's configured age, measured from when it finished;
  • free of any open incident (a dead-lettered branch awaiting an operator is never purged from under them); and
  • not a subprocess child whose parent is still running (it is kept until the parent finishes, then becomes eligible).

Deleting an instance cascades to its tokens, variables, incidents, work items and subprocess children.

Version snapshots

Purging instances is what leaves old workflow versions with nothing pinned to them. So when retention is enabled, the same cron run also prunes version snapshots that no instance pins and that are not the current or published version. A deleted workflow's snapshots are removed entirely once no instance references them. Versions still in use, and each workflow's current version, are always kept.

From the command line

The same purge runs from Drush, for one-off cleanups or to preview before enabling on cron:

drush orchestra:purge-instances [--dry-run] [--limit=N]

--dry-run reports how many instances are eligible without deleting anything; --limit caps how many are purged in the run.