Write Microflows

Mendix Microflow Skill

Reference files

SKILL.md covers the shape of a microflow and the decisions. The detail lives beside it:

• reference/control-flow.md — every form of if, case, split type, loop and while, plus error handling (try/custom handlers) and the @position / @merge / @anchor activity annotations.
• reference/data-operations.md — create, change, commit, delete; list operations and aggregates; retrieve from database, association and list; XPath navigation.
• reference/integration.md — rest call and send rest request, legacy SOAP, calling Java actions (including the empty argument and microflow-typed parameters), execute database query, file downloads.
• reference/pitfalls.md — read this when mxcli check rejects something you believe is correct. The anti-patterns, the CE0111 duplicate-variable trap, the syntax that looks plausible and does not parse, and the Studio Pro errors each one produces.

When to Use This Skill

Use this skill when:

• Writing CREATE MICROFLOW statements
• Debugging microflow syntax errors
• Converting Studio Pro microflows to MDL
• Understanding microflow control flow and structure

If you're not sure whether the logic belongs in a microflow or a nanoflow, read the next section first. The mirror lives in write-nanoflows — keep both copies in sync.

Changing an Existing Microflow

Choose the mode by who owns the microflow (choose-edit-mode):

• Created by your MDL scripts, and not edited in Studio Pro since: edit the script (or fresh describe output) and re-run create or modify.
• Authored in Studio Pro: prefer alter microflow X { insert/replace/drop … } (targets from describe microflow X with handles). create or modify of describe output patches too: unchanged writes nothing; a statement (even one whose handler returns), guard clause, return value, if condition, header clause, parameter (added/retyped; removed only if unused) or stated @position/@start change is patched in place (a move keeps the node's flows). A redrawn @anchor/@curve, loop body, error handler or other return added/taken away rebuilds under mdl 0 (MDL-V1-REBUILD: IDs renumbered, merges and curves lost) and is refused under mdl 1;. To change a loop body, alter … replace the whole loop — neither mode edits inside one (pitfalls). To rebuild deliberately, drop and create in ONE script — the grants carry only within it (pitfalls).

When to Use a Microflow vs a Nanoflow

Rule of thumb: A nanoflow runs before the server call. A microflow IS the server call.

Key Differences from Nanoflows

For nanoflow-specific authoring guidance, see write-nanoflows.

Microflow Structure

CRITICAL: All microflows MUST have JavaDoc-style documentation

/**
 * Microflow description explaining what it does
 *
 * Detailed explanation of the business logic, use cases,
 * and any important implementation notes.
 *
 * @param $Parameter1 Description of first parameter
 * @param $Parameter2 Description of second parameter
 * @returns Description of return value
 * @since 1.0.0
 * @author Team Name
 */
create microflow Module.MicroflowName (
  $Parameter1: type,
  $Parameter2: type
)
returns ReturnType as $ReturnVariable
[folder 'FolderPath']
begin
  -- Microflow logic here
  return $ReturnVariable;
end;

exposed as … action — putting a microflow in the toolbox

Studio Pro can show a microflow in its toolbox, so whoever drags it onto a flow does not need to know it is a microflow rather than a Java action. A microflow has two such entries — one for the microflow editor, one for the workflow editor — so the clause names which:

mdl 1;
create microflow Module.FormatCode ($Raw: String)
returns String
exposed as microflow action 'Format code' in 'Toolbox demo'
  icon 'assets/format-64.png'
  icon dark 'assets/format-64-dark.png'
  image 'assets/format-256.png'
exposed as workflow action 'Format code' in 'Toolbox demo'
begin
  return trim($Raw);
end;

The icon should be a 64x64 PNG and the image 256x192; paths resolve against the directory of the .mdl file, so a script and its artwork travel together. A different size is written with a warning; a file that is not a PNG is refused.

An omitted clause preserves what is stored — it does not clear it:

Rewriting a microflow's body must not cost it the icon a designer set in Studio Pro, and saying nothing about the toolbox is not asking to be taken out of it. Nothing below Studio Pro sees the difference — mx check reports 0 errors either way — so the preserve rule is the only thing protecting it.

Nanoflows and rules cannot be exposed. Only Microflows$Microflow stores a toolbox entry; the clause is refused on the other two with a message naming the alternative. Java and JavaScript actions have one entry each and use the shorter exposed as 'Caption' in 'Category' — see the java-actions skill.

@excluded — documents excluded from the project

@excluded before a create microflow marks the document "Exclude from project" (the same checkbox Studio Pro offers). The document stays in the .mpr, does not build, and list microflows reports it in the Excluded column.

mdl 1;
@excluded
create microflow MyModule.LegacyCalc ()
returns Integer
begin
  return 7;
end;

The sibling document annotation is @applyentityaccess — runs the flow under the current user's entity access rules rather than with full access, with the same absent-preserves rule and an explicit (false) to turn it off (pitfalls).

Two rules follow, and both are enforced rather than documented-and-hoped:

• An absent @excluded never un-excludes. It means "the script does not say", not "make this active" — so re-running a create or modify you wrote before the document was excluded leaves the exclusion alone. Un-exclude in Studio Pro. (Before #914 the rewrite cleared it, which is how a valid project ended up failing CE0122 — see the next rule.)
• A name is not unique when a twin is excluded. Mendix allows two documents of the same name in one module as long as at most one is active — verified on 11.13.0: the excluded pair builds at 0 errors, the same pair both active is [error] CE0122 "Duplicate document name". create or modify, describe and the other by-name lookups therefore target the live document; the excluded twin is neither rewritten nor deleted.

The same applies to every document type that carries the flag — nanoflows, pages, snippets, enumerations, queues, workflows, Java/JavaScript actions, mappings, JSON structures, REST/OData services, image collections and the agent documents.

FOLDER Option

Place microflows in folders for organization:

mdl 1;
create microflow MyModule.ACT_ProcessOrder ($Order: MyModule.Order)
returns boolean as $success
folder 'Orders/Processing'
begin
  -- logic
  return true;
end;

Key Rules:

• Parameters start with $ prefix
• Return variable must be declared or used
• Every microflow must end with return statement
• Every body statement ends with a semicolon ; — required, not optional. This includes block terminators: end if;, end loop;, end while;, end case;. A missing one is a parse error (missing ';' at 'return'), not a warning.
• Microflow ends with / separator

Parameter Types

-- Primitive types
$Name: string
$count: integer
$Amount: decimal
$IsActive: boolean
$date: datetime

-- Entity types
$Customer: Module.Entity

-- List types
$ProductList: list of Module.Product

-- Enumeration types
$status: enum Module.OrderStatus

Variable Declarations

✅ CORRECT Syntax

-- Primitive types with initialization
declare $Counter integer = 0;
declare $message string = 'Hello';
declare $IsValid boolean = true;
declare $Today datetime = [%CurrentDateTime%];
declare $status Enumeration(Module.OrderStatus) = Module.OrderStatus.Open;

You cannot declare an object (entity) variable. declare becomes a Create Variable activity, which Mendix only allows to hold primitive types (String, Integer/Long, Decimal, Boolean, DateTime, Enumeration). An object type is rejected by Studio Pro/mxbuild with CE0053 ("Selected type is not allowed"), plus CE0038 ("Value required") and CE7247 on any following set — whether or not you give it an initializer. mxcli check now flags it as MDL043. There is no "empty object variable" activity. Get objects from one of these:

• a microflow parameter: create microflow M.Save ($Product: Test.Product) ...
• a retrieve: retrieve $Product from Test.Product where Code = $c first;
• a create object: $Product = create Test.Product (Name = $n);
• a loop iterator: loop $Product in $Products ...

You cannot declare a list either. Same Create Variable restriction — Studio Pro rejects a list with CE0053/CE0038, and mxcli check flags it as MDL040. Get lists from:

• a microflow parameter: create microflow M.Process ($Items: list of Test.Product) ...
• a retrieve: retrieve $Products from Test.Product where IsActive = true;
• a create list: $Products = create list of Test.Product;

Decimal values into an integer/long fail CE0117. Integer division ($a div $b) is always a Decimal even for two integers, and so are random() and the duration *Between functions (secondsBetween, minutesBetween, hoursBetween, daysBetween, weeksBetween). Assigning any of them straight to an integer/long variable fails mx check with CE0117 (mxcli check now flags it as MDL041). Either declare the target decimal, or round it:

declare $Avg decimal = $Total div $Count;          -- ✅ Decimal target
declare $Whole integer = round($Total div $Count); -- ✅ rounded to Integer
declare $Secs integer = round(secondsBetween($a,$b)); -- ✅ rounded to Integer
declare $Bad integer = $Total div $Count;          -- ❌ CE0117 / MDL041

The calendar*Between functions (calendarMonthsBetween, calendarYearsBetween) return whole units (Integer) and are fine to assign directly.

Changing a variable: always set

set $Counter = $Counter + 1; changes a variable. $x = … without set is an activity that creates $x — required under mdl 1; (MDL-V1-SET otherwise). List operations and aggregates are one statement per activity and never nest: $Open = filter $Orders by Status = M.Status.Open; then $N = count $Open; — see reference/data-operations.md.

❌ INCORRECT Syntax

-- WRONG: Declaring an object/entity variable (CE0053/CE0038, MDL043)
declare $Product Test.Product;            -- bare object declare is invalid
declare $Product Test.Product = $someObj; -- initialized object declare is also invalid

-- WRONG: Declaring a list variable (CE0053/CE0038, MDL040)
declare $ProductList list of Test.Product = empty;  -- use a parameter, retrieve, or create list

-- WRONG: Using AS keyword (not supported in mxcli)
declare $Product as Test.Product;  -- ERROR: parse error

-- WRONG: No value (CE0038, MDL061)
declare $X string;  -- a Create Variable activity requires a value

-- WRONG: Missing type
declare $Counter = 0;  -- Type inference not always supported

-- WRONG: Using 'OF' instead of 'of'
declare $list list of Test.Product;  -- Case sensitive

Operators

Arithmetic

set $Result = $A + $B;      -- Addition
set $Result = $A - $B;      -- Subtraction
set $Result = $A * $B;      -- Multiplication
set $Result = $A div $B;    -- Division (use 'div', not '/')

Important: Use div for division, NOT /. In a Mendix expression / is the member/association separator ($obj/Attr), so $A / $B is not division — mxcli check rejects it as MDL045 (it would fail the build with CE0117). Integer/decimal division always yields a Decimal; wrap it in round()/trunc() for an Integer result (else MDL041).

Comparison

$A = $B       -- Equals
$A != $B      -- Not equals
$A > $B       -- Greater than
$A >= $B      -- Greater than or equal
$A < $B       -- Less than
$A <= $B      -- Less than or equal
$A = empty    -- Check if empty/null
$A != empty   -- Check if not empty

Boolean Logic

set $Result = $A and $B;    -- Logical AND
set $Result = $A or $B;     -- Logical OR
set $Result = not $A;       -- Logical NOT

-- Complex expressions
if $IsActive and $IsValid and $HasStock then
  set $CanProcess = true;
end if;