Custom AEM workflow steps with Java and ECMA scripts
Adobe Experience Manager workflows coordinate repeatable business processes, from content approval to asset publication. A custom workflow step adds domain-specific logic at a chosen point in that process, letting teams move beyond generic branching and assign work to a repeatable implementation.
Two implementation paths are common: a Java class exposed through an OSGi service, and an ECMA script stored with the workflow. Both can read workflow variables and influence the outcome, but they offer different levels of access, testability and long-term support.
The right choice depends less on personal preference than on where the step will run, what it must integrate with, and how often its rules change. A clear design also prevents a seemingly small automation from becoming an invisible dependency across publishing operations.
For Australian organisations, geography, privacy duties and regulated customers make those operational questions especially concrete. Workflows often serve teams spread across Sydney, Melbourne, Brisbane and Perth, where stand-ups, daylight-saving changes and approval handovers affect timing.
Java and ECMAScript: choosing the right execution model
Java offers stronger integration options and is the safer default for new AEM workloads. ECMA scripts remain useful for maintaining existing models, especially simple decisions that can be expressed within the workflow script APIs.
| Approach | Strongest use | Execution context | Main trade-off |
|---|---|---|---|
| Java | Complex rules and service integrations | OSGi bundle deployed with the application | More build, dependency and test work |
| ECMA scripts | Small steps in maintained legacy workflows | Script stored with the workflow model | Restricted APIs and deprecated support in newer AEM deployments |
A Java step can use injected OSGi services, call approved APIs and participate in normal dependency management. That makes it suitable for reading a customer record, invoking a publishing service or recording a business identifier beyond the workflow itself.
An ECMA script is quicker to place beside a model and easier for some content teams to review. Its constraints are equally important: code execution should remain focused on workflow data, with no hidden network calls or reliance on unrestricted access to the server.
For a wider view of AEM application structure, the Le Bastingue platform illustrates how components, services and build pipelines can be organised together. It is useful context when deciding whether a step belongs in a reusable application module or directly in a workflow model.
Designing steps around business decisions
Begin with the business decision, not the language. Write down the step’s inputs, expected outputs, participants, error states and whether an operation can safely be repeated. This turns an informal approval rule into a contract that Java, ECMA scripts and testers can share.
Keep orchestration in the workflow and domain logic behind clear interfaces. For example, a step can ask an order service for a status, then record the result for the next participant. The workflow should not become a place where unrelated business rules accumulate.
Content movement needs special care. CIRCUIT’s blueprint and live copy session offers useful architectural context: code, configuration and content references should remain aligned when experiences are copied or promoted. A step that rewrites paths must respect those boundaries.
Building a Java step for production
In AEM, a Java workflow step normally implements the Granite WorkflowStep contract or extends AbstractWorkflowStep. Its execute method receives the current session and configuration, providing access to workflow variables, metadata and the payload through the relevant APIs.
Package the implementation as an OSGi bundle and deploy it with the application’s content package. The Sling application and workflow model then need a step descriptor that references the configured implementation. Separating deployment from model configuration lets operations promote the model without rebuilding business logic.
Production behaviour matters more than a successful demonstration. Validate required variables before making external calls, use bounded timeouts and make retries safe through idempotency keys. Raise a workflow failure when the required outcome cannot be confirmed, rather than letting the process continue on an unchecked assumption.
Using ECMA scripts for lightweight automation
ECMA scripts are the older, lighter-weight option for extending AEM workflows. A script can examine variables, apply a condition and set a value, which makes it convenient for small routing or validation tasks already represented in a model.
Because scripts live in the repository, changes follow the same application packaging discipline as other AEM code. Keep them readable, avoid duplicating large business libraries and limit their work to operations supported by the workflow scripting APIs. Long-running or privileged integration belongs elsewhere.
ECMA script workflow steps are deprecated for newer AEM deployment models. They can remain reasonable for a maintained legacy workflow, but new AEM as a Cloud Service projects should plan around Java steps and verify the extension points available in their target release.
Planning integrations and Australian operating conditions
A step often crosses boundaries: AEM content, an external platform, identity, analytics or a publishing target. Keep each dependency narrow and give the workflow a stable contract. Microservices can own durable business processing; the AEM step can coordinate the request and persist enough state to resume safely.
Australian operating conditions deserve explicit tests. Teams in Perth may start work before Sydney, and daylight-saving differences between eastern states can turn an overnight timeout into a visible delay. Retries should therefore tolerate a normal gap between one business day and the next.
The Privacy Act 1988 and the Australian Privacy Principles also affect workflow data. If a step copies customer or employee information into variables, apply purpose limitation, data minimisation, security and access controls. Australian banking, health and government projects may add contractual or agency-specific requirements that should shape what the workflow stores.
A reliable workflow step checklist
A short pre-release review catches the failures that become expensive once content is moving through production. The following checks apply to both new implementations and legacy scripts being carried forward.
- Define inputs, outputs, branches and failure states before writing implementation code, then have a business owner confirm the rules.
- Keep executable code under the application area, configuration separate and content outside both, following AEM’s established repository conventions.
- Handle absent, stale and malformed workflow variables without allowing the model to continue with a partially applied operation.
- Use timeouts, bounded retries and idempotency for every external write, and distinguish temporary failures from permanent business rejections.
- Test the Java service with unit tests, exercise the model in an integration environment and preserve regression cases for maintained ECMA scripts.
- Log correlation identifiers and processing outcomes without writing sensitive personal information into logs or workflow history.
- Record the target AEM release, deployment method and legacy-script migration decision so future teams know why the implementation exists.
The checklist is also a useful review tool for people exploring adjacent model-driven tooling. The XtextCon conference brings together work on languages, editors and developer experience, offering ideas that complement AEM workflow design even though the execution environments are different.
Turning conference ideas into working automation
Conference material is most valuable when turned into a small, testable change. Revisit the relevant CIRCUIT sessions, choose one workflow with clear business value and reproduce its core rule in a safe environment before broadening the scope.
The CIRCUIT event companion provides a place to find event information and revisit the programme around the technical sessions. Choose one step, document its contract, implement it in Java where appropriate, test the failure paths and share the result with your delivery team.