Best Practices for Integration Design

Guide to Designing an Integration on the App Xchange Platform

Overview

This guide provides a comprehensive approach to designing an integration on the App Xchange platform prior to building. It covers key considerations and questions for product managers, integration designers, and end users.

Key Considerations

1. Integration Purpose

   • Define the scope and objectives of the integration.

   • Ideally consult with an end user of the product(s) or software to account for actual use cases, and identify “hidden” human processing that might occur in current procedures. 

   • Is the integration designed for one end user or many? If many, you may wish to have more configurability. 

   • Be very detailed:

     1. Exactly what data do you need to get out of system A? 

     2. Exactly what data do you need to move into system B?

     3. Exactly what data do you need to get out of system B?

     4. Exactly what data do you need to move into system A?

     5. Do you need additional supporting data? e.g. Vendors in Vista can be associated with tax information as well, if mapping Vendors from another system, do you have that data if needed? 

2. Object Level Mapping e.g. Venders >>> Vendors (See example below)

   • Complete a high level mapping of the objects that need to be moved between system A and system B indicating the direction of the eventual data flow

3. Field or Property  Level Mapping e.g. CompanyID>>>VendorID

   • Complete any mapping of properties and dependencies identified in the high level object map

4. Scope and Connectivity Questions 

   • Do all needed connector objects and actions exist on existing connectors (found here: https://appxchange.trimble.com/connectors)? 

     1. Check here to see existing connectors: https://appxchange.trimble.com/connectors

        • If a connector exists, does it have all the needed endpoints?

     2. If not, can you use the HTTP connector?

        • https://docs.appxchange.trimble.com/connectivity/universal-connectors/http 

     3. If not, and the HTTP connector is not a good option, do you need to build a connector using the Connector SDK? 

        • Is there a public API to support that, with supported authentication and all needed endpoints? 

        • What is the minimum viable product state? 

5. Answering the questions and completing the steps above supports:

   • Alignment between integration builder and the end user(s)

   • Avoids backtracking costing time and money

   • Supports ease of connector building and flow writing

   • Identifies any gaps preemptively, avoids stalling progress 

Example Object Map

The following is a sample Integration Template between Trimble products Flashtract and Vista:

Example Field Map

Each object is followed by a field map, such as this one for adding a Vista Project to Flashtract Project: