AERSHED Platform

Appearance

Workflow Automation ​

The workflows app provides a rule-based automation engine for managing the lifecycle of emission events. It evaluates configurable conditions and executes actions automatically as events progress through their states.

Workflows are company-specific and fully configurable through Django Admin — no code changes are required to define or update them.

Key Concepts ​

Workflow Definition ​

A WorkflowDef is a blueprint that describes how emissions should be processed for a given company. Each company can have one active workflow definition. Workflow definitions can also be global (no owner), making them available as templates that can be copied to specific companies.

Transitions ​

A Transition defines a possible state change — from one emission status to another. Each transition belongs to a WorkflowDef and has:

  • A from status and to status (using the Event.EventStatuses choices)
  • A type: AUTO (evaluated automatically by the workflow manager) or MANUAL (triggered by user action in the UI)
  • An optional Condition that must evaluate to true for the transition to execute
  • An optional list of Actions to run when the transition fires
  • A priority (0-based, higher value = higher priority) used to determine which transition executes when multiple transitions match

Conditions ​

A Condition is an expression tree that is evaluated against an emission event. It contains one or more ConditionGroups, which can be nested and combined with AND or OR logic. Each group contains ConditionExpressions that compare event data against configured values.

See Conditions for full details.

Actions ​

Actions are registered Python functions that execute when a transition fires. They can be synchronous or asynchronous (Celery tasks). Actions are registered globally and can be restricted to specific companies.

See Actions for full details.

Event Linking ​

Event Linking is an optional feature that automatically groups related events from the same data batch and marks duplicates as LINKED.

When auto_event_linking is enabled on a WorkflowDef, a LinkingRule controls:

  • Grouping fields — a priority-ordered list of field paths (e.g. site_id, data_point.data.my_key) that determine how events are grouped within a batch. Fields are tried in order; events matched by a higher-priority field are removed from consideration for lower-priority fields
  • Main strategy — how the "main" event is selected from a group (oldest, highest flux, or direct-match preferred)
  • Data provider filter — optionally restrict linking to events from a specific data provider

Events are only linked once their data batch reaches COMPLETE status. Within each group, one event is kept as the main event and all others have their status set to LINKED with a reference to the main event.

See Workflow Definitions & Transitions for configuration details.

Workflow Instance ​

A Workflow is a runtime instance that links a specific Event to a WorkflowDef. One instance is created per event when workflow automation is enabled, and it tracks whether the workflow has completed.

How It Works ​

The workflow manager runs every 5 minutes (when the workflow-automation-enabled switch is active) and processes all events in the following order:

  1. Create workflows — For every event in the CREATED state that doesn't yet have a workflow instance, a new Workflow is created linking the event to the company's active WorkflowDef.

  2. Resolve event linking — For workflow definitions with auto_event_linking enabled, CREATED events from completed batches are grouped by the configured fields in priority order. Within each group, a main event is selected and all other events are marked as LINKED. Events whose batch is not yet complete are held in CREATED until the next run.

  3. Execute AUTO transitions — For each active workflow, the manager evaluates all AUTO transitions from the event's current status. Transitions are evaluated in priority order (highest first). The first transition whose condition evaluates to true is executed:

    • The event status is updated to the transition's to_status
    • All configured actions are executed (sync actions inline, async actions dispatched to Celery)
    • The process repeats from the new status until no more transitions match

  4. Handle completion — When an event reaches a final state (COMPLETED, ARCHIVED, REJECTED, or LINKED), its workflow instance is marked as completed.

  5. Check for stuck workflows — Workflows with no available transitions from their current state are logged for monitoring.

MANUAL Transitions ​

MANUAL transitions are not evaluated by the workflow manager. Instead, they are triggered when a user updates an event's status in the UI. When the event is saved, a signal checks whether a MANUAL transition exists for that status change in the active workflow, and if so, executes its configured actions.

Enabling Workflow Automation ​

Workflow automation is controlled by the workflow-automation-enabled Waffle switch (see Flags and Switches).

When this switch is active:

  • New events are created with status CREATED instead of NEW, allowing the workflow manager to process them before they appear in operator queues
  • The run_workflow_manager Celery task runs every 5 minutes (see Scheduled Jobs)
  • MANUAL transitions are processed when users update event statuses

Setting Up Workflows ​

For a step-by-step guide to configuring workflows in Django Admin, see Workflow Definitions & Transitions.