Workflow Actions (user‑triggered)

Workflow actions let users perform configurable multi‑step operations with a single click. Unlike actions for lifecycle hooks, these actions run only when explicitly requested. They are configured centrally in Spring/YAML and executed by the same ActionsRunner engine.

---

1. Enabling workflow actions

Add or override the following in any Spring configuration file (commonly application.yml). Hook‑based actions (enabled) and workflow actions (wfEnabled) can be toggled separately.

hanami:
  features:
    actions:
      enabled: false     # lifecycle hooks
      wfEnabled: true    # workflow actions ➜ ON

When wfEnabled: false no workflow buttons are shown in the UI and API calls will return 404 – unknown action.

---

2. Where to put the configuration

workflow.actions is an array that can live in any Spring YAML file. We recommend a dedicated file per domain—for example customer-workflow.yml.

# ext/config/customer-workflow.yml
workflow:
  actions:
    - id: …

Multiple files merge automatically as long as each id is unique.

---

3. Top‑level keys

Key	Type	Required	Description
id	string	✓	Unique slug. Also used in REST endpoints and permission rules.
scope	string	✕ (default is item only supported)	. Determines where the button appears.
icon	string	✕	UI icon name (Material icons palette).
validationQuery	string	✓	SPARQL ASK executed against the item (or collection/workspace) graph. Must return true for the action to become clickable.
jobs	list of strings	✓	One or more action‑job IDs executed sequentially. Same semantics as actions/*.yml.
excludeJobs	list of strings | string	✕	Comma‑separated or YAML list of hook job IDs to suppress during this workflow. Useful to avoid infinite loops when using itemUpdateQueryStep.
i18n	map	✕	Keys pointing to the translation bundle (see §5).

---

4. Execution order & exclusion logic

1. UI/API calls /workflow/{id} with itemUri (or collection/workspace id).
2. Engine evaluates validationQuery (templated via SpEL)—if false → HTTP 409.
3. Provided jobs run through ActionsRunner with on=workflow.
4. During nested beforeSave/onSave/… executions, any job whose id matches excludeJobs is skipped.

The exclusion list is checked by string containment—so dataset‑reset will also skip dataset‑reset-onsave.

---

5. Internationalisation

The i18n map carries keys (not literal text) so UIs can fetch translations via react-intl, Angular i18n, etc.

Key	Used for
actionLabel	Text in the dropdown menu.
confirmationTitle, confirmationBody, confirmationOk	Modal dialog shown before execution.
successLabel	Toast/snackbar after successful run.

---