chore: workflow MDL comprehensive status report — issues #7-#11 implementation summary & remaining gaps

[engalar]

Summary

This report documents the current state of workflow MDL write support after the implementation sprint for issues #7–#10. It serves as the canonical reference for what is done, what works, and what still needs attention.

---

What Was Implemented (This Sprint)

Issue #7 — Boundary Event MDL Syntax

MDL syntax added:

USER TASK ApproveOrder 'Approve Order'
  PAGE M.ApprovePage
  TARGETING MICROFLOW M.GetAssignee
  OUTCOMES
    'Approve' { }
  BOUNDARY EVENT INTERRUPTING TIMER '${PT1H}';

USER TASK act1 'Caption'
  BOUNDARY EVENT NON INTERRUPTING TIMER '${PT2H}';

USER TASK act2 'Caption'
  BOUNDARY EVENT TIMER;

Key files changed:

• mdl/grammar/MDLParser.g4 — workflowBoundaryEventClause rule (INTERRUPTING TIMER / NON INTERRUPTING TIMER / TIMER)
• mdl/ast/ast_workflow.go — WorkflowBoundaryEventNode, WorkflowUserTaskNode.BoundaryEvents
• mdl/visitor/visitor_workflow.go — buildWorkflowUserTask reads AllWorkflowBoundaryEventClause()
• mdl/executor/cmd_workflows_write.go — buildUserTask wires to workflows.BoundaryEvent
• sdk/mpr/writer_workflow.go — serializeBoundaryEvents() was already implemented ✅

---

Issue #8 — Multi-User Task Distinction

MDL syntax added:

MULTI USER TASK act1 'Caption'
  PAGE M.ReviewPage
  TARGETING MICROFLOW M.GetReviewers
  OUTCOMES 'Approve' { };

Key files changed:

• mdl/grammar/MDLParser.g4 — MULTI USER TASK alternate in workflowUserTaskStmt
• sdk/workflows/workflow.go — UserTask.IsMulti bool field added
• sdk/mpr/parser_workflow.go — parseMultiUserTask() sets IsMulti = true
• sdk/mpr/writer_workflow.go — serializeUserTask() outputs Workflows$MultiUserTaskActivity when IsMulti
• mdl/visitor/visitor_workflow.go — detects MULTI() token, sets IsMultiUser = true
• mdl/executor/cmd_workflows_write.go — passes IsMultiUser → task.IsMulti

Known limitation: DESCRIBE WORKFLOW still outputs USER TASK (no MULTI prefix) — see Remaining Gaps.

---

Issue #9 — Annotation Activity MDL Syntax

MDL syntax added:

CREATE WORKFLOW M.OrderProcessing
BEGIN
  ANNOTATION 'This workflow handles order approval';
  USER TASK ApproveOrder 'Approve Order' PAGE M.Page;
END WORKFLOW;

Key files changed:

• mdl/grammar/MDLParser.g4 — workflowAnnotationStmt, added to workflowActivityStmt
• mdl/ast/ast_workflow.go — WorkflowAnnotationActivityNode
• mdl/visitor/visitor_workflow.go — buildWorkflowAnnotation()
• sdk/mpr/writer_workflow.go — serializeAnnotationActivity() outputs Workflows$Annotation BSON
• mdl/executor/cmd_workflows_write.go — buildAnnotationActivity()

BSON format: $Type: Workflows$Annotation, fields: $ID, Description, PersistentId, RelativeMiddlePoint, Size.

Known limitation: DESCRIBE WORKFLOW outputs -- annotation text (comment) rather than ANNOTATION 'text';. See Remaining Gaps.

---

Issue #10 — Outcome Parameter Mapping WITH Syntax

MDL syntax added:

CALL MICROFLOW M.CalcDiscount
  WITH (Amount = '$WorkflowContext/Amount', Category = '$WorkflowContext/Category')
  OUTCOMES
    TRUE -> { }
    FALSE -> { };

Key files changed:

• mdl/grammar/MDLParser.g4 — WITH (workflowParameterMapping, ...) clause on workflowCallMicroflowStmt; workflowParameterMapping rule
• mdl/ast/ast_workflow.go — WorkflowParameterMappingNode, WorkflowCallMicroflowNode.ParameterMappings
• mdl/visitor/visitor_workflow.go — parses AllWorkflowParameterMapping() into AST
• mdl/executor/cmd_workflows_write.go — maps to workflows.ParameterMapping structs
• sdk/mpr/writer_workflow.go — serializeCallMicroflowTask ParameterMappings with int32(2) marker was already implemented ✅

Known limitation: DESCRIBE WORKFLOW outputs CALL MICROFLOW M.F (Param = 'expr') -- caption (parentheses syntax, no WITH keyword). See Remaining Gaps.

---

Grammar Additions

New lexer tokens (MDLLexer.g4):

• ANNOTATION, BOUNDARY, INTERRUPTING, NON, MULTI

No conflicts: NON doesn't conflict with NON_PERSISTENT (has - separator); MULTI doesn't conflict with MULTIPLE (longer match wins).

---

Build & Test Status

Check	Status
go build ./...	✅ Pass
go test ./...	✅ Pass (all existing tests)
go vet ./...	✅ No warnings

---

Remaining Gaps

1. Roundtrip Tests (no tests for new features)

The 4 new features have no dedicated tests. Needed:

Visitor parse tests (lightweight, mdl/visitor/visitor_workflow_test.go):

• Parse BOUNDARY EVENT INTERRUPTING TIMER '${PT1H}' → assert BoundaryEvents[0].EventType == "InterruptingTimer"
• Parse MULTI USER TASK ... → assert IsMultiUser == true
• Parse CALL MICROFLOW M.F WITH (P = 'expr') → assert ParameterMappings[0].Parameter == "P"
• Parse ANNOTATION 'text' → assert WorkflowAnnotationActivityNode.Text == "text"

Integration roundtrip tests (mdl/executor/roundtrip_workflow_test.go, //go:build integration):

• CREATE WORKFLOW with each new syntax → DESCRIBE WORKFLOW → verify output

2. DESCRIBE WORKFLOW Formatter Gaps

DESCRIBE WORKFLOW output is not re-executable for the new features:

Feature	Current DESCRIBE output	Expected (re-executable)
Boundary Event	BOUNDARY EVENTS\n InterruptingTimer TIMER '...'	BOUNDARY EVENT INTERRUPTING TIMER '...'
Multi-User Task	USER TASK ... (no MULTI prefix)	MULTI USER TASK ...
Annotation activity	-- annotation text (comment)	ANNOTATION 'annotation text';
Parameter mapping	CALL MICROFLOW M.F (P = 'e') -- caption	CALL MICROFLOW M.F WITH (P = 'e') -- caption

These formatter fixes are required to close issue #6 (DESCRIBE output not re-executable).

3. Issue #11 — SystemTask Backward Compatibility

Issue #11 (BSON writer support for legacy SystemTask) is open. The parser handles it via parseSystemTask() but the writer doesn't emit it. Legacy MPRs with system tasks will lose them on write.

4. MultiUserTaskActivity Special Fields

According to the Mendix Model SDK, MultiUserTaskActivity has additional fields not yet implemented:

• targetUserInput — how many users must respond
• completionCriteria — completion logic

These should be added to UserTask struct and MDL syntax.

5. CallWorkflowActivity Parameter Mappings

CallWorkflowActivity also supports parameter mappings (similar to issue #10 but for sub-workflows). Not yet implemented in MDL.

---

Files Changed in This Sprint

File	Change
mdl/grammar/MDLLexer.g4	+5 new tokens
mdl/grammar/MDLParser.g4	+4 new rules, modified 2 existing
mdl/grammar/parser/	Regenerated (make grammar)
mdl/ast/ast_workflow.go	+3 new node types, modified 2 existing
mdl/visitor/visitor_workflow.go	Boundary event, multi-user, annotation, parameter mapping parsing
mdl/executor/cmd_workflows_write.go	buildUserTask, buildCallMicroflowTask, buildAnnotationActivity wired
sdk/workflows/workflow.go	UserTask.IsMulti bool
sdk/mpr/parser_workflow.go	parseMultiUserTask(), MultiUserTaskActivity dispatch fixed
sdk/mpr/writer_workflow.go	serializeAnnotationActivity(), serializeUserTask IsMulti branch

---

Related Issues

• Closes feat(workflow): add MDL syntax for boundary events #7 (boundary event MDL syntax)
• Closes feat(workflow): preserve Multi-User Task distinction in MDL and BSON writer #8 (multi-user task distinction)
• Closes feat(workflow): add MDL syntax for workflow annotations (sticky notes) #9 (annotation MDL syntax)
• Closes feat(workflow): add MDL syntax for outcome parameter mappings in CALL MICROFLOW / CALL WORKFLOW #10 (parameter mapping WITH syntax)
• Related to DESCRIBE WORKFLOW round-trip: missing activity configs and noisy comments #6 (DESCRIBE not re-executable — formatter fixes still needed)
• Related to feat(workflow): add BSON writer support for legacy SystemTask (backward compatibility) #11 (SystemTask backward compatibility — open)