/workflow-launchers

name: workflow-launchers
description: Configure and deploy Workflow Launchers that automatically start workflows in response to JCR content changes on AEM 6.5 LTS
license: Apache-2.0

Workflow Launchers Skill — AEM 6.5 LTS

Audience

Developers and integrators configuring `cq:WorkflowLauncher` nodes that auto-start workflows on JCR content events on AEM 6.5 LTS — DAM asset processing on upload, review workflows on page edit, custom auto-trigger patterns, or overlays that disable/replace OOTB launcher behavior.

Variant Scope

• AEM 6.5 LTS only.
• Custom launchers live at `/conf/global/settings/workflow/launcher/config/` (preferred) or `/apps/settings/workflow/launcher/config/`. Legacy `/etc/workflow/launcher/config/` still works but should be migrated.
• **Not for AEM as a Cloud Service.** AEMaaCS uses Sling Job Topics for event distribution; the JCR-event-listener launcher pattern documented here does not apply directly. If the target is AEMaaCS, stop and use the cloud-service variant of this skill.

Dependencies

Launchers depend on three upstream concerns — verify all three before expecting a launcher to start a working instance:

• **workflow-model-design** — the workflow referenced by the launcher's `workflow=` property must already be deployed and synced to `/var/workflow/models/<name>`.
• **workflow-development** — every `WorkflowProcess` and `ParticipantStepChooser` referenced by that model must be registered as an OSGi service. Missing services produce `Process not found` on first instance execution.
• **workflow-triggering** — launchers are one of several triggering mechanisms; if you need a different one (manual, programmatic, HTTP API), see [workflow-triggering](../workflow-triggering/SKILL.md).

Prerequisites

• AEM 6.5 LTS author instance reachable.
• Workflow model deployed and visible at `/var/workflow/models/<name>` (verify via **Tools → Workflow → Models**).
• For OOTB-launcher overlays: write access to `/conf/global/` or `/apps/settings/`.
• `filter.xml` covering the launcher path with `mode="merge"`.

Required Permissions

• Write access to `/conf/global/settings/workflow/launcher/config/` (or `/apps/settings/...`) for deploying custom launchers via content package.
• `workflow-administrators` (or equivalent) — enable/disable launchers in the **Tools → Workflow → Launchers** UI.
• Read access to `/var/workflow/models/` for runtime path lookup.

Common Scenarios

Use this table to route a developer's intent to the right launcher pattern:

| Developer intent | Pattern | |---|---| | "Start a workflow when an asset is uploaded to DAM" | NODE_ADDED on `nt:file` under `/content/dam(/.*)?/jcr:content/renditions/original` | | "Trigger review when a page is edited under /content/my-site" | NODE_MODIFIED on `cq:PageContent` under `/content/my-site(/.*)?/jcr:content` | | "Disable an OOTB DAM launcher I don't need" | Overlay at `/conf/global/.../launcher/config/<same-name>` with `enabled={Boolean}false` | | "Replace OOTB launcher behavior with my own workflow" | Overlay at `/conf/global/.../launcher/config/<same-name>` with new `workflow=` | | "Auto-start on every replication event" | Use a Replication Trigger instead — see [workflow-triggering](../workflow-triggering/SKILL.md) Section 5 |

When NOT to Use a Launcher

Launchers are **event-based** (JCR observation). Use a different mechanism when the trigger is not an event-driven content change:

| Developer intent | Use this instead | |---|---| | "Run my workflow nightly" or any time-based schedule | Sling Scheduler + WorkflowSession API — see [workflow-triggering](../workflow-triggering/SKILL.md) `programmatic-api.md` | | "Run this once for all 500 existing pages" | A one-shot servlet or scheduled job that starts workflows in a capped loop | | "When workflow X completes, run workflow Y" | A `WorkflowProcess` step in workflow X that triggers Y, not a second launcher (avoids race conditions) | | "Run when content is replicated to publish" | Replication Trigger (workflow-triggering Section 5), not a launcher on `/var/audit/...` | | "Run on events under `/var/`, `/jcr:system`, or anonymous-user events" | These paths and the `anonymous` user are excluded by `WorkflowLauncherListener` — launchers cannot fire here |

Core Concept: What Is a Workflow Launcher?

A **Workflow Launcher** (`cq:WorkflowLauncher`) is a JCR node that registers a JCR event listener. When a node event occurs at a path matching the launcher's glob pattern, node type, and conditions, the Granite Workflow Engine enqueues a workflow start.

The listener is managed by `WorkflowLauncherListener` (an OSGi service). It reads all active launcher configurations at startup and re-evaluates them when configurations change.

Architecture at a Glance

JCR Event (NODE_ADDED / NODE_MODIFIED / NODE_REMOVED)
    ↓
WorkflowLauncherListener (OSGi EventListener)
    ↓ matches: glob, nodetype, event type, conditions
Workflow Engine: enqueue WorkflowData
    ↓
Workflow Instance created at /var/workflow/instances/

Launcher Configuration Properties

| Property | Type | Description | |---|---|---| | `eventType` | Long | `1` = NODE_ADDED, `2` = NODE_MODIFIED, `4` = NODE_REMOVED, `8` = PROPERTY_ADDED, `16` = PROPERTY_CHANGED, `32` = PROPERTY_REMOVED | | `glob` | String | Glob pattern matched against the event node path (e.g., `/content/dam(/.*)?`) | | `nodetype` | String | JCR node type the event node must be (e.g., `dam:AssetContent`) | | `conditions` | String[] | Additional JCR property conditions on the event node | | `workflow` | String | Runtime path of the workflow model `/var/workflow/models/<id>` | | `enabled` | Boolean | Whether the launcher is active | | `description` | String | Human-readable description | | `excludeList` | String | Comma-separated list of entries that suppress the launcher for matching events. Two entry formats can be mixed: bare JCR property names (skip events whose only changed property matches, e.g. `jcr:l