/workflow-model-design

name: workflow-model-design
description: Design and create AEM Workflow models on AEM 6.5 LTS. Use when creating workflow models via the Workflow Model Editor or content package XML, defining step types (PROCESS, PARTICIPANT, DYNAMIC_PARTICIPANT, OR_SPLIT, AND_SPLIT), configuring step properties, declaring workflow variables, deploying to /etc or /conf, and syncing to /var/workflow/models via Package Manager or Maven.
license: Apache-2.0

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](../workflow-development/SKILL.md) 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:**

| File | Node type | Purpose | |---|---|---| | `jcr_root/conf/.../models/<id>/.content.xml` | `cq:Page` | Model root page | | `jcr_root/conf/.../models/<id>/jcr:content/.content.xml` | `cq:PageContent` | Title, template, resourceType | | `jcr_root/conf/.../models/<id>/jcr:content/flow/.content.xml` | `nt:unstructured` + parsys | Step nodes |

**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

| Type | Purpose | Key metaData property | |---|---|---| | `START` | Entry point | — | | `END` | Terminal | — | | `PROCESS` | Auto-executed Java step | `PROCESS` = FQCN or process.label | | `PARTICIPANT` | Human task (static assignee) | `PARTICIPANT` = principal name | | `DYNAMIC_PARTICIPANT` | Human task (runtime assignee) | `DYNAMIC_PARTICIPANT` = chooser.label | | `OR_SPLIT` | One branch selected by rule | Transition `rule` = ECMAScript (Rhino) | | `AND_SPLIT` | All branches execute in parallel | — | | `AND_JOIN` | Wait for all parallel branches | — |

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