Chapter 2: Adding a Custom 3PL Connection (aka Integration)

Building a Custom Connection Overview

Pipe17 exchanges data with 3rd party vendors via "Connectors" that communicate with 3rd party apps via API. Connectors are the piece of code which establishes a connection, converts data between Pipe17 canonical format and vendor format. A merchant can add an instance of the Connector into their Org as an Integration. One can think of a Connector as a class definition and an Integration as an instantiation of the class.

Connectors are reusable across many organizations by creating a organization specific integration (i.e. an instance of the connector).

When building a custom integration, you are merging the concept of a connector and integration into one. This custom integration is backed by a connector, but has only one integration instance in this organization where it was created.

For all practical purpose, a custom integration, and a custom connector are synonyms. The represent the same thing simply because a custom connector can only have one instance of integration, it is not reusable.

In this document, we may interchangeably reference custom connector, custom connection or custom integration. They all mean the same.

Adding a Custom Connection (Integration)

To build a custom 3PL connection for Pipe17, follow these steps:

Navigate to Connections page and click on "Add Custom Integration" button.

Fill in the Connection name, select the Connection Type from the dropdown list (Logistics for this example), you can choose additional workflows to support by clicking on In/Out checkboxes for each entity, write a short description, and read me should contain information on how to use the connection. These fields can be edited later using API calls.
Selecting a connector type is optional. By selecting the most appropriate type, the system will automatically suggest the grants to be given to this connection. This ensures the connection cannot access other unauthorized objects.
If you do not select a connection type, you will have to manually provide the grants.
- Minimum grants are required for a 3PL integration:
  - Inventory IN and OUT
  - Orders IN and OUT
  - Shipping Request IN and OUT
  - Fulfillment IN and OUT
  - Location IN
  - Products OUT
- Remember: IN and OUT are in context of Pipe17.
  - IN means coming into Pipe17 - The expectation is that the external system is creating this entity IN Pipe17
  - OUT means coming out of Pipe17 - The expectation is that the external system is reading this entity OUT from Pipe17

Click on the "Create" button after filling in all the info.
You will see a prompt displaying the Connection API Key

NOTE: Please save this key in a secure place as you will need it to make 
any changes to the Connector object via Pipe17 API. This key is only shown once.

Once you have saved the Keys, you should see a new Connection in your Org, along with the workflows that were chosen.

The custom connection has now been created and available for your Org only.

An integration is automatically added to your Org based on this connection.

Remember this is a private integration only used by the connection added to this org.

You can query the Pipe17 Connection API by using the generated Connection Key as X-Pipe17-Key for authorization.

curl --location 'https://api-v3.pipe17.com/api/v3/connections' \
--header 'Accept: application/json' \
--header 'X-Pipe17-Key: ba04d3762a2edb580e1e623e59f080445cf39ef'

Please note the connectorId in the response, you will need this to make any further changes to the Connection.

Additional Connection Setup

The Connection can be updated via Pipe17 API using the Update Connector endpoint.

Setup Connection Details

Vendors typically need username, password, or API Key, API Secret, API URL etc to authenticate and make API calls. Connection details provides a place to define these credentials and hold the credentials on individual connections.

In this example we will be connecting with ShipBob Fulfillment following the Personal Access Token authentication flow.

"connection": {
  "type": "basic",
  "fields": [    
    {
      "path": "sbApiToken",
      "type": "string",
      "secret": true,
      "options": {
        "label": "API Access Token"
      }
    }
  ]
}

The merchant will add the integration on their Org and provide ShipBob credentials via the above fields.

Setup Entities & Direction

Specify the entities and direction of their data flows.

"entities": [
  {"name": "shipments", "direction": "out", "mappingUuid": "unique-uuid-1"},
  {"name": "fulfillments", "direction": "in", "mappingUuid": "unique-uuid-2"},
  {"name": "inventory", "direction": "in", "mappingUuid": "unique-uuid-3"},
  {"name": "locations", "direction": "in", "mappingUuid": "unique-uuid-4"},
  {"name": "products", "direction": "out", "mappingUuid": "unique-uuid-5"}
]

Setup Connection Instructions

Provide instructions on how to connect with the Vendor, in this example ShipBob Fulfillment. Markdown formatting of the text is allowed.

"readme": "1. Enter ShipBob API Access Token\n3. Click Connect"

Combining all of the above in a single request:

curl --location --request PUT 'https://api-v3.pipe17.com/api/v3/connectors/dcab92286022a257'\
 --header 'Content-Type: application/json' --header 'Accept: application/json'\
 --header 'X-Pipe17-Key: ba04d3762a2edb580e1e623e59f080445cf39efdc0844387c6de'\
 --data '{"connection": { "type": "basic", \
"fields": [ { "path":"sbApiToken", "type": "string", "secret": true, "options": { "label": "API Access Token" } } ] },\
 "entities": [ {"name": "shipments", "direction": "out", "mappingUuid": "unique-uuid-1"}, {"name": "fulfillments", "direction": "in", "mappingUuid": "unique-uuid-2"},\
 {"name": "inventory", "direction": "in", "mappingUuid": "unique-uuid-3"}, {"name": "locations", "direction": "in", "mappingUuid": "unique-uuid-4"},\
 {"name": "products", "direction": "out", "mappingUuid": "unique-uuid-5"} ], \
"capability": [ "shipments:out", "fulfillments:in", "inventory:in", "locations:in", "products:out" ], "readme": "1. Enter ShipBob API Key\n3. Click Connect"}'

Your Connection build basic setup is now complete and the Integration UI will now appear in a similar manner to other Pipe17 Connectors.

Optional Setup

Specify Capabilities

Optionally, you may specify the capabilities supported by this Connection by setting the "capability" array. The advantage of doing so is that the UI uses this information to enable certain features on the UI for users to perform.

Here is a minimum list of capabilities one may set for a logistics integration.

"capability": [
  "shipments:out",
  "fulfillments:in",
  "inventory:in",
  "locations:in",
  "products:out"
]

Please refer to this connector model for a full set of capabilities. You can set the ones this integration will provide. For e.g. if this integration will cancel shipping request, say due to stock not available, you can set shipments_cancel_in capability.