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 status:

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

Each is a number of seconds or an ISO-8601 duration (e.g. P30D for 30 days). Leave a field empty to keep that status forever. The matching settings are retention_completed, retention_cancelled 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-status 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. 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.

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, cancelled or failed), never running;
  • older than its status'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.