Write Workflows

Mendix Workflows Skill

Guidance for authoring workflows in Mendix projects with MDL — not just reading them. CREATE WORKFLOW / DROP WORKFLOW / ALTER WORKFLOW are fully supported and build in Studio Pro. Workflows are not read-only in mxcli; do not punt workflow creation to Studio Pro.

When to Use This Skill

• Creating a business process: approvals, reviews, multi-step tasks with user interaction, timers, and parallel branches.
• Adding/removing/reordering activities in an existing workflow (ALTER WORKFLOW).
• Regenerating a workflow from DESCRIBE WORKFLOW output (round-trippable).

A workflow is a Workflows$Workflow unit driven by a context entity: the persistent entity each workflow instance is about (the Expense being approved, the LeaveRequest being reviewed). User tasks render a page bound to System.WorkflowUserTask.

Syntax — CREATE WORKFLOW

The header options may be written in any order — each at most once — and the body must close with END WORKFLOW. (They used to be order-sensitive, in exactly the sequence below; a clause written out of place failed with mismatched input 'DISPLAY' expecting {ON, BEGIN, EXPORT, DUE, OVERVIEW}, which named neither the clause nor the rule. See ako/mxcli#586.)

mdl 1;
create workflow Module.ApprovalFlow
  parameter $Context: Module.Request        -- REQUIRED: must be a $-variable + context entity
  display 'Request Approval'                 -- optional human-readable name
  description 'Approves incoming requests'   -- optional
  export level Hidden                        -- optional: Hidden | API (default Hidden)
  overview page Module.WF_Overview           -- optional; takes a System.Workflow param
  on workflow events (UserTaskStarted, UserTaskEnded)   -- optional, repeatable
    microflow Module.ACT_AuditTask as 'Task audit'
  on any workflow event microflow Module.ACT_LogEvent   -- every type this Mendix version has
begin
  -- activities here, each terminated with ;
end workflow;

Clause order does not matter, but repetition is refused. A workflow's header clauses and a user task's clauses are a set: any order, each at most once. Writing one twice is reported by name —

line 5:2: duplicate DISPLAY clause on workflow Module.ApprovalFlow
          (already given on line 4) — each clause may appear at most once, in any order

Three clauses are list-valued and accumulate instead: the header's on workflow event(s) handlers, and a task's outcomes and boundary event. The two targeting spellings count as one clause — a user task stores one user source — so targeting microflow … and targeting xpath … on the same task is a duplicate, not two clauses. It used to be accepted, with the one written last silently winning.

Two gotchas that trip up first attempts:

• PARAMETER takes a $-variable then a context entity: parameter $Context: Module.Entity. parameter Module.Entity and parameter name: Module.Entity both fail (expecting VARIABLE).
• The body closer is end workflow, not end. end; fails (missing WORKFLOW).
• The overview page takes a System.Workflow parameter, not the workflow's context object. Measured on mxbuild 11.6.6: a page without one is CE7410 "The selected page 'Overview' should accept a parameter of type 'Workflow'". (The task page takes System.WorkflowUserTask instead — two different pages, two different parameters.)

The context is always stored as WorkflowContext. Whatever you name the variable in the header, mxcli writes the parameter as WorkflowContext, so $WorkflowContext/Attribute is the canonical way to reach it in an expression. The name you declared ($Context above) and any casing of the canonical name ($workflowContext) are rewritten to it on write — in decision conditions, user task due dates and XPath targeting, wait-for-timer delays, and with (…) parameter mappings. Anything else is an undefined variable and Mendix fails the build with CE0117 "Error(s) in expression.".

create or modify workflow … is supported (create or replace is its deprecated spelling, MDL-DEPR001).

Activities

Expressions are bare, as everywhere in MDL: a decision's condition, a timer's delay, a due date (decision $WorkflowContext/Total > 1000, due date addDays([%CurrentDateTime%], 3)). The older string form (decision '…') still parses and warns MDL-DEPR080; mxcli fmt --upgrade rewrites it.

Every activity statement ends with ;. Blocks { … } nest a sub-flow.

mdl 1;
create or modify workflow Module.ApprovalFlow
  parameter $Context: Module.Request
begin
  -- User task: renders a page, offers named outcomes (branches)
  user task Review 'Review the request'
    page Module.ReviewPage
    targeting users microflow Module.ACT_Reviewers   -- or: targeting users xpath [Active = true()]
    on created microflow Module.ACT_AssignReviewer   -- optional: runs when the task is created
    description 'Please review'
    outcomes
      'Approve' { call microflow Module.ACT_Process; }
      'Reject'  { call microflow Module.ACT_Notify; };

  -- Multi user task: same clauses, one task per targeted user
  multi user task GroupSignoff 'Group sign-off'
    page Module.ReviewPage
    outcomes 'Done' { };

  -- Call a microflow (server logic); optional name, parameter mapping + outcomes
  call microflow Module.ACT_Validate(Item = $WorkflowContext) as callMicroflow1;

  -- Decision: a boolean or enum exclusive split. The name is optional; give one
  -- when a `jump to` targets it.
  decision decision1 $WorkflowContext/Total > 1000
    outcomes
      true  -> { call microflow Module.ACT_Escalate; }
      false -> { call microflow Module.ACT_AutoApprove; };

  -- An enum decision: each outcome is a FULLY QUALIFIED enumeration value
  -- (Module.Enumeration.Value), plus one '' outcome for "none of the above".
  decision decision2 $WorkflowContext/Status
    outcomes
      'Module.ENUM_Status.Approved' -> { }
      'Module.ENUM_Status.Rejected' -> { }
      '' -> { };

  -- Parallel split: independent branches run concurrently
  parallel split split1
    path 1 { call microflow Module.ACT_Notify; }
    path 2 { call microflow Module.ACT_Log; };

  -- Wait for a timer, then continue (duration is a Mendix expression)
  wait for timer timer1 addHours([%CurrentDateTime%], 1);

  -- Wait for an external notification (e.g. an event)
  wait for notification waitForNotification1;

  -- An intermediate notification event (Mendix 11.11+): what `notify workflow`
  -- targets by name
  notification DocumentsReceived caption 'Documents received';

  -- Loop back, or stop the whole workflow, from inside an outcome. A `jump to`
  -- and an `end workflow` must each END their path, so neither can close the
  -- main flow itself (CE6679 / CE6671).
  user task Confirm 'Confirm the booking'
    page Module.ReviewPage
    outcomes
      'Redo'   { jump to Review; }
      'Cancel' { end workflow caption 'Cancelled'; }
      'Done'   { };

  -- Call a sub-workflow
  call workflow Module.SubProcess as callWorkflow1 caption 'delegate';
end workflow;

Notes attach to an activity with @annotation '…' on the line before it, as in a microflow; the workflow's own note is the header clause annotation '…', and an event sub-process takes @annotation before event subprocess. One note per activity; no other @ annotation is accepted.

mdl 1;
create workflow Module.Approve
  parameter $WorkflowContext: Module.Request
  annotation 'Started from the request form'
begin
  @annotation 'Escalates after two days'
  user task review 'Review' page Module.Review_Task outcomes 'Done' { };
end workflow;

Do NOT use a standalone annotation '...'; statement in a workflow body. It parses, but the note is written into the activity flow, which Mendix loads by constructing every child with a Flow parent — no annotation type takes one, so the resulting .mpr cannot be loaded at all. mxcli refuses it (MDL-WF04) at check and exec time. Attach the note to an activity with @annotation.

Boundary events attach a timer to a user task / call-microflow / wait:

mdl 1;
create or modify workflow Module.WithBoundary
  parameter $Context: Module.Request
begin
  user task Review 'Review'
    page Module.ReviewPage
    outcomes 'Done' { }
    boundary event interrupting timer addDays([%CurrentDateTime%], 3) {
      call microflow Module.ACT_Escalate;
    };
end workflow;

• Name the kind — interrupting or non interrupting. A bare boundary event timer writes a type no Mendix 11 runtime has: check and mxbuild pass, and the runtime then refuses to start the application ("Class 'Workflows$TimerBoundaryEvent' could not be found"). mxcli refuses the bare form on Mendix 11 (MDL-WF07).
• The delay is a DateTime expression, such as 'addDays([%CurrentDateTime%], 3)' — not an ISO duration like 'P3D'.
• Every boundary path must end in a jump, an end, or Mendix's end-of-path marker, and mxcli now appends the marker for you — so a path may end in a call microflow, as above. Without it the two kinds fail in different places: an interrupting path is CE0105 at build, and a non-interrupting one builds cleanly and then stops the runtime from starting ("Expected the flow to end with an end event"). Use jump to <task> when the path should return to the task.
• A notification boundary event (Mendix 11.11+) fires when notify workflow targets it, so it takes a name instead of a delay: boundary event interrupting notification Withdrawn 'Request withdrawn' { end workflow; }. The name is unique in the workflow. Only one interrupting boundary event per activity, of either kind (CE6697, MDL-WF15). alter workflow … { insert into X { boundary event … } } cannot add one yet — restate the workflow.
• Over MCP (--mcp), Studio Pro dictates how a notification path ends, which mxbuild does not: an interrupting one ends in end workflow; (in jump to inside a parallel split), a non-interrupting one runs to its end. mxcli refuses the other shapes with that remedy, because Studio Pro's constructor would rewrite or reject them.

Event sub-processes are flows outside the main flow, written after the main body. A notification (11.8+) or a timer (11.13+) starts one while the workflow runs; interrupting cancels every active path first, non interrupting runs alongside:

mdl 1;
create or modify workflow HR.Leave
  parameter $Context: HR.Request
begin
  user task Review 'Review' page HR.ReviewPage outcomes 'Approve' { } 'Reject' { };

  event subprocess ESP_Cancel 'Cancel request'
    on interrupting notification espCancelStart 'Cancel received' {
    call microflow HR.ACT_LogCancel;
  };
  event subprocess ESP_Reminder 'Daily reminder'
    on non interrupting timer addDays([%CurrentDateTime%], 1) as espReminderStart {
    call microflow HR.ACT_Remind;
  };
end workflow;

• The End is implicit, as in the main flow: mxcli appends one unless the body already ends (end workflow, a jump to, or branches that all end). A body with no end is CE0105.
• jump to stays inside its sub-process — a jump to its own activities or its start event builds; into another sub-process, or between one and the main flow, is CE6682 (MDL-WF05).
• A timer start needs its expression (CE0126, MDL-WF14).
• Names are shared with the main flow: a start event named like an activity is CE0495, so mxcli makes it unique.

DROP WORKFLOW

mdl 1;
drop workflow Module.ApprovalFlow;

ALTER WORKFLOW

In-place edits go through the workflow mutator — no full rewrite. alter workflow is the generic alter (the same shape as alter page): the operations go in { … }, properties are set with set ( Key: value ), and a fragment is written exactly as in create workflow.

mdl 1;
alter workflow Module.ApprovalFlow {
  set (Display: 'Updated Approval', DueDate: addDays([%CurrentDateTime%], 7));
  set (Page: Module.AltReviewPage, Description: 'Check the amount') on Review;
  set (Targeting: xpath [Active = true()]) on Review;
  insert before Review { call microflow Module.ACT_Prepare; }
  insert after Review { call microflow Module.ACT_Log; call microflow Module.ACT_Notify; }
  replace ACT_Validate with { call microflow Module.ACT_Process; }
  drop ObsoleteStep;
};

Addressing an activity. A target is the activity's name (Review — describe workflow prints every name) or its caption in quotes ('Review the request'); add @n to choose one of several matches. A name wins over a caption that repeats it. An ambiguous target is refused, and the error lists the matches (@1 user task Review, @2 decision Review) — mxcli never guesses. Every target is resolved before anything changes, so a refused statement leaves the workflow untouched. The flow's start activity (start1, caption 'Start') is addressable too, but nothing goes before it — insert before start1 is refused (it would be CE9526); use insert after start1.

Workflow keys: Display, Description, ExportLevel, DueDate, OverviewPage, Parameter: $WorkflowContext: Module.Entity. Activity keys (with on <activity>): Page, Description, Targeting: microflow M.F / Targeting: xpath [ … ], DueDate.

Adding to an activity: insert into. What goes in the braces is the activity's own clause, as create workflow writes it — and it has to match the activity kind, because an activity's outcome list is typed:

Aim one at the wrong kind and the outcome lands in a list that cannot hold it, which is not a build error: the project stops loading, so Studio Pro will not open it and mx check dies before it validates anything (ako/mxcli#415). mxcli refuses all of these — at check --references and at exec, which call the same function — and the refusal names the fragment that fits the target.

Removing a member: drop X outcome 'Reject', drop Decision1 outcome true (false, default), drop Split1 path 2, drop X boundary event. Removing a branch cannot write a wrong type; it leaves an ordinary build error (CE6686) rather than an unloadable project. path n addresses a parallel split only — on a user task it used to delete the n-th outcome (ako/mxcli#791) and is now refused; drop a user task's outcome by its value. drop X boundary event names no event, so on an activity with several it is refused under mdl 1 (under mdl 0 it drops the first and warns MDL-V1-BOUNDARYDROP).

The old per-action statements (alter workflow M.W set display 'X';, set activity X page …, insert outcome 'N' on X { }, drop path 'Path 2' on X) still parse and warn MDL-DEPR140–149; mxcli fmt --upgrade rewrites them. See mdl-examples/doctype-tests/24-workflow-examples.mdl for the full surface.

DESCRIBE round-trip

DESCRIBE WORKFLOW Module.Name emits executable, re-runnable MDL — user tasks, decisions, splits, jump-to targets, wait activities and boundary events all come back as statements (not comments). You can learn the exact syntax by describing a Studio-Pro-authored workflow, and describe → drop → exec reproduces a workflow that builds. (The implicit start/end activities are omitted, as they are re-synthesised on create.) describe prints create or modify workflow, and re-running it on the workflow it came from changes nothing: the rewrite keeps the stored names of the activities MDL cannot name (Studio Pro's start1, end1, …), the empty flow of an outcome that leads nowhere, and the empty event sub-process list.

That is for learning the syntax and for workflows your scripts own. To change an existing Studio Pro workflow, use alter workflow, never drop → exec: that re-creates the document with new identities and loses anything MDL cannot express (see choose-edit-mode).

Event sub-processes come back as event subprocess … on … blocks after the main body, and notification activities and notification boundary events as statements.

Activity names, and why jump to depends on them

Mendix stores JumpToActivity.TargetActivity as an activity name string, not a pointer — so a jump is only as good as the name it aims at. Every activity type takes an optional explicit name (as <name> for the two call activities, a bare name for the rest); without one mxcli derives it from the caption, or from the called document for call microflow / call workflow.

That default is fine for a workflow written from scratch, and it is why two decisions sharing a caption used to collide on one name. It is not fine when reproducing a workflow Studio Pro authored: Studio Pro names activities by type and ordinal — decision1, split1, callMicroflow1, userTask1, waitForNotification1 — with no relation to the caption. describe workflow emits the stored name whenever it is not derivable, so the jump wiring survives a re-execution; before that it did not, and a jump to decision1 reached MxBuild as a jump to itself (CE6681, "not possible to jump to end activities or jump-to activities" — an error naming a different fault). See ako/mxcli#408.

mxcli check resolves every jump against the activity names the script itself declares (MDL-WF05) and lists the valid targets when one misses.

Rewriting an existing workflow

CREATE OR MODIFY WORKFLOW rebuilds the workflow from the statement, so anything the script does not restate is deleted — including each boundary event's whole handler flow. This is the failure that costs real work: it is not reported by mx check afterwards, because the result is a perfectly valid workflow that simply no longer does what it did.

mxcli refuses the two cases where that would lose something:

• more stored event sub-processes or notification activities than the statement declares — restate them; a sub-process with no start event, which MDL cannot state, is refused outright;
• more stored boundary events than the statement declares — restate them and the rewrite proceeds, which is what describe workflow now emits for you;
• more stored workflow event handlers, or user tasks with an on-created microflow, than the statement declares — the same: restate them.

The safe way to change one activity in a workflow carrying hand-placed structure is ALTER WORKFLOW, which mutates in place and touches nothing else.

Microflow statements for workflow tasks

These run inside a microflow (not in the workflow body) and drive a running workflow / its tasks. They are easy to miss — there is no complete task:

• set task outcome $Task 'Approve'; — completes a System.WorkflowUserTask with a named outcome. This is how a microflow (e.g. a task page's button) finishes a task and does the domain work; the outcome branches still record which one was chosen.
• $Notified = notify workflow $Wf target Module.Workflow.Name; resumes the element it names — a notification-started event sub-process, a notification activity, a notification boundary event or a wait for notification. The target is required: a notify without one fails the build (CE0166, MDL-WF16). Name the element as Module.Workflow.ElementName; mxcli works out which kind it is and refuses one a notification cannot reach (a timer start, a user task).
• open user task $Task, lock workflow $WfDef, and workflow operation abort|pause|restart|retry|continue $Wf are also statements. A lock or unlock names its workflow definition ($WfDef or Module.Workflow); pause all / unpause all after it is Studio Pro's "Pause / Unpause instances". A bare lock workflow all is refused (MDL-WF17) — it built as CE1825.

A common shape: the task page's buttons call a microflow that does the change and then set task outcome $Task '<Outcome>', leaving the workflow's outcome branch bodies empty.

The outcome is a literal, by design. Mendix stores Microflows$SetTaskOutcomeAction.Outcome by name — a reference to one outcome of the user task, resolved when the app is built — so there is no expression slot to hold a value computed at runtime. set task outcome $Task $Outcome; is a parse error (under every language version) that says so. A shared claim-and-complete microflow, called from every button with the outcome as a parameter, therefore needs one branch per outcome, each with its own literal:

mdl 1;
create microflow Approvals.ACT_CompleteTask (
  $Task: System.WorkflowUserTask,
  $Outcome: String
)
begin
  change $Task (System.WorkflowUserTask_Assignees = [%CurrentUser%]);
  commit $Task;
  if $Outcome = 'Approve' then
    set task outcome $Task 'Approve';
  else
    set task outcome $Task 'Reject';
  end if;
end;

With more outcomes, chain elsif arms, or give each button its own small microflow that names its outcome — that keeps the outcome checked against the task when the app is built, which a runtime string never would be.

Claim the task before completing it

set task outcome on a task nobody has claimed fails at runtime, and it fails quietly — the button appears to do nothing and the only trace is in the runtime log:

ERROR - Client: You can't complete this user task, it is not assigned to you.

mxcli check and mx check both pass; the build is clean. mxcli check now warns about it (MDL-WORKFLOW10), but the platform rule is worth knowing rather than being told.

The trap is that targeting xpath / targeting microflow decides who may SEE a task — it does not assign it. There is no assign task statement; claiming is a plain write to the Assignees association, and it must come first:

mdl 1;
create microflow Module.ACT_CompleteTask ( $Task: System.WorkflowUserTask )
begin
  change $Task (System.WorkflowUserTask_Assignees = [%CurrentUser%]);
  commit $Task;
  set task outcome $Task 'Plan';
end;

If the task is claimed somewhere else — earlier in the process, or in a microflow this one calls — the warning does not apply.

Related: WorkflowUserTask.Name holds the task's CAPTION, not the activity name. A task declared user task "ReviewAndPlan" 'Review and plan' stores Name = 'Review and plan', so routing an inbox on the activity name silently never matches. Route on your own entity's status instead.