Workflow basics

On this page

Architecture
Data model
Routes
A complete definition
Definition characteristics
Short need syntax
Normalize definition in PHP
Instance and steps
Connect domain modules via bindings
Creating a binding framework
Connect your own module to workflow
When a Built-in Makes Sense
Administration
Safety and consistency rules
Checklist
Related documentation

dbxWorkflow gradually leads users to a technical result. A workflow describes not only a sequence of pages, but also a goal, the necessary inputs or module actions, the progress and a controlled conclusion.

For practical work, two separate instructions are available:

Creating a workflow explains planning, visual designers, decisions, automatic checks and bindings.
Using the workflow Explains start, edit, progress, eBay example, review and completion.

Examples from the current installation:

Prepare the invoice.
Process contact request and optionally answer it by e-mail.
Create and publish shop products.
Prepare and export existing shop products for eBay.

Architecture

Workflow-Definition
  -> Start erzeugt Workflow-Instanz mit Definitions-Snapshot
  -> Engine ermittelt nächsten anwendbaren Need
  -> Benutzer wählt, erfasst, erstellt oder öffnet ein Fachmodul
  -> Schritt und Werte werden gespeichert
  -> Review zeigt das geplante Ergebnis
  -> Finish führt optional ein Modul-Binding aus
  -> Instanz ist finished, paused, canceled oder error

Component	Task
dbxWorkflow	Front end router for overview, start and running instance
dbxWorkflowEngine	Normalize definition, lead instance, render and save steps
dbxWorkflowModules	Connect domain modules via declarative bindings
dbxWorkflowBindRegistry	Read bindings and generate basic scaffolding from module DDs
dbxWorkflow admin	Manage definitions, bindings and instances

Files:

dbx/modules/dbxWorkflow/
  dbxWorkflow.class.php
  include/dbxWorkflowEngine.class.php
  include/dbxWorkflowModule.class.php
  include/dbxWorkflowBindRegistry.class.php
  dd/workflowDefinition.dd.php
  dd/workflowInstance.dd.php
  dd/workflowStep.dd.php
  dd/workflowModuleBind.dd.php
  tpl/htm/workflow-*.htm
 
dbx/modules/dbxWorkflow_admin/
  include/dbxWorkflowAdmin.class.php
  tpl/htm/workflow-*.htm

Data model

have instances and steps Owner. Creating is possible for permitted users, reading/Ändern is carried out by owner or user. Admin related. The admin interface is on the group admin limited.

Routes

Frontend:

?dbx_modul=dbxWorkflow
?dbx_modul=dbxWorkflow&dbx_run1=overview&workflow=invoice_demo
?dbx_modul=dbxWorkflow&dbx_run1=start&workflow=invoice_demo
?dbx_modul=dbxWorkflow&dbx_run1=run&iid=17

Admin:

?dbx_modul=dbxWorkflow_admin
?dbx_modul=dbxWorkflow_admin&dbx_run1=edit&rid=new
?dbx_modul=dbxWorkflow_admin&dbx_run1=instances
?dbx_modul=dbxWorkflow_admin&dbx_run1=binds
?dbx_modul=dbxWorkflow_admin&dbx_run1=edit_bind&rid=new

A technical record can be preselected at the start if the binding prefill ride Permitted:

?dbx_modul=dbxWorkflow&dbx_run1=start&workflow=ticket_demo&rid=42

A complete definition

The definition is called JSON in definition json stored. The following example shows selection, free text, multiple selection, an optional step and a dependency:

{
  "workflow_key": "project_offer",
  "title": "Angebot vorbereiten",
  "result": "Versandfertiges Angebot",
  "description": "Kunde, Leistungen und Versandweg werden gemeinsam geprüft.",
  "needs": [
    {
      "key": "customer",
      "label": "Kunde",
      "mode": "single",
      "required": true,
      "actions": ["select", "create"],
      "preferred": "select",
      "hint": "Vorhandenen Kunden wählen oder neu anlegen.",
      "options": [
        {"value": "101", "label": "Muster GmbH"},
        {"value": "102", "label": "Beispiel AG"}
      ]
    },
    {
      "key": "services",
      "label": "Leistungen",
      "mode": "multiple",
      "required": true,
      "actions": ["select"],
      "preferred": "select",
      "options": ["Beratung", "Einrichtung", "Schulung"]
    },
    {
      "key": "delivery",
      "label": "Versandweg",
      "mode": "single",
      "required": true,
      "actions": ["select"],
      "options": [
        {"value": "mail", "label": "E-Mail"},
        {"value": "portal", "label": "Kundenportal"}
      ]
    },
    {
      "key": "portal_note",
      "label": "Hinweis im Portal",
      "mode": "single",
      "required": false,
      "actions": ["form"],
      "hint": "Optionaler Hinweis für den Kunden.",
      "depends_on": "delivery",
      "depends_value": "portal"
    }
  ],
  "finish": {
    "label": "Angebot abschließen"
  }
}

Definition characteristics

Top level

Field	Meaning
workflow key	Unique technical key
Title	visible name of the expiry
result	technical objective or Result
Description	Short explanation for the user
Requirements	Ordered list of necessary steps
Finish	Label and optional closing behavior

| bind ref | optional reference modul|bind key |

Need

Field	Opportunities
Keyboard	Unique, normalized key
Labels, Rearward	User guidance
Child	Input, Action, check or Decision
Automation	Manual or safe observation with Observed
Mode mode	single or Multiple
Required	True; at false Skipping is possible
Actions	Selected, Created, Form, Modules
Preferred	preferred of permitted actions
Question, Validation	derived verification question and completeness rule
missing message, resolver	Error message and suitable processing path
Options	strings; or {value,labelObjects
Event	visible result/event label
depend on	previous need on which this step depends
depend value	Optionally required value of dependency
module links	Links to domain forms, usually as openWin
complete label	Confirmation text after a completed module form

Action types

Selected: Select one or more values.
Created: Capture a new value within the workflow step.
Form: free, i.e. by binding pre-established text.
Modules: open an existing domain form, save it there and then confirm the step.

A workflow does not replace a good domain form. Modules is correct if an article, customer or mapping already has an extensive maintenance surface.

Short need syntax

In addition to JSON, the engine can also normalize line-based definitions:

result=Versandfertiges Angebot
Kunde=single|required|select!|create|hint=Kunde wählen oder anlegen
Leistungen=multiple|required|select!|options=Beratung,Einrichtung,Schulung
Notiz=single|optional|form!

! Marks the preferred action. JSON is more suitable for dependencies, module links, structured options and bindings; The line syntax is intended for small workflows and fast designs.

Normalize definition in PHP

The engine accepts array, JSON or need lines:

$engine = dbx()->get_include_obj('dbxWorkflowEngine', 'dbxWorkflow');
$definition = $engine->normalize_definition($jsonOrArray, 'project_offer');
 
if (count((array)($definition['needs'] ?? array())) === 0) {
    throw new \InvalidArgumentException('Mindestens ein Need ist erforderlich.');
}

The admin interface uses this path before saving and files the normalized definition as readable JSON. The existing definition is used as a basis: Known designer fields are updated, unknown scheme and module extensions remain round-trip secure.

Instance and steps

At startup, the engine generates a record:

$record = array(
    'workflow_key' => $definition['workflow_key'],
    'result_label' => $definition['result'],
    'status' => 'running',
    'current_need' => '',
    'percent' => 0,
    'step_percent' => 0,
    'message' => 'Workflow gestartet.',
    'definition_json' => json_encode($definition),
    'data_json' => json_encode($prefillValues),
);
 
$db = dbx()->get_system_obj('dbxDB');
$iid = ($db->insert('dbxWorkflow|workflowInstance', $record, 0, 1, 1, 1) === 1)
    ? $db->get_insert_id()
    : 0;

dbxDB Complementary Owner, user and time fields automatically from the DD.

definition json freezes the valid expiration at start for this instance. Changes or deactivations in dbxWorkflow admin This only affects new starts. Old instances from a version without snapshot continue to load the current definition for backward compatibility.

The engine writes each acquired need additionally in workflowStep. data json contains the current total value, the step table the traceable history.

Status values:

Running: Processing possible.
paused: Stop, can be continued.
Canceled: aborted.
Finished: Review and finish successfully completed.
Error: technical or technical failure condition.

Process commands run through the same instance endpoint:

&proc_cmd=pause
&proc_cmd=resume
&proc_cmd=continue
&proc_cmd=cancel
&proc_cmd=restart

process.js Gets statuses, URLs, percentages, and interval across the workflow frame data-process*-attributes.

Connect domain modules via bindings

A workflow should not have to know a domain module hard. It references:

"bind_ref": "dbxContact|contact_reply"

The binding table resolves this reference into a declarative bind json on. The domain module shall remain independent; dbxWorkflow knows DD, fields, templates and final image from the binding.

Real binding pattern

{
  "modul": "dbxContact",
  "record": {
    "dd": "dbxContact|contactRequest",
    "id_need": "contact_request",
    "prefill_rid": true
  },
  "context": {
    "tpl": "dbxContact|contact-request-summary",
    "hide_on_need": "contact_request",
    "fields": {
      "rid": "id",
      "subject": "subject",
      "name": "name",
      "email": "email",
      "phone": "phone"
    }
  },
  "needs": {
    "contact_request": {
      "type": "dd_select",
      "where": {"status": "open", "trash": 0},
      "label": "#{id} - {subject} ({name})",
      "fields": ["id", "subject", "name"],
      "order_field": "create_date",
      "order_dir": "DESC"
    },
    "status": {
      "type": "dd_field_options",
      "field": "status"
    },
    "customer_reply": {
      "type": "dd_field_value",
      "field": "reply_text"
    },
    "send_mail": {
      "type": "static_select",
      "options": [
        {"value": "1", "label": "Ja, E-Mail senden"},
        {"value": "0", "label": "Nein, nur speichern"}
      ]
    }
  },
  "finish": {
    "type": "dd_update",
    "map": {
      "status": "status",
      "reply_text": "customer_reply",
      "reply_date": "@now",
      "reply_uid": "@uid"
    }
  }
}

Binding sources

Type	Effects
dd select	Options from a DD with WHERE, fields, label and sorting
dd field options	Option list of the specified DD field
dd field value	Pre-establish existing cell value as form value
static select	Solid {value,labelOptions

show if config can only show a need if a module configuration has enabled an ability, e.g. B. Mail delivery.

Finish mapping

In type = dd update will be over record.id need selected record updated. Sources in mapping:

Name of a need, e.g. B. customer reply.
Field of the loaded record.
@need:key for an explicit need value.
@now for the current timestamp.
@uid for the active user.
a constant value.

An optional finish.mail-Block can define recipient field, subject, body template, variables and tracking fields. The shipment runs only after successful technical check and only if the module configuration allows it.

Creating a binding framework

dbxWorkflowBindRegistry can examine a module DD:

$registry = dbx()->get_include_obj(
    'dbxWorkflowBindRegistry',
    'dbxWorkflow'
);
 
$record = $registry->generateBindSkeleton(
    'dbxContact',
    'dbxContact|contactRequest',
    'contact_reply'
);

The result is a starting point, not a blindly finished domain process. WHERE, labels, mandatory steps, finish mapping, mail and rights must be technically checked.

Connect your own module to workflow

Complete subject DD and forms in the module.
A clear one bind key Select.
Create a binding framework or create it in the workflow admin.
Record-DD and id needed define.
Map Needs to DD selection, field options, field values or static values.
Optional *-summary.htm-Template as context.
Check finish mapping with a test record.
Only then bind ref in the workflow definition.
Start without RID and with &rid=... Testing.
Pause, continue, cancel, restart and review test.

When a Built-in Makes Sense

The engine currently contains special shop workflows because article system, channel mapping, export and provider status have additional domain logic. New standard cases should preferably arise via definition and binding. A new hard-coded engine branch is only justified if declarative dd update cannot safely depict the technical operation.

Complex degrees then belong in a clear domain service or adapter. The workflow engine coordinates and shows status; it should not contain a second copy of the shop, CRM or ERP logic.

Administration

The admin interface offers:

Filter, recreate and edit definitions.
Needs to visually compose and normalize.
Create, generate and test module bindings.
Show current and completed instances with progress.
Provide demo and shop definitions during installation.

Definitions are maintained with dbxForm, lists with dbxReport. DD sync runs over the four workflow DDs and is not replaced by manual table changes.

Safety and consistency rules

Instances and steps remain owner-/admin-related.
workflow key, need key, sorting and request commands are validated.
Dynamic options come via dbxDB and defined DD fields.
Finish checks record and values again; A finished UI step is not an authorization.
External actions and mail only take place after a successful domain operation.
A repeated request must not generate uncontrolled duplications.
Modules are connected via bindings; the domain module does not necessarily know the workflow.
Templates render the interface, engine and domain service the logic.
Guest instances are additionally bound to the active PHP session.
state-changing GET actions use the existing kernel action token; Pure navigation remains tokenless.
An old start/command link without a token remains accessible, but does not mutate and leads to a page with a fresh action link.
The conclusion is atomic as Finishing claimed; only the winner is allowed to perform domain operation, mail or provider action.

Checklist

Definition contains unique key, title, result and at least one need.
Mandatory, optional and dependent needs behave correctly.
Single and multiple selections store expected values.
Module links open the existing subject interface and return to the workflow in an understandable manner.
Start with RID filled only allowed values before.
Review shows all applicable steps correctly.
Finish updates exactly the intended record.
Mail/Providerfehler do not incorrectly make the instance appear successful.
Pause, resume, cancel and restart work.
Adminreport shows status, current need, progress and message.