Workflow Launchers

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.

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:

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:

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

Copy code
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

Launcher Storage Paths on 6.5 LTS

On AEM 6.5 LTS, launcher configurations can live at:

Resolution order: /conf/global → /apps → /libs

Deploying a Custom Launcher on 6.5 LTS

Maven project location:

Copy code
ui.content/src/main/content/jcr_root/conf/global/settings/workflow/launcher/config/
    my-custom-launcher/
        .content.xml

Or for overlay-based approach under /apps:

Copy code
ui.apps/src/main/content/jcr_root/apps/settings/workflow/launcher/config/
    my-custom-launcher/
        .content.xml

Node structure (.content.xml):

xmlCopy code
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root
    xmlns:jcr="http://www.jcp.org/jcr/1.0"
    xmlns:cq="http://www.day.com/jcr/cq/1.0"
    jcr:primaryType="cq:WorkflowLauncher"
    eventType="{Long}1"
    glob="/content/dam(/.*)?/jcr:content/renditions/original"
    nodetype="nt:file"
    workflow="/var/workflow/models/dam/update_asset"
    enabled="{Boolean}true"
    description="Start DAM update workflow on new original rendition upload"/>
<!-- For author-only restriction, package this .content.xml under config.author/.
     The runModes property on cq:WorkflowLauncher is unreliable on 6.5 LTS. -->

Filter in filter.xml:

xmlCopy code
<filter root="/conf/global/settings/workflow/launcher/config/my-custom-launcher"/>

Overlaying an OOTB Launcher

To disable or modify an OOTB launcher:

1. Copy the node from /libs/settings/workflow/launcher/config/<launcher-name> to /conf/global/settings/workflow/launcher/config/<launcher-name> (or /apps/settings/...)
2. Modify the property (e.g., enabled="{Boolean}false")
3. Deploy via Package Manager or Maven

Common OOTB Launchers (6.5 LTS)

Verified against /libs/settings/workflow/launcher/config/ on AEM 6.5 LTS. Inspect any launcher in CRXDE Lite or via Tools → Workflow → Launchers for the full property set.

Event Type Combinations

To listen for both ADD and MODIFY, combine event types:

xmlCopy code
eventType="{Long}3"  <!-- 1 (ADD) + 2 (MODIFY) = 3 -->

Where-Clause Conditions

xmlCopy code
conditions="[property=cq:type,value=publicationevent,type=STRING]"

Condition format: property=<name>,value=<value>,type=<JCR_TYPE> (type is optional, defaults to STRING).

Architecture Considerations

Launchers are the surface where workflow load is automated. A single bad glob can flood the workflow job queue with one content edit. Apply these before deploying any launcher:

• Narrow your glob, node type, and conditions. A broad glob (/content(/.*)?) paired with eventType=2 (NODE_MODIFIED) fires on every property change under /content. Always pair the glob with a specific nodetype (cq:PageContent, dam:AssetContent) and conditions that match only the events you care about.
• Watch multi-event amplification. A single DAM asset upload fires multiple events — the asset node, each rendition, the metadata node. Without narrowing, one upload starts N workflows. Pin the glob to a specific descendant (e.g., /jcr:content/renditions/original) when you only want one trigger per upload.
• Avoid infinite loops. A workflow whose process step writes to a path the launcher watches will re-trigger itself. Default strategy: tag the JCR Session with setUserData("changedByWorkflowProcess") before the write so WorkflowLauncherListener ignores the resulting events. The session parameter on WorkflowProcess.execute() is a WorkflowSession, not a JCR Session — adapt it first: javax.jcr.Session jcrSession = session.adaptTo(javax.jcr.Session.class); jcrSession.getWorkspace().getObservationManager().setUserData("changedByWorkflowProcess");. If you write through a service-user ResourceResolver instead, tag that resolver's underlying Session — it is a different Session instance and the flag does not propagate. This is the most robust pattern (works across model changes, no static config to keep in sync). Use the launcher's excludeList only when you can statically name every model that might re-trigger; use a JCR property flag when the workflow writes to a different node than the launcher watches. See condition-patterns.md for code.
• Use transient workflows for high-volume launchers. Set transient="true" on the workflow model (see workflow-model-design Architecture Considerations). Persistent workflows in this regime bloat /var/workflow/instances quickly.
• Disable broad launchers in lower environments. A broad-match OOTB or custom launcher active in dev/stage with the same content as prod can fire on every content sync, masking real prod-vs-dev behavior. Either disable in lower envs (enabled={Boolean}false overlay), package the launcher under config.author/ for run-mode restriction, or restrict with conditions tied to a prod-only marker.
• Stack mechanisms cautiously. Pairing a Workflow Launcher with a Replication Trigger on the same content fires two workflows per content change. Pick one mechanism per content event.

Debugging Launchers (6.5 LTS)

Local development only. The curl -u admin:admin example below targets a local author at localhost:4502 with the default admin password. Never run it against a shared, stage, or production instance, and never with default admin:admin credentials outside an isolated dev box.

• Tools → Workflow → Launchers UI — lists all active launchers, interactive enable/disable
• Check /conf/global/settings/workflow/launcher/config/ and /apps/settings/workflow/launcher/config/ in CRXDE Lite
• Felix Web Console → OSGi → WorkflowLauncherListener service
• Check /var/workflow/launcher/ for active event registrations
• Run curl -u admin:admin http://localhost:4502/etc/workflow/launcher.json to list all

Verifying the Launcher

After deploying a launcher, confirm it's loaded and firing:

When the launcher doesn't fire

If the event happens but no instance appears:

• Most common: the glob doesn't match the actual event node path. The event for a DAM asset upload fires on the dam:AssetContent node (/content/dam/.../jcr:content), not on dam:Asset itself. Inspect the event node path in CRXDE before tuning the glob.
• Node type mismatch: the nodetype= doesn't match the event node's primary type. Confirm in CRXDE.
• Path resolution: a same-named launcher node at higher-priority /conf/global may shadow the one you deployed at /apps/. Check the resolution order in Launcher Storage Paths above.
• Globally excluded path: events under specific paths are ignored regardless of launcher config — see condition-patterns.md.

If the launcher fires (you see the log line) but the workflow doesn't progress, the issue is downstream — most commonly a referenced WorkflowProcess is not registered (see workflow-development Dependencies). For full diagnosis: workflow-debugging.

References in This Skill