CIRCUIT

AEM Custom Workflow Process: Making REST Calls from Java Steps

Adobe Experience Manager workflows often need to communicate with systems outside the repository. A DAM approval may need to notify a product information platform, an asset workflow may send metadata to an AI service, or a publication step may update an ecommerce catalogue. A Java workflow process is a practical way to perform that integration while keeping the action inside AEM’s authoring and governance model.

The implementation must be more deliberate than simply opening a URL from an execute() method. A reliable AEM custom workflow process needs controlled service configuration, authenticated HTTP requests, sensible timeouts, useful logging, and a clear response strategy. Those concerns matter particularly for Australian teams supporting distributed authors in Sydney, Melbourne, Brisbane, and Perth, where time zones, network paths, and operational coverage can affect workflow behaviour.

Choose The Right Workflow Boundary

An AEM workflow process is usually an OSGi service that implements WorkflowProcess. Its execute method receives the workflow session, a WorkItem, workflow metadata, and an args string. The process can read the payload, inspect workflow data, build a request, call a remote endpoint, and decide whether the step has succeeded.

Keep the step focused on orchestration rather than turning it into a complete integration platform. The workflow should identify the business event and pass a well-defined request to a dedicated client service. That separation makes the HTTP code testable, allows another component to reuse it, and prevents the process class from becoming tightly coupled to one vendor’s API.

The payload may be a DAM asset path, a page path, or a JCR node. Use a service user and a restricted subservice mapping to access repository data. Avoid relying on the workflow initiator’s permissions, because a scheduled workflow or system-triggered launch may have no meaningful human identity. Fetch only the metadata required for the outbound call.

Configure HTTP Access Through OSGi

Endpoints, credentials, connection limits, and timeout values belong in OSGi configuration, not in Java source code or workflow model arguments. A configuration can define the target URL, connection timeout, socket timeout, maximum response size, and whether a particular environment is enabled. Developers can then use separate values for local AEM, test, staging, and production.

For modern AEM as a Cloud Service projects, use the supported OSGi configuration approach and secret handling provided by the deployment pipeline. On older AEM 6.x installations, an OSGi configuration factory or an Apache HttpComponents-based client may be appropriate. Do not assume that a library available in a local Maven build is available in the deployed author instance; package dependencies correctly and check for version conflicts.

A simple service contract might expose a method such as sendAssetUpdate(AssetUpdate update). The workflow process creates the DTO, while the client adds headers, serialises JSON, executes the request, and maps the result to a small response object. This structure also makes it easier to replace a basic REST client with a platform-approved integration layer later.

Implement The Java REST Step

The process should validate its inputs before making a network call. Confirm that the payload exists, that the required metadata is present, and that the endpoint is configured. A missing SKU or empty asset path should produce a clear workflow error, not an HTTP request that is guaranteed to fail.

A typical implementation uses an injected client service and records a correlation value for each call:

@Component(
    service = WorkflowProcess.class,
    property = {
        "process.label=Send Asset Update"
    }
)
public class SendAssetUpdateProcess implements WorkflowProcess {

    @Reference
    private AssetApiClient assetApiClient;

    @Override
    public void execute(WorkItem item, WorkflowSession session,
                        MetaDataMap args) throws WorkflowException {
        String payload = item.getWorkflowData().getPayload().toString();

        if (payload.isBlank()) {
            throw new WorkflowException("Workflow payload is missing");
        }

        try {
            ApiResult result = assetApiClient.send(payload);

            if (!result.isSuccessful()) {
                throw new WorkflowException(
                    "Remote service rejected the asset update: "
                    + result.statusCode());
            }
        } catch (ApiClientException ex) {
            throw new WorkflowException("Asset update request failed", ex);
        }
    }
}

The actual HTTP client should use a pooled connection manager where appropriate, set Content-Type and Accept headers explicitly, and close response bodies in every path. Treat only the expected 2xx responses as success. A 401 or 403 usually indicates a credential or permission issue, while a 400-series validation response should be handled differently from a 500-series temporary outage.

Use an idempotency key when the remote API supports one. A workflow may be restarted manually, retried by an operator, or resumed after an instance interruption. Without idempotency, the same asset event could create duplicate records or send repeated notifications. A combination of the workflow instance ID, payload path, and business revision can provide a useful key.

Protect Reliability And Sensitive Data

Remote calls introduce failure modes that do not exist in a local repository operation. DNS errors, TLS negotiation problems, slow vendor responses, rate limits, and partial outages can all leave a workflow suspended. Set finite connection and read timeouts; an unlimited wait can consume worker threads and create a larger incident than the original API outage.

Retry only transient failures, and use a small bounded number of attempts with backoff. Do not retry invalid JSON, missing credentials, or a 400 response. If the endpoint is not designed for synchronous workflow execution, consider an asynchronous queue or an intermediate integration service. AEM can then complete the authoring step while a separate consumer manages delivery and retry policy.

For Australian organisations, outbound data handling deserves close attention. The Privacy Act 1988 and the Australian Privacy Principles may apply when an asset workflow sends personal information to a third-party platform. Keep payloads minimal, document the destination, and confirm contractual and hosting arrangements. If the provider offers an AWS Sydney region, that may help with latency and residency decisions, but regional hosting alone does not settle every privacy obligation.

Never write access tokens, API keys, full request bodies, or personal data to ordinary AEM logs. Use a secret store or deployment-managed secret, rotate credentials, and redact identifiers where possible. If the API requires OAuth, cache tokens only for their permitted lifetime and protect the token exchange with TLS certificate validation rather than disabling checks to solve a development problem. For teams following Australian business hours, alerts should also account for handover between eastern states and Western Australia.

Test And Operate The Integration

Test the process at several levels. Unit tests should cover missing payloads, malformed metadata, successful responses, rejected requests, timeouts, and retryable failures by mocking the client service. An integration test can run against a stub server that returns controlled status codes and deliberately slow responses. This verifies that the client closes connections and honours its timeout settings.

AEM-specific testing should include an actual workflow model, a service-user mapping, and representative DAM or Sites payloads. Check that permissions work on an author instance and that the process behaves consistently when launched by a scheduler. For a repeatable local setup, teams can use Docker development environments to standardise supporting services, mock APIs, and developer configuration without pretending that a container is an exact production equivalent.

Observability should show the workflow instance, process name, remote operation, duration, response class, and correlation ID. Metrics for success rate, latency, timeout count, and retry count are more useful than a large volume of raw log lines. AEM teams managing high-volume media pipelines may also choose to store a delivery status on the asset or in an external tracking system.

Practical Recommendations For Production

Use these practices when moving a Java REST workflow step beyond a proof of concept:

  • Keep endpoint URLs, timeouts, credentials, and feature flags in environment-specific OSGi configuration.
  • Access repository content through a least-privilege service user rather than the workflow initiator.
  • Validate payloads and required metadata before opening an HTTP connection.
  • Add bounded retries, backoff, idempotency keys, and explicit handling for 2xx, 4xx, and 5xx responses.
  • Redact secrets and personal information from logs, traces, exception messages, and workflow metadata.
  • Monitor latency, failures, queue depth, and remote rate-limit responses with alerts that cover Australian support rosters.
  • Consider an asynchronous integration pattern when the external service is slow, rate-limited, or business-critical.

Binary-heavy workflows also need an appropriate storage design. If the REST step sends asset references or triggers downstream processing, review S3 binary storage patterns rather than loading large files into memory. Passing a signed object reference can reduce request size, improve throughput, and keep the workflow worker focused on orchestration.

A production runbook should explain how to identify a failed instance, replay a safe request, rotate credentials, and contact the external provider. Include the relevant Australian public holiday and after-hours arrangements if the integration supports a customer-facing service. For retail and media businesses whose publishing peaks align with local campaigns or evening traffic, capacity tests should reflect real usage rather than a quiet developer environment.

A well-designed AEM custom workflow process makes a REST call predictable: configuration controls the environment, a dedicated client controls transport, the workflow controls business progression, and monitoring exposes the result. Build the Java step with those boundaries from the beginning, validate it against realistic AEM permissions and Australian privacy requirements, and document the replay path before the first production failure. That approach turns a fragile outbound request into an integration that authors and operations teams can trust.