What should an integration requirements document contain?

An integration brief should explain which business event moves information between which systems, which source is authoritative and how the team will detect missing, duplicated or incorrect records. Name the owners, access requirements, data mapping, update timing, exception process and acceptance evidence before requesting implementation estimates.

A list of applications is a starting point. The requirements need to explain what should happen between them. For delivery scope, see Watabe’s systems integration service.

Describe one business event from start to finish

Choose a specific event, such as an approved application or an updated invoice status. Describe what triggers it, which system records it first, where the information must appear and who depends on the result. Separate that event from related processes that are outside the first release.

Illustrative example: an approved invoice in a finance system updates an internal reporting dashboard. The finance system owns the invoice amount and status; the dashboard displays that information and does not edit it. This example uses no client data and is not a delivered-project claim.

Record the systems, owners and access constraints

  • The name and purpose of each source and destination system.
  • The business owner, technical contact and person authorised to approve access.
  • The available interface, documentation, test environment and provider support route.
  • Known limits, licence dependencies, account approvals and planned system changes.
  • The data that may be shared, the permitted users and the agreed retention requirements.

Keep passwords, API keys and personal records out of the requirements document. Agree a separate approved process for access and use representative, non-sensitive test data when possible.

Define the data mapping and source of truth

Prepare a mapping entry for each required field. Include the source name, destination name, meaning, format, whether it is mandatory, any transformation and what should happen when it is missing or invalid.

In the invoice example, the mapping needs an invoice identifier, amount, currency, status and update time. The identifier links both systems’ records; the currency gives the amount its meaning; and the update time or agreed version rule helps determine whether an arriving change is newer than the value already held.

Agree the treatment of dates, time zones, empty values, corrections and deleted records. If two systems can edit the same information, define a conflict rule and escalation owner. Do not leave the developer to infer which department’s value should win.

Specify failures, retries and reconciliation

Describe the expected normal timing and the acceptable delay. Then specify the cases that can leave systems out of step.

A request times out
How will the integration determine whether the destination accepted it? Agree a safe retry approach that avoids repeating the business action unintentionally.
The same event arrives twice
Define the identifier or other rule used to detect duplicates and the evidence retained for investigation.
An older update arrives late
Agree whether it should be ignored, recorded for review or applied according to a documented business rule.
A record fails validation
Specify where it is held, who is alerted, what they can correct and how processing resumes.
A connection is unavailable
Define the queue or alternative operating process, monitoring, recovery steps and responsibility for outstanding records.

Include a reconciliation method: compare agreed counts, identifiers, states or totals between the source and destination for a defined period. Logging a successful request is not always enough to establish that the business records agree.

Write acceptance tests before comparing estimates

For each test, state the starting condition, event, expected result, evidence and approving owner. Cover a normal record, a missing required field, a duplicate, a timeout, an out-of-order update and recovery after an interruption where relevant.

In the illustrative invoice scenario, a repeated update should leave one agreed dashboard record with the expected status. A failed record should appear in the agreed exception process. A reconciliation check should explain every difference within the test’s scope.

The supplier should confirm which cases are covered and which depend on third-party behaviour. Agree expected volumes, permission checks and support responsibilities as part of the scope.

Prepare the handover and change plan

Name the owner for monitoring, failed-record review, access renewal and future mapping changes. Request the agreed configuration notes, support contacts, test evidence and recovery instructions. Record which provider or licence costs recur and how changes to an upstream system will be assessed.

If the main difficulty is the approval process itself, review business process automation before connecting it. If the destination is a management report, include the reporting requirements in the same discussion. You can send an integration brief to Watabe once the systems, owners and first business event are clear.