View Source

The Integration Configuration Workbook serves as the primary blueprint for designing, documenting, and implementing technical interfaces. This document is a modular template designed specifically for Integration Leads and Developers to standardize the transition from high-level requirements to detailed technical execution.

The objective of this workbook is to provide a "single source of truth" for all integration logic. Rather than starting from scratch for every integrations, users can select the relevant modules (bits and pieces) applicable to their specific use case.

Once finalized, the data captured here serves as the foundation for the Functional Specifications and technical documentation maintained within Confluence.

1. Integration Overview

Property	Value
Integration Name	[e.g., ERP Order Submission]
Integration ID/Reference	[e.g., INT-001]
Direction	[Inbound / Outbound / Bidirectional]
Integration Pattern	[Synchronous / Asynchronous / Batch / Event-Driven]
Source System	[e.g., Salesforce CRM]
Target System	[e.g., SAP ERP]
Technical Owner	[Name / Email]
Business Owner	[Name / Email]
Expected Volume	[e.g., 1000 records/day]
SLA Requirements	[e.g., Response within 5 seconds]

Business Purpose

[Describe the business purpose and use case for this integration...]

2. Inbound Integration (External to Salesforce)

Inbound Integration: External systems call Salesforce APIs. Configure a Connected App for authentication and document the Salesforce API endpoints to be exposed.

2.1 Connected App Configuration

Setting	Value	Required
Connected App Name	[e.g., ERP_Integration_App]	Required
API Name	[e.g., ERP_Integration_App]	Required
Contact Email	[admin@company.com]	Required
Description	[Connected App for ERP integration]	Optional

OAuth Settings

Setting	Value
OAuth Flow	[JWT Bearer / Client Credentials / Web Server & Refresh Token / Username-Password]
Callback URL	[https://your-callback-url.com/oauth/callback]
Consumer Key	[Generated after creation]
Consumer Secret	[Generated after creation - store securely]

OAuth Scopes

Scope	Description	Selected
api	Access and manage your data	[Yes/No]
refresh_token	Perform requests at any time (offline_access)	[Yes/No]
full	Full access	[Yes/No]
id	Access identity URL service	[Yes/No]

Client Credential

Setting	Value
Enable Client Credentials	[Yes/No]
Run As User	[Integration User]

JWT Configuration (if applicable)

Setting	Value
Use Digital Signatures	[Yes/No]
Certificate Name	[e.g., JWT_Certificate]

Session Policies

Setting	Value
IP Relaxation	[Enforce IP restrictions / Relax IP restrictions]
Refresh Token Policy	[Expire after X hours / Valid until revoked]
Permitted Users	[All users may self-authorize / Admin approved users]

Security

Setting	Value
Require secret for Web Server Flow	[Yes/No]
Require secret for Refresh Token Flow	[Yes/No]
Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows	[Yes/No]
Enable Refresh Token Rotation	[Yes/No]
Issue JSON Web Token (JWT)-based access tokens for named users	[Yes/No]

2.2 Salesforce API Configuration

Setting	Value
API Type	[REST API / SOAP API / Bulk API 2.0 / Composite API / GraphQL / Apex REST]
API Version	[e.g., v59.0]
Base URL	[https://yourinstance.salesforce.com]
Endpoint Path	[e.g., /services/data/v59.0/sobjects/Account]
HTTP Method	[GET / POST / PATCH / PUT / DELETE]
Content-Type	[application/json / application/xml]

Common Salesforce REST API Endpoints Reference

Operation	Method	Endpoint
Create Record	POST	/services/data/vXX.0/sobjects/{SObject}/
Get Record by ID	GET	/services/data/vXX.0/sobjects/{SObject}/{id}
Update Record	PATCH	/services/data/vXX.0/sobjects/{SObject}/{id}
Delete Record	DELETE	/services/data/vXX.0/sobjects/{SObject}/{id}
Query Records (SOQL)	GET	/services/data/vXX.0/query/?q={SOQL}
Composite Request	POST	/services/data/vXX.0/composite
Composite Graph	POST	/services/data/vXX.0/composite/graph
Bulk Job (Ingest)	POST	/services/data/vXX.0/jobs/ingest
Apex REST Service	*	/services/apexrest/{YourEndpoint}

2.3 Integration User

Setting	Value	Required
Username	[e.g., integrationuser@test.com]	Required
License Type	[e.g., Salesforce Integration, Salesforce]	Required
Profile	[e.g., Salesforce API Only System Integrations, Minimum Access ]	Required
Role	[IT]	Required
Permission Set Group	[e.g.: ERP_Integration_Access ]	Required
Permission Set License(s)	[e.g.: Salesforce CPQ ]	Optional

3. Outbound Integration (Salesforce to External)

Outbound Integration: Salesforce calls external system APIs using the Integration Framework. Configure Named Credentials for authentication and create an INT_Outbound_Integration__c record.

3.1 Named Credential Configuration

Setting	Value	Required
Named Credential Name	[e.g., ERP_API_Credential]	Required
Named Credential API Name	[e.g., ERP_API_Credential]	Required
URL	[https://api.external-system.com]	Required
External Credential	[e.g., ERP_External_Credential]	Required
Generate Authorization Header	[Yes/No]	Optional
Allow Formulas in HTTP Header	[Yes/No]	Optional

3.2 External Credential Configuration

Setting	Value
External Credential Name	[e.g., ERP_External_Credential]
Authentication Protocol	[OAuth 2.0 / JWT Token Exchange / JWT Bearer / Custom / No Auth]
Token Endpoint URL	[https://auth.external-system.com/oauth/token]
Scope	[e.g., api read write]
Issuer (JWT)	[e.g., salesforce-client-id]
Subject (JWT)	[e.g., service-account@company.com]
Audience (JWT)	[e.g., https://api.external-system.com]
Signing Certificate	[Certificate name in Salesforce]

Custom Headers

Header Name	Header Value	Description
[X-API-Key]	[{!$Credential.ERP_External_Credential.ApiKey}]	[API Key for authentication]
[X-Client-Id]	[your-client-id]	[Client identifier]

3.3 Remote Site Settings

Note: Remote Site Settings are required if NOT using Named Credentials, or for additional domains that need to be whitelisted.

Setting	Value
Remote Site Name	[e.g., ERP_API_Site]
Remote Site URL	[https://api.external-system.com]
Disable Protocol Security	[No (Recommended)]
Description	[Remote site for ERP API integration]

3.4 Outbound Integration Record (INT_Outbound_Integration__c)

Integration Framework: This custom object stores the configuration for outbound integrations. Create one record for each integration endpoint.

Field (API Name)	Value	Required
Name	[e.g., ERP_Order_Submission]	Required
Integration Reference INT_Integration_Ref__c	[e.g., INT_ERP_ORDER_001]	Required
Approach INT_Approach__c	[Callout / Click-Through]	Required
Method INT_Method__c	[GET / POST / PUT / PATCH / DELETE]	Optional
Named Credential INT_Named_Credential__c	[e.g., ERP_API_Credential]	Required
Service Path INT_Service_Path__c	[e.g., /api/v1/orders]	Optional
Timeout (ms) INT_Timeout__c	[e.g., 120000]	Optional
Correlation ID Header INT_Correlation_Id_Header__c	[e.g., X-Correlation-Id]	Optional
User Reference Header INT_User_Reference_Header__c	[e.g., X-User-Reference]	Optional
Custom Auth Header INT_Custom_Auth_Header__c	[e.g., X-API-Key]	Optional
Custom Auth Header Value INT_Custom_Auth_Header_Value__c	[Header value]	Optional
Custom Auth Header 2 INT_Custom_Auth_Header2__c	[e.g., X-Client-Secret]	Optional
Custom Auth Header Value 2 INT_Custom_Auth_Header_Value2__c	[Header value 2]	Optional
Store Logs As Info INT_Store_Logs_As_Info__c	[Yes/No]	Optional
Log HTTP Headers INT_Log_HTTP_Headers__c	[Yes/No]	Optional

Mock Configuration (Testing)

Field (API Name)	Value
Mock Enabled INT_Mock_Enabled__c	[Yes/No]
Mock Named Credential INT_Mock_Named_Credential__c	[e.g., Mock_ERP_API]
Mock Service Path INT_Mock_Service_Path__c	[e.g., /mock/api/v1/orders]

Click-Through Configuration

Field (API Name)

Value

Clickthrough Base URL

INT_Clickthrough_Base_URL__c

[https://external-system.com/app]

4. Extended Integration Framework (EIF)

Extended Integration Framework: EIF provides advanced features like asynchronous callouts, transformation engine integration, and platform event support. Configure EIF_Integration_Config__c records for enhanced capabilities.

4.1 Extended Outbound Integration (EIF_Integration_Config__c)

Field (API Name)	Value	Required
Name	[e.g., ERP_Order_Extended_Config]	Required
Operation Code EIF_Operation_Code__c	[e.g., ORDER_SUBMIT]	Optional
Outbound Integration Ref EIF_Integration_Setting_Ref__c	[e.g., INT_ERP_ORDER_001]	Required
Callout Response Type EIF_Callout_Response_Type__c	[TRA_OrderSubmission_Srv.Response]	Optional
Is Active EIF_Is_Active__c	[Yes/No]	Optional
Integration Mechanism EIF_Integration_Mechanism__c	[Synchronous Callout / Asynchronous Callout / Platform Event]	Required

Transformation Configuration

Field (API Name)	Value
Transformation Type EIF_Transformation_Type__c	[No Transformation / Transformation Engine / Custom Extension]
Transformation Code EIF_Transformation_Code__c	[e.g., ORDER_TRANSFORM_001]
Transformation Class EIF_Transformation_Class__c	[e.g., OrderTransformationService]
Suppress Null Values EIF_Suppress_Elements_With_Null_Value__c	[Yes/No]

Response Handling

Field (API Name)

Value

Callout Response Type

EIF_Callout_Response_Type__c

[e.g., OrderResponseWrapper]

Asynchronous Callout Configuration

Note: These settings apply when Integration Mechanism is set to "Asynchronous Callout".

Field (API Name)	Value
Max Retry Number EIF_Async_Callout_Max_Retry_Nr__c	[e.g., 3]
Retry Interval (seconds) EIF_Async_Callout_Retry_Interval__c	[e.g., 60]
Exclude Status Codes For Retry EIF_Exclude_Status_Codes_For_Retry__c	[e.g., 400,401,403,404]
Async Callout Result Behavior EIF_Async_Callout_Result_Behavior__c	[See options below]
Async Callout Result Handler EIF_Async_Callout_Result_Handler__c	[e.g., OrderCallbackHandler]

Async Callout Result Behavior Options

Option	Selected	Description
Fire Platform Event On Error	[Yes/No]	Publish platform event when callout fails
Execute Callback Handler On Error	[Yes/No]	Execute Apex handler class on failure
Fire Platform Event On Success	[Yes/No]	Publish platform event when callout succeeds
Execute Callback Handler On Success	[Yes/No]	Execute Apex handler class on success

Platform Event Configuration

Field (API Name)

Value

Enable Platform Event Debugging

EIF_Enable_Platform_Event_Debugging__c

[Yes/No]

4.2 Mapping Definition ( TRS_Mapping_Definition__c)

Mapping Definition is only to be used if the Transformation Type is set to Transformation Engine.

Field (API Name)	Value	Required
Name	[e.g., ERP Order Transform]	Required
Mapping Code EIF_Operation_Code__c	[e.g., ORDER_TRANSFORM_001]	Required
Type Type__c	[e.g.,Standard]	Required
Assign Initial Context to TRS_Assign_Initial_Context_To__c	[orderId]	Optional
Is Active TRS_Is_Active__c	[Yes/No]	Optional
Description TRS_Description__c	[Synchronous Callout / Asynchronous Callout / Platform Event]	Optional
Suppress Null Elements TRS_Supress_Null_Elements__c	[Yes/No]	Optional
Treat Empty Lists as Null Elements TRS_Treat_Empty_Lists_as_Null_Elements__c	[Yes/No]	Optional
By Pass Validation Rules TRS_By_Pass_Validation_Rules__c	[Yes/No]	Optional
JSON Template
Refer to TRS - Import Configuration From Template

5. Authentication Configuration

5.1 Certificate Management

Property	Value
Certificate Name	[e.g., Integration_Certificate]
Certificate Type	[Self-Signed / CA-Signed]
Key Size	[2048 bits / 4096 bits]
Expiration Date	[e.g., 2025-12-31]
Purpose	[Describe what this certificate is used for]

5.2 API Keys and Secrets

Security Notice: Never store actual secrets in this document. Use references to secure storage locations (e.g., Named Credentials, External Credentials, or secure vault).

Credential	Storage Location	Notes
API Key	[e.g., External Credential: ERP_External_Cred]	[Notes]
Client ID	[Storage location]	[Notes]
Client Secret	[Storage location]	[Notes]

5.3 Authentication Flow

Property	Value
Authentication Type	[OAuth 2.0 / JWT / API Key / Basic Auth]
Token Endpoint	[https://auth.external-system.com/oauth/token]
Token Lifetime	[e.g., 3600 seconds]
Refresh Token Lifetime	[e.g., 86400 seconds]

Authentication Flow Description

[Describe the authentication flow step by step]

6. Request and Response Payloads

6.1 Request Payload

Property	Value
Content-Type	[application/json / application/xml]

Request Payload Structure

{

"orderId": "ORD-001",

"customer": {

"id": "CUST-001",

"name": "Acme Corporation"

},

"items": [

{

"productId": "PROD-001",

"quantity": 10,

"unitPrice": 99.99

}

],

"totalAmount": 999.90

}

Request Field Mapping

Salesforce Field	API Field	Type	Required	Notes
[Order.OrderNumber]	[orderId]	[String]	[Yes/No]	[Notes]
[Account.Name]	[customer.name]	[String]	[Yes/No]	[Notes]
[...]	[...]	[...]	[...]	[...]

6.2 Response Payload

Success Response (HTTP 200/201)

{

"status": "success",

"externalId": "EXT-ORD-001",

"message": "Order created successfully",

"timestamp": "2024-01-15T10:30:00Z"

}

Error Response Structure

{

"status": "error",

"errorCode": "VALIDATION_ERROR",

"message": "Invalid order data",

"details": [

{

"field": "items",

"error": "At least one item is required"

}

]

}

Response Field Mapping

API Field	Salesforce Field	Type	Notes
[externalId]	[Order.External_Id__c]	[String]	[Notes]
[status]	[Order.Integration_Status__c]	[String]	[Notes]
[...]	[...]	[...]	[...]

7. Error Handling and Status Codes

7.1 HTTP Status Codes

Status Code	Meaning	Salesforce Action
200 OK	[Success]	[Update record with external ID]
201 Created	[Resource created]	[Update record with external ID]
400 Bad Request	[Validation error]	[Log error, notify user]
401 Unauthorized	[Authentication failed]	[Refresh token, retry]
403 Forbidden	[Access denied]	[Log error, escalate]
404 Not Found	[Resource not found]	[Log error]
429 Too Many Requests	[Rate limit exceeded]	[Retry with backoff]
500 Internal Server Error	[External system error]	[Retry with backoff]
503 Service Unavailable	[Service temporarily unavailable]	[Retry with backoff]

7.2 Error Handling Strategy

Scenario	Handling Approach
Timeout	[Retry up to X times with exponential backoff]
Network Error	[Retry up to X times, then queue for later]
Validation Error	[Log error, update record status, notify user]
Authentication Error	[Refresh token and retry once]
Rate Limiting	[Implement exponential backoff]
Partial Success	[Process successful items, log failures]

7.3 Retry Configuration

Setting	Value
Max Retry Attempts	[e.g., 3]
Initial Retry Delay	[e.g., 1 second]
Backoff Multiplier	[e.g., 2x]
Max Retry Delay	[e.g., 60 seconds]
Retryable Status Codes	[e.g., 429, 500, 502, 503, 504]
Non-Retryable Status Codes	[e.g., 400, 401, 403, 404]

7.4 Logging and Monitoring

Setting	Value
Log Level	[INFO / DEBUG / ERROR]
Log Request Payload	[Yes/No]
Log Response Payload	[Yes/No]
Log HTTP Headers	[Yes/No]
Monitoring Dashboard	[Link to dashboard]
Alert Recipients	[Email addresses or Slack channel]