How to Write an Integration Requirements Document That Developers Actually Use

The Document That Gets Skipped (And Why It Costs Millions)

Most integration projects do not fail because of bad code. They fail because of a bad brief.

Development teams spend weeks building connectors, mapping fields, and wiring up APIs, only to discover mid-sprint that the source system does not expose the field they assumed it would, that the target system enforces validation no one documented, or that error handling behaviour was never formally agreed upon. Each of those discoveries triggers rework, and rework in integration projects is expensive because the defect usually travels across two or more systems before it surfaces.

According to the 2025 MuleSoft Connectivity Benchmark Report, produced in collaboration with Vanson Bourne and Deloitte Digital from surveys of 1,050 IT leaders worldwide, 95% of organisations face challenges integrating systems into existing processes and 80% name data integration as their single largest obstacle. The financial impact is measurable: integration challenges drain an average of $6.8 million per year per organisation in lost productivity and delayed projects. IT teams already spend 39% of their time on custom integration work, a figure that reflects how much rework enters the development lifecycle when initial specifications are vague or incomplete.

Behind most of those losses is a documentation problem.

An Integration Requirements Document (IRD) is the contract between the business and the engineering team. When it is written with precision, developers build with confidence. When it is written vaguely, or skipped entirely, developers build twice.

This guide covers exactly what an IRD needs to contain, how to write each section so it drives implementation rather than gathering dust, and what the most common structural failures look like in practice. The technical examples are drawn from MuleSoft, Workday, and Infor environments because those are the platforms where integration complexity tends to surface most painfully.

What Is an Integration Requirements Document

An Integration Requirements Document is a structured specification that defines the complete scope of a system integration. It describes what data needs to move, between which systems, in which direction, on which schedule, under what conditions, and what should happen when something goes wrong.

The operative word is “structured.” A requirements document that exists as a thread of email exchanges, a set of Confluence notes, and a series of verbal agreements is not a document. It is a liability.

A properly structured IRD addresses seven technical areas: the business context and integration purpose, the integration pattern and transport protocol, the technical endpoint details and authentication model, the data mapping and transformation rules, the error handling and retry behaviour, the non-functional requirements covering latency and throughput, and the testing and acceptance criteria. Each of those areas is expanded below with the level of detail developers need to build from without back-and-forth clarification.

Why Most IRDs Fail Before Development Starts

Before writing a better IRD, it helps to understand exactly why existing ones get ignored.

The most common failure pattern is ambiguity presented as completeness. A business analyst produces a document that appears thorough because it is long, but the technical sections are either absent or written in business language that developers cannot translate into behaviour.

Consider a requirement like “the integration should sync employee data from Workday to the HRMS nightly.” That sentence answers none of the questions a developer actually needs answered. Which Workday REST resource? The Workers v36.2 endpoint, or the Worker Data report via RAAS? Which specific worker fields, by their exact API field name? What constitutes nightly in terms of a cron expression and time zone? Is nightly a full snapshot load or an incremental delta filtered by lastUpdatedMoment? What happens to records that exist in the target but have been terminated in Workday? Is the correct behaviour a soft-delete flag update, a hard delete, or a status field change? What is the retry behaviour when the Workday tenant returns a 503 during maintenance windows?

Every one of those questions, left unanswered in the IRD, becomes a developer assumption. Developer assumptions become production defects.

A second failure pattern is the assumption gap. Integration documents frequently assume that both systems behave the way the requirements author believes they behave. In practice, the source system may not support the query pattern assumed. Workday, for example, does not allow arbitrary SQL-style filtering on most REST resources. Fields like workdayID are immutable identifiers, but fields like employeeID are tenant-configured and may not be unique across business entities. These are not edge cases. They are documented API behaviours that an IRD author unfamiliar with the platform will routinely misstate.

A third failure pattern is missing the integration pattern entirely. An IRD that specifies what data to transfer but does not specify whether the integration is request-reply, fire-and-forget, publish-subscribe, or batch-scheduled leaves the architectural decision to the developer. That decision has downstream consequences for error recovery, monitoring, and operational support that should be agreed at the requirements stage, not resolved during build.

The 2025 MuleSoft Connectivity Benchmark reports that 80% of organisations say data silos remain their biggest barrier to automation and AI goals, and that only 28% of enterprise applications are properly integrated. The compounding effect of vague IRDs is that integration projects get deprioritised or rebuilt, which widens the silo problem rather than closing it.

Section 1: Integration Overview and Business Context

This section is the one technical teams most commonly skip because it reads as business content. That is a mistake.

Developers who understand why an integration exists make better decisions about edge cases. When an unusual data scenario arises and the specification is silent, a developer with business context can reason toward the correct behaviour. A developer with no context makes an arbitrary choice. Both developers ship code. Only one of them ships the right code.

The integration overview should answer five specific questions.

First: what business process does this integration support, and what is the upstream trigger that initiates it? “New employee onboarding” is a business process. “A new hire record reaching Active status in Workday for a worker type of Employee, excluding contingent workers and interns” is a triggerable event that can be implemented.

Second: what is the operational impact of integration downtime? Quantify it. “Payroll cannot close” is more actionable than “important.” If the business impact of an integration being down for two hours is a delayed payroll run affecting 4,000 employees, the team will make different architectural decisions about retry aggression, alerting urgency, and fallback behaviour than they would for a reporting feed that can tolerate a 24-hour lag.

Third: what is the acceptable data latency window, and is it defined by business requirement or by regulatory requirement? These are different constraints with different architectural implications.

Fourth: what are the consuming systems or teams downstream of the target system? Understanding the downstream dependency chain determines what the acceptable blast radius of a data quality issue is, which in turn governs how strict the target-side schema validation should be.

Fifth: are there any brownout or maintenance windows on either system that affect the integration schedule? Workday tenants have a weekly maintenance window that can last from four to six hours. If an integration is scheduled to run during that window, the IRD must specify the expected behaviour.

Section 2: Integration Pattern and Transport Protocol

This section is frequently absent from IRDs even though it governs fundamental architectural decisions.

Every integration can be characterised by its pattern and its transport. The pattern describes the flow of control and data. The transport describes the protocol and medium over which data moves. Both must be specified explicitly.

Integration Patterns

The four common integration patterns each have distinct implications for error handling, monitoring, and latency.

Request-reply (synchronous) means the calling system initiates a call, waits for a response, and continues processing based on that response. This pattern is appropriate when the outcome of the call determines subsequent logic. It is sensitive to target system latency and unavailability. Any MuleSoft HTTP connector operating in synchronous mode follows this pattern.

Fire-and-forget (asynchronous, one-way) means the source system publishes a message and does not wait for a response. The source system’s responsibility ends when the message is accepted by the messaging layer. This pattern is appropriate when the source and target systems need to be decoupled from each other’s availability. Workday Pub/Sub API events follow this pattern.

Publish-subscribe means one or more publishers emit events to a topic, and one or more subscribers consume from that topic independently. This pattern is appropriate when multiple downstream systems need to react to the same business event. Infor ION’s event framework uses this pattern via BOD publication to ION API endpoints.

Batch extraction and load means data is read in bulk from the source, transformed, and written to the target on a scheduled basis. This pattern is appropriate for high-volume, latency-tolerant operations. Workday EIB-based integrations and MuleSoft batch jobs both follow this pattern.

The IRD must specify which pattern applies and why. If the latency tolerance question from Section 1 was answered with “less than five minutes,” a batch-scheduled pattern cannot satisfy it. If the answer was “within the next business day,” request-reply adds unnecessary coupling with no benefit.

Transport and Protocol Specification

The transport section should specify: the protocol (REST over HTTPS, SOAP over HTTPS, AMQP, JMS, SFTP, AS2), the message format (JSON, XML, CSV, flat file), the character encoding (UTF-8 should be stated explicitly rather than assumed), and the compression behaviour if applicable.

For REST integrations the IRD should specify the HTTP method per operation (GET for retrieval, POST for creation, PUT or PATCH for update, DELETE for removal) and should not leave HTTP method selection to developer preference. A source system that uses POST for both creation and update operations (upsert via POST) needs to document that explicitly because it changes how idempotency is handled.

For SOAP integrations the IRD should reference the specific WSDL version, the operation name, and any WS-Security headers required. Workday Web Services (WWS) use versioned WSDL documents published on the Workday Community developer portal, and the IRD should pin the WSDL version rather than defaulting to the latest, since schema changes between versions can break field expectations.

For file-based integrations over SFTP the IRD should specify the directory structure, file naming convention including any timestamp or sequence number pattern, the polling interval, whether the integration uses a sentinel file (a separate signal file indicating the primary file is complete), and the file archive or deletion behaviour after successful processing.

Section 3: System Endpoints and Authentication

Endpoint Specification

Endpoint documentation should be precise enough that a developer can configure a connection without asking a single clarifying question. For each system involved, the IRD should document the base URL per environment (development, QA, staging, production), the specific resource path and HTTP method, the API version pinned for this integration, any path parameters or query parameters required, and the expected response structure including HTTP status codes for each outcome.

A weak endpoint specification looks like this: “Workday REST API, Workers endpoint, Production.”

A usable endpoint specification looks like this:

• Base URL: https://{tenant}.workday.com/api/v36.2/
• Resource: /workers
• Method: GET
• Required query parameters: format=json, limit=100 (max per page), offset={incremental}
• Optional filter parameter: updatedFrom={ISO8601 datetime} for delta loads
• Response structure: JSON array under the data key, pagination cursor in the next key
• Success response: HTTP 200 with body
• Empty result: HTTP 200 with empty data array (not 404)
• Rate limit: 1,200 calls per hour per ISU account (Workday default)

That level of specificity is what allows a developer to write the connector configuration and pagination logic without a separate discovery exercise.

For Infor LN integrations that publish BODs through Infor ION, the endpoint section should specify the ION API endpoint URL, the BOD noun and verb (for example, Sync.ReceivableTransaction), the connection point name in ION Connect, and whether the integration subscribes to ION events or queries the ION API on demand. The event-driven architecture of Infor LN and ION means that the subscription configuration is a distinct setup step from the API call itself, and both need to be documented.

Authentication Specification

Authentication documentation is consistently one of the most under-specified areas in IRDs. The specification must go beyond naming the authentication type and must document every parameter and step required to acquire and maintain a valid credential.

For OAuth 2.0 Client Credentials (the standard for Workday REST API and MuleSoft client-facing APIs), the IRD should specify:

• Grant type: client_credentials
• Token endpoint URL: https://{tenant}.workday.com/ccx/oauth2/{tenant}/token
• Client ID: specify by reference to the credential store (not the actual value in the document)
• Client secret: specify by reference to the credential store
• Scope: list each scope explicitly (for example, wd:facilities_data:read, wd:workers:read)
• Token expiry: duration in seconds (Workday default is 3,600)
• Refresh behaviour: Client Credentials does not issue refresh tokens; a new token must be acquired via a fresh client credentials grant after expiry
• Token storage: where the token is cached during the integration runtime (for MuleSoft, this is typically the ObjectStore connector)

For API Key authentication the IRD should specify the header name, the prefix if any, and the rotation schedule. “Authorization: Bearer {key}” and “X-API-Key: {key}” are different header formats and the distinction matters.

For mutual TLS the IRD should specify the client certificate subject name, the issuing CA, the expiry date, the keystore type (JKS, PKCS12), and the team responsible for certificate renewal. If renewal is not tracked in the IRD, it becomes an incident trigger.

For Workday integrations specifically, the IRD should also document the Integration System User (ISU) account name and the Workday security groups assigned to it. The ISU must have domain security policy access for every Workday domain the integration queries or modifies. Missing domain access is one of the most common causes of 403 errors in Workday integrations, and it is a tenant configuration issue, not a code issue. Confirming ISU access before development begins saves significant debugging time.

For Workday ISU setup, the Workday Developer Portal documentation on API authentication is the canonical reference for OAuth 2.0 API client configuration, ISU setup, and scope assignment in Workday Studio and the REST API.

For MuleSoft integrations consuming APIs managed through Anypoint Exchange, the IRD should specify whether the consuming application is registered in Anypoint Platform, the SLA tier it is assigned to, and whether client ID enforcement is applied at the API gateway. Our guide to API-led connectivity patterns from real MuleSoft projects covers how API contracts, client application registration, and SLA enforcement interact in a governed Anypoint deployment.

Section 4: Data Mapping and Transformation Rules

This is the functional core of the document and the section most likely to cause production defects if written carelessly. It is also the section most developers will return to during implementation, during testing, and during incident investigation.

Structure of the Mapping Table

A data mapping table must include every field being transferred. For each field, the table should have a minimum of eight columns: source system field name (as it appears in the API response or file), source data type, target system field name (as it appears in the API request or database column), target data type, transformation logic, null handling behaviour, conditional logic, and notes.

The source and target field names must use the exact name as it appears in the actual system, not a human-readable label. A Workday API response returns workerData.personalData.nameData.preferredNameData.nameDetailData.firstName, not “First Name.” Using display labels in the mapping table forces developers to perform their own field resolution, which introduces interpretation errors.

Transformation Logic: Beyond the Happy Path

Simple transformations include format conversion (date format, case normalisation), string concatenation, and arithmetic. These should be written as explicit transformation rules rather than described in prose.

Weak: “Combine first name and last name into full name.”

Usable: “Concatenate source field firstName, a space character, and source field lastName. If firstName is null, use lastName only. If both are null, set to empty string and flag record in the validation log.”

Complex transformations include lookup table mapping, conditional branching, and cross-field derivation. Each of these needs a separate specification block.

Lookup table mappings must document every source value and its target equivalent. If the source system uses ISO 3166-1 alpha-2 country codes and the target uses full country names, the mapping table must list every code-to-name pair used in the dataset, not just the common ones. Unexpected source values not in the lookup table need a defined fallback: reject the record, pass through the raw value, or substitute a default.

Conditional branching must be written as explicit if-then-else logic, not described as “depends on the scenario.” A rule like “if the worker type is Employee, map to the Permanent staff category; if the worker type is Contingent Worker, map to the Contract staff category; if the worker type is any other value, reject the record and write to the error log” is unambiguous and directly implementable.

Cross-field derivation covers cases where a target field value is computed from two or more source fields. For example, deriving an employee’s full-time-equivalent value from their scheduled weekly hours divided by the standard full-time hours for their location. That derivation logic, including what the standard full-time hours constant is and where it comes from, belongs in the mapping specification, not in a code comment.

Handling Null, Empty, and Missing Fields

Null handling is where mapping specifications most commonly leave gaps. There are at least four distinct cases that need to be defined for each nullable field: the source field is present but explicitly null, the source field is present but empty string, the source field key is absent from the response payload entirely (a common pattern in Workday REST responses where omitted keys indicate no data rather than null data), and the source field contains a value that fails the target system’s validation.

Each case can legitimately have a different required behaviour, and each must be specified. A field that the target system requires to be present and non-null needs a hard reject rule when the source provides null. A field that the target system accepts as optional needs a pass-through-null rule. A field where null means “use the last known value” needs an explicit state management requirement. None of those behaviours are obvious defaults.

Schema Versioning and Breaking Changes

The mapping specification should also note the source and target API versions it was written against, and explicitly define what constitutes a breaking change requiring IRD revision. Adding a new required field on the target, deprecating a source field, and changing a field type from string to enum are breaking changes. Renaming a field in a non-backward-compatible way is a breaking change. Adding an optional field is not.

This is important for Workday integrations specifically. Workday releases two major platform updates per year (R1 and R2). Each release may deprecate API resources or change the structure of existing ones. The IRD should specify which Workday API version (v36, v37, and so on) the mapping is validated against, so that the impact of a version upgrade can be assessed systematically.

For Infor LN integrations using BODs, the IRD should specify the BOD version (for example, 9.0.1) and identify any custom BOD extension fields used, with their full extension path in the BOD XML structure. A custom field on a ReceivableTransaction BOD that exists in the Infor LN BOD extension but is not part of the standard Infor ION schema needs to be documented precisely, because it is invisible to any developer who has not been shown where to look. For details on how Infor LN surfaces these through its event architecture, our post on Infor LN event management and BOD handling covers the subscription and extension mechanics.

Section 5: Idempotency and Duplicate Handling

This section is almost universally missing from IRDs, and its absence causes one of the most common categories of production data quality incidents.

Idempotency means that processing the same message more than once produces the same result as processing it once. In integration systems, duplicate message delivery is not a theoretical edge case. It is a guaranteed operational reality. Network timeouts cause retries. Message brokers deliver at-least-once. SFTP polling scripts pick up files that were not correctly archived. Any integration that processes a message and then fails before acknowledging it will receive that message again.

The IRD must specify: whether each operation is required to be idempotent, how the integration identifies duplicate messages, and what the duplicate handling behaviour is.

For REST-based integrations, idempotency is typically implemented using a correlation ID or an idempotency key header. The IRD should specify the field or header that carries the unique message identifier, where that identifier originates (source system primary key, UUID generated at the integration layer, or a hash of the message payload), and how long the integration layer retains previously processed identifiers for deduplication.

For file-based batch integrations, the IRD should specify the mechanism for tracking which records have been processed. Common approaches include a watermark timestamp field (only process records with an updatedAt timestamp greater than the last successful run), a sequence number column, or a processed status flag on the source record. Each approach has implications for database load and query design that the IRD should acknowledge.

For Workday integrations using the REST API with updatedFrom filtering, the IRD must specify how the watermark is managed between runs, what happens if a run fails partway through (does the watermark advance or stay at the last successful run), and how records that were updated multiple times within a single polling window are handled.

Section 6: Error Handling, Retry Logic, and Dead-Letter Behaviour

This section separates IRDs that guide production operations from IRDs that generate production incidents.

Error Taxonomy

The first task in specifying error handling is defining the error taxonomy: a complete list of the error categories the integration can encounter, with the specific HTTP status codes or system error codes associated with each.

A minimal error taxonomy for an HTTP-based integration should include:

Transient infrastructure errors cover HTTP 502, 503, and 504 responses, network timeouts at the TCP layer, and DNS resolution failures. These errors indicate that the target system is temporarily unavailable. They are candidates for retry.

Transient rate limit errors cover HTTP 429 responses. These indicate that the integration is sending requests faster than the target system’s policy permits. They require a retry with a backoff interval that respects the Retry-After header if one is provided, or a default backoff if not. Workday enforces a rate limit of 1,200 API calls per hour per ISU account by default. A batch integration that exceeds this limit will receive 429 responses for the remainder of the hour window. The IRD must specify the backoff strategy for this scenario explicitly.

Authentication errors cover HTTP 401 responses indicating an expired or invalid token, and HTTP 403 responses indicating insufficient permissions. A 401 should trigger a token refresh attempt followed by one retry. A 403 should not be retried because it indicates a permissions problem that will not self-resolve. A 403 in production must trigger an alert because it indicates either a misconfiguration or a security policy change that requires human investigation.

Client-side data errors cover HTTP 400 and HTTP 422 responses indicating that the request payload failed target-side validation. These should not be retried because the same payload will receive the same rejection. The record should be written to the error log with the full validation error response body, and the integration should continue processing subsequent records rather than halting.

Business rule rejections are application-level errors returned with an HTTP 200 response code but with an error structure in the response body. These are common in Workday Web Services responses, which return HTTP 200 with a SOAP Fault element when a business validation fails. The IRD must specify how the integration distinguishes a successful response from a business rule error in this case, since HTTP status alone is insufficient.

Retry Matrix

The retry specification should be presented as an explicit matrix covering each error category with the retry count, backoff type, backoff interval, and on-exhaustion behaviour.

A usable retry matrix would specify, for example: HTTP 503 errors should be retried up to four times with exponential backoff starting at 15 seconds (15s, 30s, 60s, 120s) and then routed to the dead-letter queue. HTTP 429 errors should be retried up to six times with a fixed backoff of 3,600 seconds divided by the remaining hourly quota (or a minimum of 60 seconds if the Retry-After header is absent), then routed to the dead-letter queue. HTTP 400 errors should not be retried and should be written directly to the error log.

Dead-Letter Queue Specification

The dead-letter specification must answer: where messages are stored after retry exhaustion, the message format and metadata stored alongside the failed payload (correlation ID, original timestamp, error response body, retry count, source system identifier), who is notified on dead-letter arrival, the SLA for investigating dead-letter messages in production, and the procedure for replaying a dead-letter message after the root cause is resolved.

The notification path must be specific. “Alert the integration team” is not a specification. “Post a message to the #integration-alerts Slack channel with the correlation ID, the error category, and the dead-letter queue depth; page the on-call engineer via PagerDuty if the dead-letter queue depth exceeds five messages within a 30-minute window” is a specification.

Section 7: Non-Functional Requirements

Non-functional requirements govern how the integration performs rather than what it does. They are frequently absent from IRDs, which means developers build to no performance specification and are then held to an informal standard that nobody agreed on.

Throughput and Volume

The throughput specification should state expected record volume per execution window, both for normal operations and for peak periods. The specification should distinguish between initial load (the first execution that processes all historical records) and steady-state (subsequent incremental loads).

An initial load of 250,000 worker records from Workday is a very different technical problem from a daily delta of 150 updated records. The first requires batch pagination, parallel processing workers, rate limit budget management across multiple ISU accounts if necessary, and a restart-from-checkpoint capability. The second can run as a lightweight scheduled flow. Both requirements need to be stated explicitly in the IRD so the developer can design the appropriate solution.

Latency Targets

Latency targets must be specified differently for synchronous and asynchronous integrations.

For synchronous (request-reply) integrations, the target is the maximum acceptable end-to-end response time measured at the caller. This should be expressed as a percentile target: p95 response time under 500ms, p99 under 2,000ms, with any response exceeding 5,000ms considered a timeout error.

For asynchronous integrations, the latency target is the maximum acceptable time between the source event occurring and the data being available and correct in the target system. This is an end-to-end measurement that includes event publication, message queue transit, integration processing, and target system write. Each segment has a latency budget, and the IRD should acknowledge which segments are within the integration team’s control and which depend on external systems.

Availability and Maintenance Windows

The availability specification should state the required uptime percentage (99.5%, 99.9%, and so on), the measurement period, the planned maintenance window and how it interacts with the integration schedule, and the behaviour of the integration during a planned maintenance window on either connected system.

For Workday integrations specifically, Workday publishes maintenance window schedules per tenant. If the integration is scheduled to run during a Workday maintenance window, the IRD must specify whether the run should be skipped, delayed until the maintenance window ends, or retried at a fixed interval after the window close time.

For organisations using managed integration services where a third party monitors and operates the integration in production, the non-functional requirements section of the IRD defines the SLA that the managed service is held to. Availability, latency, throughput, and error rate targets all need to be stated explicitly.

Section 8: Security and Compliance Requirements

Data Classification and Field-Level Controls

The security section begins with data classification. Every field in the data mapping table should have a classification level assigned to it, and the integration’s security controls should be calibrated to the highest classification level present in the payload.

Classification levels for integration purposes typically fall into three tiers: non-sensitive data (internal reference codes, system identifiers, non-personal configuration values), personally identifiable information or PII (names, contact details, national identification numbers, date of birth), and sensitive or regulated data (salary and compensation data, health or benefit information, performance ratings, protected characteristics).

For each classification tier, the IRD should specify: whether the field must be masked or tokenised in integration logs, whether the field may be written to a non-production environment (PII masking in test environments is a common compliance requirement), and whether the field requires field-level encryption during transit in addition to transport-level TLS.

Audit Logging Requirements

The audit logging specification must define what events are logged and what data each log entry contains.

At a minimum, integration audit logs should capture: a unique correlation ID for the message, the source system and source record identifier, the target system and target record identifier (if the operation was successful), the operation type (create, update, delete), the timestamp of each stage (message received, transformation completed, target write attempted, target write confirmed), the outcome (success, retry, dead-letter), and the actor identity (the ISU or API client ID used).

The retention period for audit logs must be specified. For integrations handling regulated data under GDPR, audit logs demonstrating lawful data transfer must typically be retained for a minimum of three years. For integrations in scope for SOC 2, audit log integrity and retention are explicitly assessed.

The IRD should reference the specific regulatory framework applicable to this integration rather than making a generic statement about compliance. “This integration transfers EU employee data under GDPR Article 6(1)(b) (performance of a contract of employment)” is a specification. “Ensure GDPR compliance” is not.

Credential and Secret Management

The IRD should specify: where integration credentials are stored (a secrets manager, an encrypted configuration file, a platform-native credential vault such as MuleSoft’s Anypoint Security or Workday’s ISU credential store), who has access to each credential, and the rotation schedule and process for each credential type.

For any-to-any integration architectures connecting multiple third-party systems, the credentials section can become complex. Maintain a credentials inventory as a sub-section of the IRD, listing each credential, the system it authenticates against, its expiry date, and the owner responsible for rotation.

Section 9: Testing and Acceptance Criteria

Test Case Structure

This section defines what “done” means. Without it, integrations go live on informal consensus and fail in production under conditions that were never tested.

Each test case should document: a unique test case ID, the scenario being tested (happy path, error path, edge case), the precondition state of both systems, the test input and how it is injected, the expected output in the target system, the expected log entries at the integration layer, and the pass or fail criteria.

Test cases for transformation logic must cover: standard input producing the expected output, null input for each nullable field, boundary values for numeric and date fields (minimum value, maximum value, value at boundary), invalid input that should trigger a validation rejection, and lookup table values including at least one value not in the lookup table.

Test cases for error handling must verify that each error category in the retry matrix is handled as specified. This requires the ability to simulate error conditions, either by using a test endpoint that returns configurable error responses or by temporarily misconfiguring credentials to trigger authentication errors. If the test environment does not support error simulation, that is a gap in the testing strategy that should be flagged in the IRD.

Performance Test Specification

If throughput and latency non-functional requirements are defined in Section 7, the testing section must include a corresponding performance test specification. The performance test spec should define: the test scenario (initial load simulation, steady-state simulation, or peak load simulation), the data volume, the target metrics being validated (p95 latency, records per minute, error rate under load), and the acceptance threshold for each metric.

For MuleSoft batch integrations, MuleSoft’s Anypoint Platform documentation on batch processing defines the threading and commit behaviour of batch jobs, and the performance test should validate that the integration behaves within the documented parameters under the volume specified in the IRD.

Production Readiness Checklist

The production readiness section defines the minimum conditions that must be met before the integration is promoted to production. This checklist should include: all test cases passing with documented results, all open questions in Section 9 resolved and incorporated into the spec, all security controls verified including encryption and credential rotation tested, monitoring and alerting configured and verified to fire correctly, dead-letter queue reprocessing procedure documented and tested, runbook for the most likely failure scenarios completed and reviewed by the operations team, and sign-off obtained from all four review parties defined in the IRD review process.

Platform-Specific IRD Considerations

MuleSoft Anypoint Platform

MuleSoft integrations benefit most from IRDs that are aligned with the API-led connectivity model, which means the specification should reflect the three-layer architecture rather than describing point-to-point connections.

For System API specifications, the IRD should name the specific backend system resource being wrapped, reference the API contract in RAML 1.0 or OAS 3.0 format (or link to the published Anypoint Exchange asset by asset ID and version), document the caching policy (TTL, cache key strategy), and specify the connection pool size and idle timeout for the backend connector.

For Process API specifications, the IRD should document the business process being orchestrated, the System APIs consumed with their specific endpoints and version contracts, the DataWeave transformation logic applied at the process layer (transformation requirements should be written as DataWeave pseudo-code or type annotations rather than English prose where precision matters), and the transaction boundary if the process requires compensating transactions.

For Experience API specifications, the IRD should document the consumer identity (mobile application, partner portal, internal web app), the SLA tier assigned in Anypoint Platform, and the gateway policies applied. Common Experience API gateway policies include client ID enforcement, OAuth 2.0 token validation, rate limiting by client ID, CORS configuration, and IP allowlisting. Each applied policy must be specified in the IRD because each one can reject legitimate requests if misconfigured.

MuleSoft’s Anypoint Platform documentation on API policies and runtime management covers the available policy types and their configuration parameters.

Workday Integrations

Workday integrations require documentation precision that goes beyond what other REST integrations typically need, because Workday’s platform exposes multiple integration mechanisms with different capabilities, performance characteristics, and access patterns.

The IRD must specify which mechanism is used and why. The Workday REST API is appropriate for real-time or near-real-time record access where the data volume per call is modest. Workday Web Services (SOAP) is necessary for operations not yet available in the REST API, including most write operations in domains like Payroll and Benefits. Enterprise Interface Builder (EIB) is appropriate for scheduled bulk file extracts. Workday Integration Cloud (WIC) and Studio integrations are appropriate for complex transformations or when bi-directional orchestration is required.

The IRD should also specify whether calculated fields are used. Workday allows calculated fields to be defined at the tenant level and exposed through RAAS (Report as a Service) custom reports or through the Worker Data report. A calculated field that exists in one Workday tenant may not exist in another. If the integration relies on a calculated field, the IRD must document the field name, the calculation logic, and the domain it is defined in, so that its existence can be verified in the target tenant before development begins.

For full details on Workday REST API OAuth flows, ISU permissions, and versioned resource access, the Workday Developer Portal is the authoritative reference. The IRD should cite the specific API version and resource documented on the portal rather than describing expected behaviour from memory.

Our technical guide to Workday REST API integration patterns for enterprise teams covers OAuth 2.0 token management, pagination across large worker populations, and field availability differences between Workday versions.

Infor LN and ION Integrations

Infor LN integrations that use the Infor ION middleware layer follow a publish-subscribe event model built around Business Object Documents (BODs). The IRD for an Infor LN integration needs to specify the integration at two layers: the Infor LN layer (what triggers the BOD publication, which BOD noun and verb are used, and which LN session parameters are relevant) and the ION layer (the connection point configuration, the data flow document routing, and the API endpoint or file-based delivery method).

At the LN layer, the IRD should specify the LN session user and company context, the business object event that triggers the BOD (for example, finalising a sales order in session SLS100 triggers a Sync.SalesOrder BOD), and any LN-side configuration required such as enabling the ION service on specific LN sessions.

At the ION layer, the IRD should specify the ION connection point name, the BOD routing rule (which connection points receive which BOD nouns and verbs), and whether the integration uses the ION API (HTTP endpoint) or ION file-based delivery. For API-based consumption, the IRD should document the ION API endpoint, the OAuth 2.0 credential configuration in ION, and the polling or webhook delivery model.

Handling Incomplete Requirements

Not all requirements are knowable at the start of a project. Source systems may not yet be available for exploration, target schemas may be in active development, or the business process the integration supports may not be finalised.

The correct response is to write a precise document that explicitly marks unknown areas as open questions, assigns each question an owner, and sets a resolution deadline.

A data mapping row where the transformation logic reads “OPEN: owner J. Smith, deadline 14 June, question: confirm whether source field departmentCode maps to costCentre or department in target” is useful. A row that reads “to be determined” is not. The first creates a tracked action item. The second creates a hidden assumption that surfaces as a production defect six weeks later.

For projects with a high volume of unknowns, a phased IRD approach works well. The Phase 1 document captures what is known with confidence and is used to scope technical design and infrastructure provisioning. The Phase 2 document, produced after a dedicated discovery sprint against the actual systems, fills in the gaps before full development begins. This structure pairs naturally with custom integration development engagements where a discovery phase is part of the scoped delivery model.

The IRD Review Process

A completed IRD should be reviewed by at least four parties before it is baselined: the business stakeholder who owns the integrated process, the architect or lead developer who will build the integration, the team that owns the source system, and the team that owns the target system.

The business stakeholder review validates that the document accurately represents the business requirement, that the latency and availability specifications match operational expectations, and that the security and compliance section correctly identifies the applicable regulatory framework.

The developer review validates that the document is technically precise enough to build from without back-and-forth clarification. Any section where the developer would need to make a decision not specified in the IRD is a gap that must be resolved before work begins.

The source system review validates that the integration assumptions about available fields, query patterns, API version capabilities, rate limits, and authentication mechanisms match the actual system behaviour. This is the review most commonly skipped and the one most responsible for integration rework.

The target system review validates that the mapping, data types, enumeration values, and validation rules align with the target system’s actual enforcement behaviour, not the behaviour described in outdated documentation.

Each reviewer should annotate rather than simply approve. An IRD review that produces no comments is not a thorough review.

Keeping the IRD Current After Go-Live

An IRD written once and then abandoned becomes misleading within months. Workday releases two major updates per year. MuleSoft runtime versions progress. Target system schemas evolve. Business rules change. When the document no longer reflects production reality, it actively misleads anyone who references it during an incident or when planning a related integration.

The IRD should be treated as a living document with a version history. Each change should be logged with a date, a description of what changed, and who approved the change. A version-controlled repository is substantially more useful than a folder of files with names containing “FINAL” and “revised.”

For teams managing multiple integrations in production, the IRD library becomes a critical operational asset. Integration consulting engagements frequently include IRD remediation as a formal deliverable when teams inherit integration portfolios built without adequate documentation. Retrofitting documentation onto working integrations is harder than writing it upfront, but it is far more tractable than operating integrations that cannot be safely changed because nobody understands how they work.

Reference IRD Section Map

The following section structure can be applied as a working template. Each heading maps to a content area covered in this guide.

Section 1 – Document Information: title, version number, creation date, last modified date, author, reviewer list, approval status.

Section 2 – Integration Overview: business process supported, trigger event, operational impact of downtime, acceptable latency window (business vs. regulatory basis), downstream dependencies, maintenance window constraints.

Section 3 – Integration Pattern and Transport: pattern type (request-reply, fire-and-forget, pub-sub, batch), transport protocol, message format and encoding, HTTP methods per operation, file naming convention if applicable.

Section 4 – Endpoints and Authentication: source system base URL per environment, resource path, API version, required parameters, rate limits; target system equivalent; authentication type, token endpoint, credential reference, token expiry and refresh behaviour, ISU or client application details.

Section 5 – Data Mapping and Transformation: field-by-field table (source field name and type, target field name and type, transformation logic, null handling, conditional logic, classification level, notes); lookup tables for enumerated values; cross-field derivation rules.

Section 6 – Idempotency and Duplicate Handling: idempotency key field and origin, deduplication mechanism, watermark or sequence strategy for incremental loads, duplicate behaviour (skip, overwrite, reject and log).

Section 7 – Error Handling: error taxonomy with HTTP or system codes; retry matrix (error category, retry count, backoff type, backoff interval, on-exhaustion behaviour); dead-letter queue location, message format, notification routing, reprocessing procedure.

Section 8 – Non-Functional Requirements: throughput for initial load and steady state, latency targets (p95 and p99 for synchronous; end-to-end delivery window for asynchronous), availability SLA, peak load behaviour, twelve-month volume growth projection.

Section 9 – Security and Compliance: data classification by field, masking and tokenisation rules, credential management and rotation schedule, audit log specification (events, fields, retention period), regulatory framework reference.

Section 10 – Testing and Acceptance Criteria: unit test cases for transformation logic, integration test scenarios (happy path and error paths), performance test specification, production readiness checklist, UAT cases and sign-off owner.

Section 11 – Open Questions: question text, owner, resolution deadline, resolution (populated when answered).

For organisations building any-to-any integration architectures across multiple platforms and communication protocols, this structure scales by adding platform-specific sub-sections under the endpoint, authentication, and mapping sections for each system pair involved in the integration topology.

The Real Cost of Getting This Wrong

An Integration Requirements Document is not a compliance exercise or a project management formality. It is the mechanism through which a business communicates a technical requirement with enough precision that an engineering team can build it correctly the first time.

The data is unambiguous. The 2025 MuleSoft Connectivity Benchmark Report puts the average annual cost of integration challenges at $6.8 million per organisation. IT teams spend 39% of their time on custom integration work, and 95% of organisations report that integration challenges are a material barrier to their AI and automation objectives. With only 28% of enterprise applications properly integrated despite years of investment, the pattern is clear: the problem is not a shortage of integration effort. It is a shortage of integration precision.

The teams that write precise IRDs do not just ship better integrations. They ship faster, with fewer production defects, more predictable delivery schedules, and operational documentation that survives beyond the team that built the original integration. The document is not overhead. It is the most cost-effective engineering investment in the integration delivery lifecycle.

Work With Sama Integrations

If your team is planning or managing a complex integration project and needs support defining requirements, designing the architecture, building the integration, or operating it in production, the Sama Integrations team works across MuleSoft, Workday, Infor, and custom integration environments.

Talk to our integration consultants about your project requirements

Learn about our managed integration and production support services

Explore our custom integration development capabilities