Workflow Model Design

Workflow Model Design (AEM 6.5 LTS)

Design workflow models for AEM 6.5 LTS: step structure, transitions, OR/AND splits, variables, and model XML deployment via Package Manager.

Audience

Developers and workflow designers building or modifying AEM 6.5 LTS workflow models — via the Workflow Model Editor or by hand-authoring model XML and shipping it as a content package.

Variant Scope

• This skill is AEM 6.5 LTS only.
• Models can be stored at /conf/global/settings/workflow/models/ (preferred) or /etc/workflow/models/ (legacy — auto-deployed without Sync).
• Not for AEM as a Cloud Service. If the target instance is AEMaaCS, stop and use the cloud-service variant of this skill — /etc/workflow/models/ is deprecated, the Sync flow differs, and several patterns documented here will produce models that fail to deploy.

Dependencies

Models reference deployed WorkflowProcess and ParticipantStepChooser services by process.label / chooser.label or fully-qualified class name. Build and deploy the Java step first; reference it from the model second. A model that references a label whose service is not yet registered fails at runtime with Process not found — Sync will succeed and the model will appear in the editor, but instances will fail on first execution. See workflow-development for step implementation.

Prerequisites

• AEM 6.5 LTS author instance reachable (local, dev, or sandbox).
• Maven project with ui.content module — or the ability to author in the Workflow Model Editor and export as a content package.
• Required WorkflowProcess / ParticipantStepChooser services already implemented and deployed (see Dependencies above).
• filter.xml covering the model path you intend to install, with mode="merge".

Required Permissions

• workflow-editors (or equivalent write access to /conf/global/settings/workflow/models/) — create or modify models in the Workflow Model Editor or via content package.
• workflow-administrators (or equivalent) — start test workflow instances and terminate stuck test instances during iteration.
• Read access to /conf/global/settings/workflow/models/ and /var/workflow/models/ for verification.

Workflow

Model Design Progress
- [ ] 1) Clarify the workflow purpose: what triggers it, what steps are needed, who approves
- [ ] 2) Map out steps: PROCESS (auto), PARTICIPANT (human), OR_SPLIT (decision), AND_SPLIT (parallel)
- [ ] 3) Decide payload type: single JCR_PATH or multi-page workflow package (a `cq:Page` collection, detected at runtime via `adaptTo(ResourceCollection.class)`)
- [ ] 4) Identify workflow variables needed for inter-step data passing
- [ ] 5) Design model XML: flow/parsys layer with correct nt:unstructured step components and sling:resourceType per step
- [ ] 6) Choose storage: `/conf/global/settings/workflow/models/<id>` (default; requires Sync) unless the user explicitly names a site — then `/conf/<site>/settings/workflow/models/<id>`; or `/etc/workflow/models/<id>` (legacy, auto-deployed)
- [ ] 7) Add filter.xml entry with mode="merge"
- [ ] 8) Deploy via mvn install or Package Manager
- [ ] 9) Open the model in Tools → Workflow → Models → Edit → Sync; verify the model appears in /var/workflow/models/ and all steps render on the editor canvas
- [ ] 10) Start a test workflow instance; confirm it runs to completion

Output Contract

Generate only these files for a /conf-based model:

Never generate — hard stops:

• ❌ Any file under jcr_root/var/ — AEM Sync writes /var/workflow/models/ automatically after you click Sync in the editor. Never ship /var content in a content package.
• ❌ A model/ directory inside jcr:content/ at the /conf path — a cq:WorkflowModel node with <nodes> and <transitions> is the runtime format. It must never appear under /conf. The Workflow Model Editor cannot open a model that contains it.
• ❌ <filter root="/var/workflow/models/..."/> in filter.xml — /var is never a package filter target. The only filter entry needed is the design-time /conf (or /etc) path.

filter.xml — correct entry:

<filter root="/conf/global/settings/workflow/models/my-workflow" mode="merge"/>

Node Types Quick Reference

Default Path Rule

Unless the user explicitly names a specific AEM site, always generate models at /conf/global/settings/workflow/models/<id>. Do not infer a site-scoped path (e.g., /conf/wknd/…) from conversational context such as "for the WKND site" or "install on the WKND instance." Workflow models are not site-scoped by default — they are global resources. Only use /conf/<site>/settings/workflow/models/<id> when the user explicitly states that the model should be scoped to a specific site.