Workflow Definitions & Transitions

This page explains how to create and configure workflow definitions and transitions in Django Admin.

Creating a Workflow Definition

1. Go to Django Admin (see Admin Operations).
2. Navigate to Workflows → Workflow Definitions.
3. Click Add Workflow Definition.
4. Fill in the following fields:

Field	Description
name	A descriptive name for this workflow
description	Optional notes about the workflow's purpose
owner	The company this workflow belongs to. Leave blank to create a global (template) workflow
is_active	Whether this workflow is active. Only active workflows are picked up by the workflow manager
auto_event_linking	When enabled, events from the same batch that share a grouping field (e.g. site or equipment) will be automatically linked. Requires a Linking Rule (see Event Linking)

5. Click Save to create the definition before adding transitions.

Note: Each company can only have one workflow definition. If you need to experiment, use the Copy action to duplicate an existing global workflow to a company (see Copying a Workflow).

Adding Transitions

Transitions are added as inlines within the Workflow Definition edit page.

Each transition has the following fields:

Field	Description
from_status	The event status this transition starts from
to_status	The event status this transition moves the event to
type	AUTO — evaluated by the workflow manager; MANUAL — triggered by user action
priority	Integer (0-based). When multiple AUTO transitions match the same from_status, the one with the highest priority fires first
condition	Optional. A link to a Condition that must evaluate to true. Not applicable for MANUAL transitions
actions	Optional list of registered actions to execute when this transition fires

Transition Type: AUTO vs MANUAL

• AUTO transitions are evaluated periodically by the workflow manager. You can assign a condition to restrict when they fire.
• MANUAL transitions are triggered when a user explicitly moves an event to the to_status in the platform UI. They cannot have conditions — they fire unconditionally whenever the status change occurs.

Priority and Ordering

When multiple AUTO transitions share the same from_status, they are evaluated in descending priority order. The first one whose condition evaluates to true is executed. Only one AUTO transition fires per evaluation cycle per event.

If all matching transitions have equal priority, a stable secondary ordering is applied based on status rank.

Setting Up Actions on a Transition

In the transition inline, the Actions field shows all registered workflow actions available to this workflow's company. Select one or more actions to execute when the transition fires.

Actions run in the order they are listed. Synchronous actions run inline; asynchronous actions are dispatched to Celery. See Actions for details.

Copying a Workflow

You can copy a workflow definition (including all its transitions) to another company directly from Django Admin.

1. Open the Workflow Definition you want to copy.
2. In the top-right area, click the Copy button.
3. Select the target company.
4. Click Copy to confirm.

The copied workflow will be inactive by default. Review and activate it once you've made any company-specific adjustments.

Note: The target company must not already have a workflow definition. If it does, you'll need to delete the existing one first.

Editing Conditions

From the transition inline, click the Condition link to open the condition editor. See Conditions for a full explanation of how to build conditions.

Event Linking

Event linking automatically groups related events within the same data batch and marks duplicates as LINKED, keeping only one main event per group. This is useful when a single data batch produces multiple events for the same site or equipment.

Prerequisite: Event linking requires the workflow-linking-enabled waffle switch to be active. See Platform Toggles for instructions on enabling switches.

Enabling Event Linking

1. Open the Workflow Definition you want to configure.
2. Check the Auto event linking checkbox.
3. In the Event Linking Rule inline that appears below the transitions, configure the rule:

Field	Description
data_provider	Optional. If set, linking only applies to events from batches belonging to this data provider. Leave blank to apply to all providers
grouping_fields	JSON list of field paths used to group events within a batch. Fields are relative to the event's emission record and can traverse relations using . or __ as separators (e.g. "site_id", "data_point.data.my_key", "site.extra_data.region"). Fields are applied in priority order — see Grouping Field Priority below.
main_strategy	Strategy for selecting the main event within a group (see below)

4. Click Save.

Main Event Selection Strategies

Strategy	Behavior
Oldest created	The event with the earliest created_at timestamp is kept as the main event
Direct match preferred	Events with a direct site match (i.e. site_id is not null) are preferred. Among those, the oldest is selected. Falls back to oldest if no direct matches exist
Highest flux	The event with the highest detected emission rate is kept as the main event

Grouping Field Priority

Fields in grouping_fields are processed in order, with earlier fields taking higher priority. For each field, the remaining pool of unmatched events is grouped by that field's value. Any group of two or more events is resolved (main selected, others linked), and all events in that group — including the main — are removed from the pool before the next field is processed.

This means an event can only be linked once, by the highest-priority field that produces a match for it.

Example — ["site_id", "equipment_id"] with events A (site=1, equip=10), B (site=1, equip=11), C (site=2, equip=11), D (site=3, equip=11):

1. Group by site_id: A and B share site=1 → A is main, B is linked. A and B leave the pool.
2. Group by equipment_id: C and D share equipment=11 (B was consumed) → C is main, D is linked.

Reversing the field order to ["equipment_id", "site_id"] would instead group B, C, and D together by equipment=11, leaving A unlinked.

Events with a null value for a field are skipped for that field but remain in the pool for subsequent fields.

Supported Field Paths

grouping_fields accepts any field path relative to the event's emission record, using . or __ as separators:

Example	Resolves to
site_id	emission_record.site_id (direct FK column, no extra query)
site	emission_record.site (the Site object; compared by pk)
data_point.detected_rate	emission_record.data_point.detected_rate
data_point.data.my_key	emission_record.data_point.data.get("my_key")
site.extra_data.region	emission_record.site.extra_data.get("region")
site.sensor_config.type	emission_record.site.sensor_config.get("type")

Validation rules:

• The field path must exist on the model chain — an unknown field raises a validation error.
• A bare JSON field (e.g. data_point.data on its own) is rejected. You must specify a key within it.
• JSON sub-key paths (e.g. data_point.data.my_key) are accepted but a warning is shown if no records with that key set can be found, scoped to the workflow's owner and/or data provider.

How It Works

When the workflow manager runs, it processes linking before evaluating AUTO transitions:

1. Events in CREATED status whose data batch is COMPLETE are collected.
2. For each field in grouping_fields (in priority order), events are grouped by batch and that field's value.
3. For each group with more than one event, the main event is selected using the configured strategy; all others are marked LINKED with a main_event reference.
4. All events in a matched group are removed from the pool before the next field is processed.

Events whose data batch has not yet reached COMPLETE status are held in CREATED — AUTO transitions will not fire for them until linking has been resolved. This ensures that linking runs before any other workflow processing.

Note: A WorkflowDef with auto_event_linking enabled but no Linking Rule configured will log a warning and skip linking.

Workflow Status Reference

The following statuses are available for use in transitions:

Status	Description
CREATED	Entry state when workflow automation is enabled. Events start here and are processed before notifying operators
NEW	Default entry state when automation is disabled. Newly matched emissions
WORK_IN_PROGRESS	An operator has been assigned and is actively working the event
WAITING_APPROVAL	Awaiting review by a user with reviewer permissions
COMPLETED	All work is complete. This is a final state
ARCHIVED	The emission will not be investigated. This is a final state
REJECTED	The emission is not related to company infrastructure. This is a final state
LINKED	The emission has been linked to another event. This is a final state

See Emission States for the full state descriptions.