Workflow Hooks Reference

Developer guide for the Enezaframework workflow engine. Part of the Workflow series.

Table of Contents

1. Event Reference
2. WorkflowHookContext Reference
3. Filter Semantics
4. Ordering and De-duplication
5. Settings
6. Failure History Rows
7. check_workflow_hooks
8. WorkflowHookRegistry API
9. Troubleshooting
10. Related Guides
11. A Note on Testing

Event Reference

WorkflowHookEvent (enezaworkflowengine/models/choices.py) lists the valid event keys.

Notes:

• state_entered carries trigger = start, transition, fork or join.
• state_changed fires exactly once per successful transition_branch call. to_state is the resolved landing state code, or '' when the branch landed on a FORK, JOIN or END node — read metadata.to_state_type to tell which.
• Blocked transitions emit nothing. A rejected/changes-requested step emits only its own event, never completed or cancelled.

WorkflowHookContext Reference

WorkflowHookContext (enezaworkflowengine/services/workflow_hooks.py) is a frozen, JSON-serializable dataclass passed to every handler.

Methods (return None if the row no longer exists):

To identify the record the workflow is attached to, read document_model and document_id directly (no query), or call get_document_id() for a native-typed pk:

def on_submitted(context):
    model = context.document_model   # 'frameworkapp.IncidentReport'
    pk = context.document_id         # '42' (no query)
    pk = context.get_document_id()   # 42 (int/UUID; queries the row)

to_dict() / from_dict() convert to and from the primitive payload used by the async task.

Filter Semantics

A dict entry's filters are compared as strings against the matching context field:

'state_entered': [
    {'handler': 'myapp.hooks.on_closed', 'to_state': 'closed'},
    {'handler': 'myapp.hooks.on_reopen', 'from_state': 'closed', 'to_state': 'investigation'},
]

• Every present, non-empty filter must match exactly (logical AND).
• Absent or empty filters match anything.
• Valid filter names: from_state, to_state, step_name, document_model.
• Unknown keys are ignored.

Ordering and De-duplication

Handlers run sequentially, in this order:

1. the '*' workflow bucket, in list order,
2. the matching workflowname bucket, in list order,
3. runtime hooks added with register(), in registration order.

An identical (handler, filters) pair is executed once per event, even if declared twice.

Settings

Failure History Rows

A hook that raises is logged and written to the document's workflow history:

Successes are not recorded in history, to keep the timeline readable. The history templates render the unknown type through the generic get_action_type_display fallback.

check_workflow_hooks

Validate the registry without running a workflow:

python manage.py check_workflow_hooks
python manage.py check_workflow_hooks --workflowname IncidentWorkflow
python manage.py check_workflow_hooks --json

The report prints MY_PROJECT_WORKFLOWS_CONFIG, the raw WORKFLOW_HOOKS mapping, the valid events, and one row per entry with its status:

The command exits non-zero when any entry is not resolved, so it can gate CI.

WorkflowHookRegistry API

from enezaworkflowengine.services.workflow_hooks import WorkflowHookRegistry

WorkflowHookRegistry.register('InvoiceWorkflow', 'approved', my_callable)
WorkflowHookRegistry.register('*', 'completed', my_callable, document_model='app.Model')

• register(workflowname, event, handler, **filters) — adds a runtime handler for apps that cannot edit the project config; workflowname='*' matches every workflow. Raises TypeError when the handler is not callable.
• iter_handlers(workflowname, event, context=None) — yields the resolved callables in execution order.
• describe() — the flat diagnostic view used by the command.

Runtime hooks live in process memory and are lost on restart; prefer the config registry for anything permanent.

Troubleshooting

Related Guides

• Workflow Hooks — concepts and quick start.
• Workflow Project Configuration — the workflowconfig/ package pattern.
• State-Based Workflow Reference — the state engine service API.
• Workflow — Developer Index

A Note on Testing

Per project rules, the developer or agent does not run or claim test results. The user is solely responsible for all testing and validation of the output described in this guide.