Integration and orchestration systems: an operating guide

Connected is not the same as reconcilable

A stack that has reached this point is usually already connected in some form. Records move, automations fire, dashboards populate. The question an integration system answers is narrower and harder: when two systems disagree, which one is right, how would anyone notice, and what happens to the work that was done in the system that lost.

That question is architectural, not tooling. It is decided by six things — the interface contract, the event surface, the identity key, the retry semantics, the terminal state and the write-back path — and each of them is chosen once, usually early, and inherited by everything downstream.

Integration and orchestration are different layers

Integration is data movement: a record leaves one system and arrives in another. Orchestration is process coordination: a sequence of steps across several systems, with an explicit order, an owner for each step, and defined behaviour when a step fails or never completes. A stack can be thoroughly integrated and entirely unorchestrated — each hop works on its own, and nothing owns the outcome when one hop does not.

What the domain owns

• Interface contracts. What each system promises to accept and return, and which side owns each field. Contested field ownership is a design decision, not a bug to be discovered later.
• [Documented event surface](/glossary/documented-event-surface/). The state changes a platform publishes as subscribable events. A change the vendor does not publish cannot be reacted to — only polled for, or noticed by a person.
• Identity keys. The value that lets a record in one system be matched to a record in another. Event specifications make this explicit: a producer must ensure the combination of `source` and `id` is unique per event, and a consumer may treat a repeated pair as a duplicate ^{[cloudevents_spec]}.
• Retry and idempotency semantics. Whether repeating a request is safe. A method is idempotent when the intended effect of several identical requests is the same as the effect of one ^{[rfc9110_idempotent]}. Where the underlying operation is not idempotent, providers document an explicit key mechanism instead ^{[stripe_idempotency]}.
• [Terminal state](/glossary/terminal-state-configuration/). The status a record is left in when a sequence stops trying, and which systems are told about it.
• [Write-back path](/glossary/write-back-gap/). The return route from a downstream or edge system into the system of record. Where it is absent, the record stays internally consistent and quietly incomplete.

Retry safety is a property of the contract, not the tool

Retries happen in normal operation — a timeout, a rate limit, a redeploy. What differs is whether retrying is safe. RFC 9110 defines an idempotent method as one where the intended effect of multiple identical requests matches the effect of a single request, which is why retry logic is usually built around those methods ^{[rfc9110_idempotent]}.

Creation is the common exception, and providers address it explicitly rather than by convention. Stripe documents a caller-generated idempotency key: the first request under a key has its status code and response body stored, later requests with the same key return that stored result, keys may be pruned after at least 24 hours, and reusing a key with different parameters is an error ^{[stripe_idempotency]}. That is one provider's documented behaviour. Other platforms differ, and the specific semantics have to be read rather than assumed.

How this owner differs from nearby routes

A maintainable implementation sequence

1. Name the system of record for each entity, and write down which side owns each contested field.
2. Read the vendor documentation and list the events that are actually published, separately from the events the design assumes.
3. Decide the identity key at the outward hop, before records leave; reconciling on names and dates afterwards is additional work that deciding a key once avoids.
4. Establish whether each write is safe to repeat, and where it is not, adopt the provider's documented key mechanism ^{[stripe_idempotency]}.
5. Define the terminal state for every bounded sequence, and give it an owner or a queue.
6. Specify the write-back path in the same change as the outward path, not as a later phase.
7. Verify by reconciliation: list transactions in the external system and compare them against the record.

What can be verified

A source and configuration review can establish which events a vendor documents, which are enabled on an account, which identity key is in use, whether a write path has a documented idempotency mechanism, what terminal state a sequence writes, and whether a return path exists. Reconciling an external system against the record establishes whether entries are missing. Those are implementation facts.

It cannot establish that a vendor lacks an undocumented capability, that missing entries would have changed a decision, or that any revenue, conversion or efficiency outcome followed from closing a gap. Those require internal verification, and none is claimed here.

Next diagnostic step

Use the Integration & Orchestration Systems domain to locate the capability in the portfolio. Use Revenue Scan when the next question is whether the current public surface shows observable gaps. Revenue Scan remains the sole public diagnostic owner; internal integration state requires access and is confirmed separately.