This is second blog in series of 8 blog focussing on gathering integration requirements. The blog will focus on enterprise-wide integration where Salesforce is the primary system but interacts with other core systems.

Integration is the lifeblood of an enterprise Salesforce implementation. In our previous article, we introduced the Salesforce Integration Decision Framework. In this second installment, we focus on gathering integration requirements and why this step is critical for enterprise-wide projects. Without a clear blueprint of requirements, even the best technology can falter.

Various studies highlight this: as many as 70% of system integration projects fail to achieve their goals, and industry research shows poor requirements management is a top reason for project failure. In other words, rushing into integration without solid requirements is “like building a bridge without measuring the gap first.”

"Integration requirements are not just technical details—they are business lifelines that ensure our systems speak the same language," says a senior Salesforce architect.

This blog will walk through a structured 6-step approach to gathering integration requirements, applicable across industries and filled with practical insights.

Step-by-step process for gathering integration requirements

To help SF Architects and project teams, I'm presenting a step-by-step framework for capturing integration requirements. This practical toolkit aligns with integration best practices and covers often overlooked aspects like governance, error handling, and long-term maintainability. By following these steps, you can create a comprehensive requirements document that serves as a blueprint for successful integrations

Step 1: Identify business flows and data ownership

Meet with stakeholders across departments (sales, finance, customer support, IT, etc.) to map out the critical business flows that span multiple systems. For example, an Order-to-Cash process might involve Salesforce (CRM), an ERP for billing, and a fulfillment system. Document each cross-system process in scope and the high-level data that moves through each step.

Next, identify key data entities and their “System of Record”. Determine where each piece of data should be mastered. For instance, is Salesforce the source of truth for customer contacts, or does an ERP own that data? Clarity on data ownership is crucial to avoid conflicts. In two-way integrations, define which system "wins" for each field to prevent a tug-of-war

It’s also important to involve both business and IT stakeholders in this step:

• Business stakeholders will outline what they need (e.g., sales wants new leads from the website to appear in Salesforce instantly).
• Technical stakeholders (Salesforce admins, integration engineers) will assess feasibility and note any constraints (e.g., the website’s system API limits).

"The business drives integration, not the other way around."

Step 2: Document data dictionary and relationships

A detailed data dictionary and entity relationship understanding are your best friends in integration projects. This involves documenting each data element that will be exchanged between Salesforce and other systems, along with its attributes and mappings.

Start by listing out all objects and fields involved in the integration:

• For each Salesforce object (Account, Contact, Case, Order, etc.) in scope, list the fields that need to be sent or received.
• Do the same for the external system’s objects (e.g., an “Invoice” object in an ERP).

Define a data dictionary with key fields and formats

(Note: Data Warehouse receives daily dumps of new customers from Salesforce.)

This dictionary would continue for all fields that are exchanged or compared between systems. If you have hundreds of fields, focus on the key fields first – you can always append more as needed.

Step 3: Define data flow and transformation rules

With what data defined, now focus on how data moves between systems and any transformations needed. This step is about capturing the end-to-end data flow for each integration scenario, including triggers, intermediate steps, and business rules that affect the data in transit.

For each business flow identified in Step 1, break down the integration sequence:

• Trigger/Event: What starts the integration? Is it a user action (e.g., a salesperson closing an Opportunity), a time-based job (nightly batch), or an event in another system (a new record in an external database)? Document the trigger condition clearly.
• Source Data Extraction: When the trigger fires, what data is collected? E.g., “When an Opportunity is marked Closed-Won, gather the Opportunity details and related Account and Line Items.”
• Transformation/Enrichment: Describe any data transformations that must occur before sending to the target. For examples: converting data formats (dates, currency), applying business logic (e.g., if Opportunity Stage = “Closed Won” then set ERP Order Status = “New”), or enriching data by adding additional info. For instance, you might append a country code based on the state/province, or lookup a Salesforce record ID to include as a foreign key in the payload. If multiple source fields combine into one target field (or vice versa), specify that rule (e.g., concatenate First Name and Last Name into a full name for a legacy system).
• Deduplication Rules: If the integration might create duplicates (for example, receiving contact info from two sources), define how to identify and handle dupes. Will you check Salesforce for existing records by email or external ID before inserting a new record? Outline the approach (maybe using Salesforce Duplicate Management or letting the integration middleware handle it).
• Routing and Conditional Logic: Note if there are branches in the flow. E.g., “If the Account is a VIP customer, route the data through an approval process before integration” or “If record type = X, send to System A, otherwise send to System B”. These conditions should be clearly documented, possibly with a flow diagram.
• Target System Load: Specify how data is written to the target system. For example, “Create a new Order in the ERP via API Endpoint /orders; then return the Order ID and update it back in Salesforce.” If the integration is bidirectional, document the flow in the opposite direction as well.

Document the transformation rules in detail. This could be an extension of your field mapping table with additional columns for any formula or logic. For example: Before sending to marketing system check:

IF Contact.MailingCountry is blank AND 
Account.BillingCountry is not blank, 
set Contact.MailingCountry = Account.BillingCountry

Step 4: Determine integration type and frequency

Not all integrations are created equal—each use case may require a different integration approach (pattern) and timing. In this step, define whether each integration need is real-time, near real-time, or batch, and decide on the appropriate mechanism (API, middleware, event, etc.) to use. This is essentially applying an Integration Decision Framework to each flow.

First, ask for each use case: How soon must data be synchronized?

• Real-Time (Synchronous): If the business requires an immediate response or instant data availability, a real-time integration is needed. For example, when a customer calls support, the agent’s Salesforce screen might fetch live data from an order management system via API so they have up-to-the-minute info. Real-time integrations are typically request/response style — e.g., Salesforce makes a callout to an external REST API and waits for a response. Use cases include validating an address in real-time or retrieving inventory levels on the fly. Keep in mind Salesforce’s governor limits on callouts and API calls; real-time calls should be used judiciously for critical needs.
• Near Real-Time (Asynchronous/Event-Driven): Many scenarios don’t need an immediate blocking response, but still should happen quickly in the background. This is where events or messaging shine. Salesforce Platform Events, Change Data Capture (CDC), or outbound messages can publish an event that subscribers (external systems or middleware) receive almost instantly. For instance, a Platform Event can notify an ESB (Enterprise service bus) that a record changed, and the ESB then orchestrates updates to other systems. This decouples the process – Salesforce doesn’t wait for a reply, it just sends the notification. If multiple systems need to know about an event (fan-out), event-driven is a great fit. Document if an event is one-way or if after processing, the external system will callback or update Salesforce (which would be a separate flow).

Choosing the right integration approach depends on the type of data, sync frequency, and system constraints. The framework below helps architects decide whether to use real-time, event-driven, or batch-based integration. Use this as a guiding reference when designing integrations.

Once you have determined the overall integration type, the next step is selecting the most appropriate Salesforce integration mechanism based on data volume and frequency. The diagram below provides a useful reference for aligning integration choices with business and technical constraints.

Finally, clearly specify synchronization frequency for each data flow. Even if it’s event-driven (which is essentially on-demand), note it. If some data needs an initial backfill and then incremental sync, capture that. The requirements should state, for example, “All existing customer records will be loaded initially via a one-time migration, then new and changed customers will sync in real-time via event messages.”

By the end of this step, you should have for each integration use case: a defined integration style (pattern), tools/technologies chosen, and timing/frequency.

Step 5: Security, compliance, and data governance

No integration requirement is complete without a thorough look at security and compliance. Data is moving between systems, possibly leaving the Salesforce cloud, so you must ensure it’s protected and meets regulatory requirements.

Key things to capture:

• Authentication & authorization: For each integration point, determine how systems will authenticate. Salesforce offers solutions like Connected Apps for OAuth tokens, or you might use API keys/IP whitelisting for certain endpoints. Best practice is to use a dedicated Integration User account in Salesforce with restricted permissions—only what’s needed for the integration​.
• This way, if credentials are compromised, damage is limited. If using middleware, document how it will authenticate to Salesforce (and vice versa if Salesforce calls out). Also consider authorization: ensure the integration follows the principle of least privilege (e.g., the integration user profile only has access to objects/fields it needs).‍
• Encryption: Data should be encrypted in transit and at rest. Salesforce APIs use HTTPS (SSL/TLS) by default – ensure the external side also supports TLS 1.2/1.3. If any payloads are written to disk (e.g., a middleware staging table or an SFTP drop), note if encryption at rest or PGP encryption is needed. Also consider field-level encryption for sensitive data. For instance, if syncing Social Security Numbers or credit card info, Salesforce Shield Platform Encryption might be required on those fields. Document any such requirements now so the build team includes them.‍
• Data Governance & compliance: Identify any regulatory / policy requirements related to the data being integrated. Common ones:‍
  • Data Residency: Does any data need to stay within certain geographical boundaries? For example, EU customer data might need to remain in EU data centers (GDPR data residency requirements). If integrating with a system in another region, you may need special approvals or architecture (Salesforce has features like Hyperforce for specified regions, but external systems must comply too).‍
  • GDPR/CCPA: If personal data is involved, ensure you have a way to honor deletion or anonymization requests across systems. For instance, if a user invokes their right to be forgotten, your integration should be documented to propagate deletion or anonymization to all connected systems, not just Salesforce. Include requirements like “When a Contact is deleted in Salesforce for GDPR, the integration will also delete or anonymize the contact in System X within 30 days.”‍
  • HIPAA or Industry Regulations: If you’re dealing with health data, financial data, etc., note compliance standards. E.g., health data integrations might require using secure messaging standards and audit trails due to HIPAA. Financial data might necessitate additional encryption or masking under PCI DSS. Document any requirements for audit logging of data access for compliance.‍
• Access control & APIs: If external systems are calling into Salesforce via APIs, detail what API user profiles or permissions sets are needed. Conversely, if Salesforce calls external APIs, confirm that the external API has proper token validation and perhaps IP restrictions to only allow Salesforce/MuleSoft servers. Consider using Named Credentials in Salesforce to manage endpoint and credentials securely (it simplifies authentication management).

Security & compliance checklist (sample)

Step 6: Define error handling and monitoring

A robust integration requirement must address error handling, monitoring, and long-term maintainability strategies.

Key things to cover:

• Error handling strategy: For each integration flow, decide how errors will be handled. Consider both system errors (e.g., network outage, API down) and data errors (bad data causing a failure). Will the integration retry automatically on failure? If so, how many times and at what interval? For example, “If an ERP order insert fails, retry up to 3 times with 5 minutes interval.” If not auto-retried, does it go to a dead-letter queue or an error queue for manual review? Define the behavior clearly. Salesforce’s patterns provide guidance: in a synchronous call, the calling system must handle the error (maybe show an error to the user)​, whereas in an async pattern like platform events or outbound messages, the responsibility often shifts to the receiving system or requires a replay mechanism​. Document where those responsibilities lie.‍
• User notifications vs Silent logging: Decide if errors should be exposed to end users or only to admins. For example, if a real-time screen integration fails, do you show the Salesforce user an error message (“Unable to fetch data, please try again later”), or just log it and let them proceed? This ties into UX requirements. Document any user-facing error requirements.‍
• Logging and Audit Trails: Specify how integration actions and errors will be logged. Ideally, every integration attempt (success or fail) should leave a trace for troubleshooting. If using middleware, it likely has logging. If not, you might need Salesforce to capture some info. Options include:
  • Create a custom Integration Log object in Salesforce to record when calls are made, with status and timestamps.
  • Use Salesforce’s Event monitoring or Transaction security for API usage tracking.
  • External logs: if the integration is external, ensure those logs are accessible. Requirements might be “The system shall log all failed records to an error table, including error details and a reference ID.”
  • Audit needs: For sensitive data, maybe log every time certain data was sent out (to satisfy auditing standards).‍
• Monitoring & Alerts: How will the team know if something breaks? Define monitoring requirements:
  • Do we need real-time alerts (email/SMS/Slack) if an integration fails or if error rate exceeds X?
  • Will someone receive an alert if a scheduled batch didn’t run or if it processed zero records when it should have processed many?
  • Consider using Salesforce tools like Flow orchestration logs, or external APM tools, or the middleware’s dashboard. Document who gets the alerts (e.g., the Salesforce admin team, or a dedicated support email).

Error handling & monitoring matrix (sample)

Finalizing the IRD(integration requirements document)

After gathering all the details from Steps 1–6, the next step is to consolidate this information into a structured IRD

Structure the document clearly: Organize the IRD into sections that mirror the process we followed. For example:

1. Overview – Summary of integration scope, objectives, and stakeholders. Include the business justification: e.g., “Implementing integration between Salesforce Sales Cloud and ERP to automate order processing, eliminate manual data entry, and ensure data consistency across systems.”
2. Business process flows – Describe each relevant business flow (from Step 1) in narrative form, possibly with flow diagrams. Include which systems are involved in each step.
3. Data definitions and mappings – Insert the data dictionary and mapping tables from Step 2. If there are many, consider putting them in an appendix or separate spreadsheet, but summarize key entities and relationships in the main doc. Include ERD diagrams or object models here for clarity.
4. Integration approach details – For each integration use case, specify the integration type, frequency, triggers, and pattern as determined in Step 4. This could be a subsection per integration flow with headings like “Opportunity to Order (Salesforce -> ERP) Integration” and under it, details from Step 3 and 4: trigger, data flow, mapping reference, pattern (e.g., event-driven via platform event), frequency (real-time), etc.
5. Security and compliance – A section summarizing all security requirements (from Step 5). It might include tables for authentication matrix, permissions needed, and compliance notes. Security teams often look for this section in particular.
6. Error handling & monitoring – Include the error handling matrix and describe the monitoring plan from Step 6.
7. Non-functional requirements – This covers performance, scalability, and maintainability aspects. For instance, note expected volumes (peak records per hour) and performance SLAs, any scalability considerations (“system should handle 2x current volume in 3 years”), and maintainability needs (documentation, ease of configuration). This might draw from earlier steps (like volume from Step 3, maintainability from Step 6).
8. Assumptions and constraints – List any assumptions made (e.g., “ERP system will provide API by Q2”, “All systems have test environments available”) and constraints identified (“Salesforce API call limits of 100k/day must not be exceeded”, “Integration will not cover historical data migration” etc.).
9. Glossary – Define any acronyms or terms for clarity (SOR = System of Record, CDC = Change Data Capture, etc.).
10. Sign-offs – A section for stakeholder sign-off, indicating that business owners, Salesforce architects, system owners, and security have all reviewed and agreed to these requirements.