AEM Workflow Custom Process Steps for External Calls
Adobe Experience Manager workflows often begin as straightforward content operations: a page is submitted, an asset is reviewed, or a publication task is assigned. The design becomes more demanding when the workflow must call an external service, such as a product catalogue, translation platform, CRM, payment gateway, analytics endpoint, or internal approval system.
A custom process step gives an AEM implementation a controlled place to make that call. With the right Java service, error handling, security model, and operational safeguards, teams can connect AEM to other systems without turning an authoring workflow into a fragile chain of hidden dependencies.
Where External Calls Fit In An AEM Workflow
An AEM workflow is made up of steps that pass a payload and metadata through a defined process. A custom process step can retrieve the payload path, read workflow metadata, build a request, invoke an external API, and record the result for later steps. This approach is useful when the integration requires business logic that is not available in the standard workflow components.
Common examples include sending approved content to a headless delivery service, notifying a marketing platform when a campaign page is published, or creating a support task in an external ticketing system. The process step should have a single, clear responsibility. Validation, request construction, and response handling can be separated into services so the workflow code remains testable.
The conference agenda provides useful context for the wider AEM engineering topics that sit around this pattern, including integrations, architecture, and Java development. Those concerns matter because a workflow call is part of a production platform, not simply a small script attached to an authoring screen.
Building The Custom Process Component
A custom process step normally implements the AEM workflow process contract and is registered as an OSGi service. Its execute method receives the workflow session, work item, metadata map, and arguments configured in the workflow model. The implementation can then identify the current payload and pass it to a dedicated integration service.
Configuration should be externalised through OSGi rather than embedded in Java or stored as plain-text workflow arguments. Endpoint URLs, connection timeouts, service-user mappings, feature flags, and safe retry limits belong in environment-specific configuration. In an Australian deployment, this separation is especially valuable when development runs in Sydney while production services operate in Melbourne, Singapore, or another regional location.
Keep repository access and HTTP communication distinct. A repository-facing service can read the approved content and create a minimal data transfer object, while an API client handles authentication, headers, serialisation, and response parsing. This division makes unit testing easier and reduces the risk of accidentally serialising internal JCR properties into an external request.
Preparing A Reliable API Request
Before making a request, validate the payload and the fields required by the receiving system. A missing title, identifier, locale, or publication state should create a meaningful workflow failure rather than an opaque remote-service error. The process should also confirm that the current content is eligible for the operation, preventing an author from sending an unapproved draft to a downstream platform.
Use a supported HTTP client and define connection, read, and overall execution timeouts. Authentication may involve OAuth 2.0 client credentials, signed requests, mutual TLS, or a managed token service. Secrets should be stored using the platform’s protected configuration facilities or an approved secret manager. Logging an access token, full customer record, or sensitive authoring data is unacceptable.
Payload design deserves careful attention. Send the smallest useful representation, include a correlation identifier, and state the schema version where the receiving API supports it. For Australian organisations, privacy obligations under the Australian Privacy Act and Australian Privacy Principles can affect what content or personal information is sent to overseas processors. Legal, security, and data-residency requirements should be settled before the workflow is wired to a live endpoint.
Handling Failures, Retries, And Timeouts
An external call can fail because of a network interruption, a 401 response, a malformed request, a rate limit, or a remote service outage. These conditions should not all be treated the same way. A 400 response usually requires content or mapping correction, while a 429 or temporary 503 may be suitable for a delayed retry.
A robust process step classifies errors and records a concise failure reason in workflow metadata or an operational log. It should fail the step when human intervention is needed, allowing an administrator to inspect the payload and restart safely. For transient failures, a bounded retry strategy with increasing delays is preferable to an immediate loop that consumes AEM threads.
A workflow timeout must be shorter than the timeout of the caller or queue that initiated it. Long-running external operations should generally be asynchronous: submit a request, store a correlation ID, and use a callback, polling job, or separate reconciliation process. Blocking an authoring workflow while a remote system processes a large translation or catalogue export can create a poor experience across busy Australian business hours, particularly when teams span Perth, Adelaide, Sydney, and Brisbane.
Making External Calls Safe To Repeat
Retries create a key design issue: the same request may be sent more than once. If the external operation creates an order, ticket, campaign, or publication record, duplicate execution can cause real business damage. Idempotency keys should be derived from a stable content identifier, workflow purpose, and version, rather than from the current timestamp.
The receiving API should support an idempotent operation where possible. If it does not, the integration can store a request status in a controlled repository location or an external tracking store. Before creating a new record, the service checks whether the same content version has already been accepted. Updating an existing record is often safer than creating a new one on every workflow retry.
Use service users with the minimum repository permissions needed to read content and write integration status. Avoid granting broad administrative access because a process step happens to run under a technical account. Audit entries should identify the content path, workflow instance, remote system, response category, and correlation ID without exposing personal information.
The speaker sessions from the CIRCUIT community also reflect why architecture and systems engineering matter here. An integration that works in a developer environment can still fail under dispatcher caching, clustered author instances, network controls, or a busy publication pipeline.
Testing And Operating The Integration
Test the custom process step at several levels. Unit tests should cover payload extraction, validation, authentication failures, response mapping, and retry classification. Contract tests can verify that the generated request matches the external service’s schema. A controlled integration environment should exercise timeouts, duplicate requests, rate limits, malformed responses, and remote downtime.
Avoid depending on a real third-party API in every automated build. Use a mock server for predictable scenarios, then schedule a smaller set of environment tests against the partner system. Include content with Australian date formats, Australian English spelling, UTF-8 characters, GST-related fields where relevant, and time-zone transitions. These details often expose assumptions hidden in an otherwise successful integration.
Operational visibility is just as important as implementation quality. Monitor call counts, latency, response classes, retry volume, and workflow failures. Alerts should distinguish a single bad content item from a widespread outage. In the local market, an organisation may have a tightly managed enterprise API gateway, while a smaller retailer or agency may rely on a SaaS platform with strict monthly quotas; the process step needs controls suited to that commercial reality.
A practical design can be summarised as follows:
| Concern | Recommended approach | Risk reduced |
|---|---|---|
| Configuration | OSGi configuration and protected secrets | Credential leakage and environment drift |
| Request handling | Dedicated API client with validation and timeouts | Unclear failures and blocked workflow threads |
| Transient errors | Bounded, classified retries | Unnecessary duplicates and retry storms |
| Duplicate execution | Idempotency key and status tracking | Repeated orders, tickets, or publications |
| Security | Least-privilege service user and minimal payload | Excessive repository or personal-data exposure |
| Operations | Correlation IDs, metrics, and actionable alerts | Slow diagnosis and invisible outages |
An AEM workflow that calls an external service should be treated as a small distributed system. The custom process step is the boundary between AEM’s repository and a network that can be slow, unavailable, rate-limited, or changed by another team. Clear contracts, careful failure handling, and secure configuration make that boundary dependable.
For teams working across Australia, this discipline supports more than technical stability. It helps meet privacy expectations, accommodates regional operating hours, and gives content authors a predictable process whether they are working from a Sydney office, a Melbourne agency, or remotely from regional New South Wales. Build the process step around observable, repeatable behaviour, then validate it against the real API and the real publishing workflow before release.