Why Document Integrations and Relationships?
Today's applications are integrated more than ever before. Change in one system can have a ripple effect on other systems. A change in a field within Salesforce can affect the accuracy of data or trigger unexpected behaviors in an ERP system, or disrupt marketing synchronization.
Without documenting these relationships, teams are often blindsided by issues, leading to increased operational risks. Proper documentation of these dependencies mitigates risks by providing clarity and control, ensuring smoother operations and informed decision-making across the entire system landscape.
When to Document Integrations and Relationships?
While it is a good idea to dedicate some time to audit and document all existing integrations, down to affected metadata components, there is often little time for such an ambitious undertaking. Here are therefore specific events that should trigger such documentation efforts:
New Integration: Whenever you are working on integrating a new system into Salesforce, such as an ERP or marketing platform, use this opportunity to document the integration in your Salesforce metadata dictionary.
System Upgrades: Prior to upgrading an existing integration, document the relationship and its purpose in your Salesforce metadata dictionary.
Prerequisites
In order to follow this guide you need:
Salesforce Metadata Management license
Synced Salesforce Org into Metadata Dictionary
Options for Documenting Integrations Using Elements.cloud
Elements provides you with a couple of different options for documenting your external integrations with a Salesforce Org. Watch this short overview from Rich, our VP of Customer Success in EMEA, and then continue reading the available options.
Option 1: Leverage MetaFields
MetaFields allow you to extend the metadata dictionary with custom fields, providing a more flexible and structured way to capture integration details.
Proposed MetaFields for Integration Documentation
Proposed MetaFields for Integration Documentation
We propose you define following MetaFields for objects, fields, flows, apex classes, external services, external objects, and platform events. So any metadata types that can be used for external integrations.
External System (Picklist)
Purpose: Identifies the external system tied to this Salesforce metadata component.
Values: ERP, CRM, Marketing, Payment, etc.
Data Exchange Type (Picklist)
Purpose: Identifies the method of data exchange.
Values: API, Batch, File Transfer, Webhook.
Data volume (Number)
Purpose: Specifies how many records are being pulled or pushed
Integration schedule (Picklist)
Purpose: Identifies how often integration runs and touches Salesforce.
Values: Hourly, Daily, Weekly, Monthly
Integration Owner (Text)
Purpose: Assigns the team or person responsible for managing the integration.
Pros:
Highly customizable to the specific needs of your organization.
MetaFields can be applied to any Salesforce metadata component and combined with custom views for reporting.
Cons:
Over-customization can make managing fields difficult.
Option 2: Tagging Metadata for System Integration Context
Tags in Elements.cloud can be applied to metadata components to categorize and group them by their role in integrations, making it easy to manage and view components involved in specific integrations.
Example Tags:
ERP
HubSpot
PaymentGateway
APIConnection
Pros:
Simple and quick to apply across many components.
Easy to filter and organize views based on tags.
Cons:
Lacks the depth of detail compared to MetaFields.
Cannot capture complex data relationships.
Option 3: Building a Manual Metadata Dictionary for External Systems
For external systems that don’t integrate directly with Salesforce metadata, you can manually build a metadata dictionary within Elements.cloud to document system tables, fields, and APIs. You can then document dependencies and connections between these external components and Salesforce manually.
Why It’s Useful:
Building a metadata dictionary for external systems allows teams to gain a deeper understanding of the external system’s configuration, such as its tables, fields, and custom logic. This is crucial for analyzing data consistency and mapping dependencies within the external system. By understanding these in-system relationships, you can document how changes in Salesforce might affect external system configurations, and vice versa.
Pros:
Allows for detailed documentation of systems outside Salesforce.
Facilitates a better understanding of how external systems are configured and operate.
Supports comprehensive documentation of in-system dependencies, helping with troubleshooting and future integration improvements.
Cons:
Entirely manual and time-consuming to maintain.
No automatic synchronization or update capabilities with external systems.
Requires a thorough understanding of the external system’s architecture.
Limitation
Currently the capability to document your metadata dictionaries for other systems requires manual work and is not automatic. The dictionaries are also not synced and kept up to date with your systems.
We plan to support automatic metadata dictionaries for non-Salesforce systems in 2025.
Therefore we recommend to use the following guide for systems that do not undergo very frequent changes and that can be documented manually without significant effort.