E

Workflow Type Registry Troubleshooting

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

Table of Contents

  1. Overview
  2. Custom Workflow Not in the Model List
  3. Models Not Resolving
  4. Relationships Not Showing
  5. Config Changes Not Taking Effect
  6. Cannot Override a Framework Workflow
  7. General Debug Checklist
  8. Related Guides

Overview

Most registry problems come from three sources: a wrong dotted path, a workflow-name mismatch, or the registry cache. The registry swallows import/config errors silently (enezaworkflowengine/services/workflow_type.py:154-167), so a misconfiguration looks like "nothing happened" rather than an exception.

flowchart TD
    SYM["Workflow not working"] --> A{"Setting path correct?"}
    A -->|No| FIX1["Fix MY_PROJECT_WORKFLOWS_CONFIG"]
    A -->|Yes| B{"Registry key matches<br/>Workflownames value?"}
    B -->|No| FIX2["Correct the exact string"]
    B -->|Yes| C{"app_label / model_name correct?"}
    C -->|No| FIX3["Verify via apps.get_model"]
    C -->|Yes| D{"Restarted server?"}
    D -->|No| FIX4["Restart to clear the registry cache"]
    D -->|Yes| FIX5["Inspect relationships list"]

Custom Workflow Not in the Model List

Cause 1 — wrong setting path. The setting must be the full dotted path to the class, not the module or instance:

python
MY_PROJECT_WORKFLOWS_CONFIG = 'myproject.workflowconfig.WorkflowTypeConfig'

Cause 2 — name mismatch between choices and registry. The key in WORKFLOW_TYPE_REGISTRY must exactly match a Workflownames value (case-sensitive). The Python constant name is not used.

Models Not Resolving

Cause — incorrect app_label or model_name. Both must match Django's labels exactly. Verify in a shell:

python
from django.apps import apps
model = apps.get_model('myapp', 'MyModel')
print(model)  # must not raise LookupError

If the model is auto-discovered by the builder, a bad related_app / related_model inside a relationship is skipped silently for aggregates (views/mixin.py:170-173) and raises later when generating filters (views/mixin.py:289).

Relationships Not Showing

Cause — an empty relationships list disables auto-discovery. Omitting the key enables auto-discovery; setting [] suppresses it (views/mixin.py:284-314).

  • To expose relationships explicitly, populate the list.
  • To expose all FK/M2M automatically, remove the key entirely.

Config Changes Not Taking Effect

Cause — the merged registry is cached after first access (workflow_type.py:175-176). Restart the Django development server. There is no cache-invalidation hook.

Cannot Override a Framework Workflow

Cause — a typo in the workflow key. The key must match the framework string exactly:

Framework Your config must use
'InvoiceWorkflow' 'InvoiceWorkflow'
'PurchaseOrderWorkflow' 'PurchaseOrderWorkflow'

A near-miss creates a new, separate workflow instead of overriding.

General Debug Checklist

  1. Confirm MY_PROJECT_WORKFLOWS_CONFIG imports: import_string(path) succeeds.
  2. Confirm the class exposes a WORKFLOW_TYPE_REGISTRY dict.
  3. Confirm each registry key matches a Workflownames value.
  4. Confirm each app_label / model_name resolves with apps.get_model.
  5. Confirm relationships is either omitted (auto) or a populated list.
  6. Restart the server to clear the cache.
  7. Re-check the URL namespace: it is enezaworkflowengine, mounted under /workflow/.
View source Edit this page