Workflow Model Configuration

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

Table of Contents

1. Overview
2. Model Configuration Dict
3. Relationships
4. Full Schema Reference
5. Relationship Type Behavior
6. Explicit vs Auto-Discovered vs Empty
7. Related Guides

Overview

Each WorkflowTypeRegistry entry maps a workflow name to a list of model configuration dicts. Each dict tells the query builder which model to expose, how to label it, and which related models may be filtered. The same shape is consumed by QueryBuilderMixin.get_allowed_models() and get_model_filters().

Model Configuration Dict

{
    'slug': 'purchase_order',
    'label': 'Purchase Order',
    'app_label': 'purchasing',
    'model_name': 'PurchaseOrder',
    'relationships': [
        {
            'field_name': 'vendor',
            'label': 'Vendor',
            'type': 'fk',
            'related_app': 'purchasing',
            'related_model': 'Vendor',
        },
    ],
}

SaveQueryView resolves the chosen model with next((m for m in allowed_models if m['slug'] == model_slug), None) (enezaworkflowengine/views/querybuilder.py:101), so slug must be unique within a workflow.

Relationships

The relationships list defines which related models are exposed as filter groups.

{
    'field_name': 'vendor',       # FK/M2M field name on the primary model
    'label': 'Vendor',            # display label for the relationship group
    'type': 'fk',                 # 'fk' or 'm2m'
    'related_app': 'purchasing',  # related model's app label
    'related_model': 'Vendor',    # related model's class name
}

The builder expands each relationship into filter definitions for the related model's fields, using <field_name>__<field> lookups (enezaworkflowengine/views/mixin.py:288-301).

Full Schema Reference

{
    # Required
    'slug': str,
    'label': str,
    'app_label': str,
    'model_name': str,

    # Optional — omit for auto-discovery, use [] to disable
    'relationships': [
        {
            # Required per relationship
            'field_name': str,
            'label': str,
            'type': str,            # 'fk' or 'm2m'
            'related_app': str,
            'related_model': str,
        },
    ],
}

Relationship Type Behavior

Both are emitted as a lookup_prefix of <field_name>__, so the generated filter IDs are identical in shape.

Explicit vs Auto-Discovered vs Empty

The behavior depends on whether the relationships key is present (enezaworkflowengine/views/mixin.py:284-314):

flowchart TD
    CFG["model_config passed to get_model_filters()"] --> HAS{"'relationships' key present?"}
    HAS -->|Yes| EXPLICIT["Use the explicit list<br/>even when it is empty []"]
    HAS -->|No| AUTO["Auto-discover FK + M2M<br/>from model._meta"]
    EXPLICIT --> BUILD["Build 'related' filter groups"]
    AUTO --> BUILD

Omitting the key and setting [] are not equivalent. Omission triggers auto-discovery; an empty list suppresses it.

Related Guides

• Workflow Type Registry Architecture
• Workflow Project Configuration
• Workflow Aggregate Metadata API
• Workflow Type Registry Reference
• Workflow — Developer Index