Adovo

AEM Sites Playbook, Chapter 14: Integrations, APIs and data exchange

Can connected systems exchange data correctly through failure and replay?

November 10, 2026

Write the contract before connecting systems

Use this chapter for PIM imports, external content consumers, CRM/Forms/Commerce handoffs or Adobe Experience Cloud integrations. List the sending and receiving systems, data owner, operation, identifiers, schema, expected frequency and failure owner. Confirm the supported API and authentication method for the precise operation.

Separate transport success from business completion. Receiving an update does not establish that AEM applied it, a reviewer approved it or the intended channel delivered it. Define the checkpoint at which each system acknowledges responsibility and the evidence another operator can use for reconciliation.

For the hypothetical product import, agree which system owns product facts and which fields editors control. Include deletion, local overrides and missing references. The Salsify discussion explores architecture options without a confirmed final implementation. Avoid importing its proposed volumes or batch sizes as benchmarks.

Resolve authentication and permission boundaries

Check the API family, environment enablement, credential type, account/product-profile association, client configuration and action/path permissions. Adobe's OpenAPI overview, setup procedure and OAuth invocation tutorial describe separate requirements. The Assets tutorial is not a generic recipe for creating Sites pages.

The App Builder/Sling POST discussion demonstrates the distinction. The author could use Content Fragment APIs but received authorization errors for other operations; adding a custom servlet did not resolve rejection before its internal service identity ran. The accepted reply was followed by the author's correction. Do not invent an API scope, assume a missing entitlement or reuse a token for an unrelated interface without checking current documentation.

Keep development diagnostics separate from production authentication. Store and rotate credentials through approved mechanisms. Record denied/expired credentials as test cases; do not describe a different token or route as a bypass around an unresolved access-control requirement.

Design for retries and partial failure

Give an update a stable business identifier and an understood version/order rule. Decide what a repeated request means and how the receiver recognizes already-applied work. Define bounded retry, failure retention, operator intervention and reconciliation. Test interruption between accepting input and recording completion.

Cloud Service custom work must tolerate clustered execution and interruption. Adobe describes resumable, cluster-aware development and at-least-once Sling Jobs. The fixed-Publisher migration case does not establish exactly-once external delivery merely by selecting a leader. Make duplicate handling part of the receiving contract and test it during relevant deployment/retry conditions.

Simulate an unavailable receiver, malformed payload, duplicate, older event arriving late, missing dependency and partial batch success in non-production. Confirm whether replay corrects the state or overwrites newer/editor-owned data. Show an operator how to inspect and resolve the failed record without reprocessing an entire successful batch.

Choose an interface for the business operation

Community discussions distinguish permission to invoke an operation from correctness when it repeats or is interrupted. The authorization example leaves the final access problem unresolved, while the migration example does not prove its delivery guarantee. Test both contracts separately.

Scroll horizontally if needed.

Choose an interface for the business operation: table 6
DecisionOptions to compareRequired evidence
Where data is transformedBefore AEM, within supported AEM code, or at the consumerOwnership, resource behavior and failure/replay contract
How content is managedCurrent supported management API or another documented operationExact operation, environment enablement and action/path authority
How content is deliveredAppropriate delivery API/rendering pathAudience, fields, cache/freshness and withdrawal behavior
How updates are orderedExplicit source version/order or another agreed conflict ruleRepeated and out-of-order inputs give the intended state
Where failures are retainedApproved operational record/queue with an ownerFailed work is identifiable and can be reconciled safely

Do not choose a particular API merely because a related operation succeeded. Management, delivery, authentication and repository authority have separate acceptance evidence. Use API setup and credential distinctions for the actual family; do not invent a missing scope from a reply.

Worked scenario of replay after a lost acknowledgement

This hypothetical integration receives approved product updates from a source system. Each update carries a stable business identifier and an agreed source version. Regional descriptions are editor-owned. The receiver must tolerate the caller retrying when its acknowledgement is lost.

The team agrees a behavioral contract before implementing a particular queue or service:

Scroll horizontally if needed.

Worked scenario of replay after a lost acknowledgement: table 9
InputRequired receiver behavior
First valid approved updateApply the permitted source-owned changes and retain its outcome
Identical repeated updateRecognize prior work or produce the same intended state without a duplicate
Older update after a newer oneFollow the agreed version/conflict rule; do not silently restore stale facts
Update that conflicts with local ownershipPreserve protected editorial content or retain a visible conflict
Partially failed batchIdentify successful and failed records so replay does not erase success
Denied or expired credentialFail without unintended changes and identify the access issue

Engineers test an interruption after the write but before acknowledgement, a repeat after restart and two different source versions arriving in reverse order. They verify the actual resulting content and operator record. A process that merely returns success on the second request is insufficient if the first request created a duplicate.

Suppose the hypothetical trial applies one update, loses acknowledgement and receives a retry. The content remains one logical object with the intended values. A later older event is retained as stale according to policy. A separate record fails because a required reference is missing; an operator can identify and replay only that record after correction.

Scroll horizontally if needed.

Worked scenario of replay after a lost acknowledgement: table 11
Acceptance checkIllustrative resultDecision
Lost acknowledgement and retryIntended state remains singularPass for the tested interruption
Older eventDoes not overwrite the newer approved statePass for the agreed order rule
Local descriptionPreservedOwnership requirement passes
Missing dependencyVisible failed record with a successful focused replayOperator path demonstrated
Credential revocationDenied without writesAccess requirement passes

The owner approves a bounded rollout with the tested schema/volume and monitored reconciliation. Capacity outside that tested range remains a separate question. No exactly-once external guarantee is inferred from this trial or from at-least-once job execution.

Make reconciliation a business control

Compare source intent, accepted input, applied state and delivered output at agreed checkpoints. A successful transport count can hide rejected records, mismatched identifiers or content not approved for publication. Decide how differences are classified and which team corrects each class.

Record the integration's authoritative input, completion checkpoint, retry policy, dead/failed-work handling, operator permissions and escalation. Include the downstream content/publication owner so an integration engineer does not independently authorize customer-visible facts.

Before handover, ask an operator who did not write the integration to diagnose a prepared failure, identify affected content and complete a permitted replay. Retain the steps and evidence. A replay mechanism that requires a developer to edit production data by hand is an unresolved operating dependency, even when the normal path is reliable.

Accept the end-to-end operation

Complete W14 with contracts, credentials/permissions by reference, retry/replay rules, reconciliation and ownership. Validate the resulting content with editors and an actual consumer. A successful Author API call does not establish public availability; follow chapter 10 through publication and chapter 11 through delivery. Treat integrations with other Adobe products as explicit interfaces with their own prerequisites, not implied capabilities of every AEM installation.

W14 API and integration contract

Use with chapter 14. Make replay and reconciliation part of the contract.

Scroll horizontally if needed.

W14 API and integration contract: table 16
RecordEntry
Sending/receiving system, operation and business completion checkpoint[enter]
Schema, stable identifier, version/order and field ownership[enter]
Documented API family, environment, account/profile and permissions[enter]
Credential mechanism/reference, rotation and denied/expired tests[enter]
Duplicate, older event, timeout, partial success and replay behavior[enter]
Reconciliation, failure retention and operator intervention[enter]

Continue exploring

Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 1: Strategy, value, ownership and adoption

What outcome justifies the work, and who will operate it?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 10: Preview, publication, scheduling and withdrawal

How do we release and remove the complete approved experience?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 11: Delivery, Dispatcher, CDN, domains and caching

Which layer controls the request, redirect or stale response?

Read more
Explore data and analytics services →