Document your integrations

It's a good practice to document your integrations. Below are guidelines, standards, and key aspects to consider when documenting your integrations.

Contents

• Guidelines
• Standards
  • Naming conventions
    • Integrations
    • Flows
    • Exports and imports
  • Structure
• Key aspects

Guidelines

Your document should always be clear, concise, complete, and accessible to all users. Here are some suggestions for keeping your docs clean:

• Clarity – Be concise and clear about each step of the integration.
• Completeness – Cover all essential elements of your integration, including setup, configuration, data mapping and transformation rules, error handling procedures, monitoring and maintenance guidelines, and troubleshooting steps.
• Consistency – Establish and adhere to naming conventions, document structures, and formatting guidelines.
• Accessibility – Make sure the information is easily accessible to all relevant users.
• Maintenance – Keep documentation up-to-date by adding information on changes, enhancements, or bug fixes. Encourage feedback and identify areas for improvement.

Tip: You can generate a current description of a flow or step's functionality using Celigo AI.

Standards

Always keep consistent naming conventions and standards. These are essential for clarity and organization within your integration documentation. Consider using predefined documentation templates to enforce consistent formatting, naming conventions, and standards across different integrations or projects. Templates can serve as a starting point and help streamline the documentation process.

Naming conventions

• Use descriptive names for all nameable elements in your integration.
• Avoid generic or ambiguous names that may cause confusion.
• If there are multiple instances or environments, clearly differentiate them using prefixes or suffixes (e.g. Dev, Staging, QA, Prod).
• Consider including version numbers or dates to track updates.
• Abbreviations or acronyms:
  • Always write out abbreviations and acronyms the first time they’re used.
  • Provide a glossary and explanation.

Integrations

Integrations can hold several flows that serve to implement a business process. For this reason, you can name a tile after a specific business process, such as Order Management, Inventory Management, A/P or A/R automations. Alternatively, you can also name the tile based on the integrated systems. For example, Salesforce – NetSuite, BambooHR – ADP, or Shopify – NetSuite.

Flows

Common naming conventions ensure that the source and destination applications, as well as the specific objects or record types, are clearly stated. It’s also worth including the operations that will be performed. The most common template is: <System> <Object> to <System> <Object> [<Operation(s)>]. For example:

1. HubSpot Deal to NetSuite Sales Order [Create or Update]
2. Salesforce Opportunity to NetSuite Sales Order [Create or Update]
3. NetSuite Sales Order to NetSuite Invoice [Create]
4. Shopify Order to NetSuite Sales Order [Create] and Customer Payment [Create]

Exports and imports

To maximize the potential of reusing exports and imports, their names should clearly reflect what they do (or are intended for). Common naming conventions include the system, the operation, and the object or record type. The most common template is: <System> : <Operation> <Object>

Examples:

• Imports
  • NS : Create or Update Sales Order
  • Stripe : Create or Update Invoice
  • Shipstation : Create or Update Shipment
• Exports / Lookups
  • NS : Get Latest Sales Orders
  • HS : Get Company by ID
  • Stripe : Lookup Company
  • Shop : Lookup Order by ID

Structure

Create a consistent structure for your documentation. Include headings, subheadings, and sections, and use a logical hierarchy to organize information.

Key aspects

There are many different types of documents you can create, and many aspects of an integration that need to be documented. integrator.io provides Description fields for most major resources of an integration, and you can add help text and description fields for any custom integration settings. You can also provide important details about an integration in the README that's available in the Admin tab.

However, you can still document the overall architecture, configuration, and setup process for your integration. It would help to gather requirements for your integration beforehand.

• Overview – Document a quick overview of the integration and each integration flow and step. Also include details of the business logic behind your integration and why it’s important.
• Glossary – Include a glossary of technical terms and acronyms used throughout the documentation. This helps ensure a common understanding among all stakeholders involved in the integration project.
• Architecture – Detail the architecture of your integration, including:
  • components and their interactions.
  • source and destination applications.
  • intermediate systems or databases and the middleware's role in facilitating data transfer.
  • connectors or prebuilt templates.
  • system or application diagrams.
• Dependencies – Identify and document the dependencies associated with your integration, including:
  • required software versions.
  • access credentials.
  • specific configurations needed in the source or destination applications.
  • information about any external systems or APIs.
• Configuration and setup – Explain the steps required to configure and set up the integration. Include: screenshots.
  • step-by-step instructions.
  • configuration files or scripts.
  • specific settings or options that need to be enabled or disabled.
  • mapping and transformation rules.
  • data type conversions.
  • data validation rules.
  • custom logic or scripts.
• Error handling and logging – Describe the error handling mechanisms in place for the integration.
  • Explain how error messages are captured, logged, and reported.
  • Provide guidance on troubleshooting common errors and known issues, including any relevant error codes or error message explanations.
  • Capture error handling for your own logic (for example, in your own scripts, applying branching, or even having built your own error management flows).
• Version control – Maintain a version history of your integration and its documentation. Indicate:
  • a version number
  • the dates of updates
  • a summary of changes made in each iteration
• Maintenance and monitoring – Outline the best practices for maintaining and monitoring the integration.
  • integrator.io's monitoring tools enable you to skip the need to document the inner workings of the functionality and instead focus on details specific to the integrations you have built and any logic that goes with them.
• Troubleshooting and support – Create a section dedicated to troubleshooting common issues that may arise during the integration process. Provide a list of frequently asked questions (FAQs) and their solutions. Include contact information for support resources, such as each system’s vendor’s customer support or community forums.