Typical Integration Flow

A typical Public API Integration Workflow is as follows.

1. Using your API Key, generate an OAUTH Token
2. Poll the List of Changed Connections.
3. Fetch the Profile Data for each of the Public Ids on the list.
4. Process the supplier through the integration
5. Send back identifiers to enable future updates
6. Acknowledge that the supplier has been integrated with or without errors.

Getting a List of Changed Connections

Retrieve a list of connections that are primed for integration into your system using the GET changes/connections API. This API offers parameters to narrow down the connection list, ensuring the received data aligns with your expectations.

API Description:

Documentation: GET /changes/connections

Endpoints:

• URL: /changes/connections
• Method: GET

Important Parameters:

1. Interface:

   • Description: Graphite uses the term "Interface" to oversee and track the list of suppliers prepped for integration. Each interface carries two critical dates that decide if a supplier is included.
   • Key Dates:
     • Last Updated Date: Represents the last modification date of the connection. Variation between interfaces might occur due to [External Interfaces](Link To External Interface) and [Transformations](Link for Transformations).
     • Last Sync Date: Marks the last successful synchronization, more details on how this field is set in the Acknowledgement topic.

2. filterEntitiesWithConfirmationReviews:

   • Description: Filters out connections with pending tasks.
   • Default: false
   • ERP Integration Recommended Value: true

3. connectionPhases:

   • Description: A comma-separated list used to filter entities based on their connection stage.
   • Default: invite,invited,review,connect,connected,disconnect,disconnected
   • ERP Integration Recommended Value: connected,disconnected

4. filterAnswersInclusive:

   • Description: Ensures the inclusion of entities having the specified answers set.
   • Format: AnswerKey1:Answer1|AnswerKey2:Answer2

Return Value

{
  updated: [
  	"US1234", "MX4556", "US8888"
  ],
  count: 3,
  total: 3
}

Usage:

Use this API to integrate the required connections into your system. By employing the available parameters, you can customize and streamline the data you obtain. Remember to ensure that the data you retrieve corresponds with your system's needs and integration criteria.

Fetching Profile Data

The GET profile/:publicId API facilitates the retrieval of data for a specific connection based on the provided Public ID. The response is a JSON object representing the connection's profile. Tailor the format of this data by employing Transformations.

API Description

Documentation: GET profile/:publicId

Endpoints

• URL: /profile/:publicId
• Method: GET

Parameters:

1. Public ID URL Parameter:
   • Description: Specifies the unique Public ID associated with the connection in Graphite. Use this ID to fetch the desired profile.
2. applyVisibilityRules:
   • Description: If set to true, the response omits fields that are hidden within the Graphite user interface.
   • Default: false
   • ERP Integration Recommended Value: true
3. Transformation:
   • Description: This parameter refers to the name of the Transformation intended to alter the structure or content of the response. Incorporating a transformation lets you adapt the API's output to better match your system's requirements or preferences.

Usage

Use this API endpoint when you need to access detailed information about a specific connection. By utilizing the available parameters, you can modify the data fetched to ensure it's both relevant and formatted to your needs.

Send Back Integration Identifiers

Overview

The PATCH profile/{publicId} API enables users to update connection fields, thereby storing critical data for subsequent integration processes. A primary use of this feature is to return primary keys, which allows future updates related to a particular connection. Each patch operation appends an entry in the Answer History, and the user is recorded as the name associated with the API key.

API Description

Documentation: PATCH profile/{publicId}

Endpoints

• URL: /profile/{publicId}
• Method: PATCH or POST
• Body Data Type: json

Important URL Parameters

1. Public ID URL Parameter:
   • Description: Denotes the unique Public ID correlated with the Graphite connection. Essentially, it represents the ID of the supplier set for an update.
2. updateChangeDateForInterface:
   • Description: Determines if the modification in the answer should reflect on the updatedAt date pertaining to the interface.
   • Default: false
   • ERP Integration Recommended Value: true

Body Format

• Root Level Keys: For root level modifications, align the Graphite key directly with its intended value in the body's root.
• Group Level Keys: For group level updates, list the group's name and map it to an array of objects. Every object within this array must enclose the instance id (_id) representing the specific instance under modification, along with any key to be updated in that group.

Example Explanation

Consider an example where you intend to assign the key supplier_vendor_id a value of 12345 and simultaneously update two distinct instances under the supplier_locations group. Specifically, for the two instances, the key supplier_location_id is set to 1111 and 2222 respectively.

{
  "supplier_vendor_id": 12345,
  "supplier_locations": [
    {
      "_id": "23ab88546bfc97223f2c4802936f26e4",
      "supplier_location_id": 1111
    },
    {
      "_id": "e82d1321ed4d374e78350a9ef74610a2",
      "supplier_location_id": 2222
    }
  ]
}

Acknowledge Integration Status

Overview

The POST Acknowledge_ API allows users to communicate to Graphite the outcome of an integration attempt. Depending on the provided feedback, Graphite will take appropriate actions such as updating the Last Sync Date or notifying specific stakeholders.

Successful Integration:

• If acknowledged without errors, Graphite will update the Last Sync Date. This action also clears the supplier from the changes queue.

Unsuccessful Integration:

• If acknowledged with errors, Graphite will send notifications to the designated person or group to address the integration failure. Additionally, this will block the supplier from the changes queue until resolved.

💡

Customized Workflows

The workflows triggered after a failed acknowledgement can be customized. Consult your Implementation Manager for more specific configurations.

API Description

Documentation: GET connections/acknowledge

Endpoints:

• URL: /connections/acknowledge
• Method: POST
• Body Data Type: json

Body Parameters:

1. interface:

   • Description: Represents the supplier set up for integration.
     • On successful integration, the Last Sync Date is updated, and the supplier is cleared from the List of changed connections.
     • On unsuccessful integration, the associated workflows are determined based on the interface to notify and block the failed supplier.

2. publicId:

   • Description: The unique identifier for the supplier being acknowledged. Commonly found in the Entity_Public_ID key in the supplier's profile.

3. connectionId:

   • Description: The connection ID for the supplier being acknowledged. Commonly found in the connectionId key in the supplier's profile.

4. groupKey:

   • Description: Updates the integration status of a group based on this groupKey and the instanceId.
   • Default Value: ERP_Record

5. instanceId:

   • Description: Denotes the specific instance of the groupKey that requires a status update. Within a supplier's profile group, this is represented by the key _id.

6. errors:

   • Description: Lists errors, if any, from the integration attempt. A non-empty array signifies a failed acknowledgment, triggering certain workflows based on the interface.
   • Datatype: Array

Example Body:

{
  "interface": "sap",
  "publicId": "US1234",
  "connectionId": "65391cd24520de7311741c02",
  "groupKey": "ERP_Record",
  "instanceId": "efe54134411f10c669026cc391b7ea08",
  "errors": // [] for successful ["put your error message here"] for failure
}