urban-workflow

English · Français

Workflow engine driven by a domain-specific language (DSL) — a Python port of Black-Beard-Sdk/Workflow (.NET), whose JSON output normalization system is replaced by urban-json (a JSLT engine): the messages produced by the engine are described by declarative .jslt templates that can be changed without redeploying.

A workflow in a few lines

NAME ValidationAchat VERSION 1
MATCHING (Type = 'achat')

DEFINE EVENT  DemandeSoumise 'une demande est déposée';
DEFINE RULE   MontantInferieur (DECIMAL seuil) 'montant sous le seuil';
DEFINE ACTION NotifierValideur (TEXT dossier)  'demande d''approbation';
DEFINE CONST  seuil_auto 500 'approbation automatique sous ce montant';

INITIALIZE WORKFLOW
    ON EVENT DemandeSoumise RECURSIVE SWITCH Tri

DEFINE STATE Tri 'aiguillage'
    ON EVENT DemandeSoumise
        WHEN MontantInferieur(seuil = seuil_auto)
            SWITCH Approuvee
        EXECUTE NotifierValideur(dossier = @Workflow.ExternalId)
            SWITCH EnValidation
;
DEFINE STATE Approuvee    'approbation automatique' ;
DEFINE STATE EnValidation 'en attente d''un valideur'
    EXPIRE AFTER 3 DAY SWITCH Expiree
;
DEFINE STATE Expiree      'sans réponse' ;

from urban_workflow import (
    FunctionRegistry, MemoryStorage, Workflow,
    WorkflowEngine, WorkflowFactory, WorkflowProcessor, WorkflowsConfig,
)
from urban_workflow.dsl import parse_config
from urban_workflow.outputs import default_memory_output

rules = FunctionRegistry("rule")
rules.add("MontantInferieur", lambda ctx, seuil: float(
    ctx.incoming_event.extended_datas.get("Montant", 0)) < seuil)

storage = MemoryStorage()
configs = WorkflowsConfig().add_document(parse_config(SCRIPT, rules=rules))
processor = WorkflowProcessor(configs, WorkflowFactory())
processor.load_existing_workflows_by_external_id = (
    lambda key: storage.get_by(Workflow, key, "external_id"))
processor.output_actions = default_memory_output(storage)
engine = WorkflowEngine(processor)

engine.evaluate_event({"Name": "DemandeSoumise", "ExternalId": "DA-42",
                       "Type": "achat", "Montant": 120})

Documentation

Playground

Standalone web components (editor with intellisense, diagram, schemas, scripts, simulation on the real engine…) that an application mounts as needed, and a page that assembles them — a separate distribution, urban-workflow-playground:

pip install urban-workflow-playground
urban-workflow-playground     # http://127.0.0.1:8777

Installation and development

pip install -e .[dev]
python3 -m pytest -q

Single core dependency: urban-json (which brings the ANTLR runtime used by the DSL parser). Python ≥ 3.10.

Porting status

Foundation, DSL (ANTLR grammars taken from the source), engine, urban-json templating and SQL persistence ([sql] extra, SQLAlchemy Core) are functional and tested (end-to-end scenarios DSL script → events → states → messages, lifecycle persisted in SQL), with GitHub Actions CI (Python 3.10 → 3.13 tests, ruff lint). Known bugs of the source engine are not reproduced — each one is covered by a dedicated test.

License

See LICENSE.