Intro to APIs

The Opus Platform accepts all APIs through one exposed /api/events endpoint per environment using the POST HTTP method regardless of the operation being performed or the object being operated upon. This is unlike a traditional RESTful Web service, which exposes multiple endpoints where users can perform operations with HTTP methods (e.g. GET, POST, PUT, etc.). The app that handles the request and the objects affected by the request are determined based on the contents of the header section of the request body.These event-driven APIs can be used to integrate the TraceLink app with your company's internal systems (e.g. enterprise resource planning system, warehouse management system).

Request header

The request header contains the metadata associated with the API request. All API calls to the Opus Platform must include the following key-value pairs in the request header:

• Content-Type – The media type for the message. Valid value is application/json.
• Authorization – The authorization token required to connect to the platform and environment.

Request body

The request body contains the message routing and handler information as well as the contents of the request. All API requests submitted to the Opus Platform must include the following header and payload elements:

• header – Specifies the event type of the request and the app that will receive the request. This must include the following parameters:
  • headerVersion –The header version. Valid value is 1.
  • eventName – The fully qualified name of the event that will be triggered by the request. This is typically formatted as [app-name]:[event-name]:[version] (e.g. agile-process-teams:add-incident:v1).
  • appName – The application that owns the event (e.g. agile-process-teams).
  • ownerId – The identifier for the company that is providing the app.
  • dataspace – The dataspace within the environment that the request call is being made. Valid value is default.

• payload– Includes the contents of the request.

Users are granted authorization to the Opus Platform through an API token. The users need to generate an API token prior to sending an API request in order to identify a username (an API key) and password (an API secret). A valid username and password must be included in the headers to process the API request successfully. This username and password does not expire, and it can be used in all API calls.

A guidelines table contains element requirements for a message.

• Element – The source or element name included in the API.
• Occurs | Length – Occurs indicates the minimum and maximum amount of times that the particular element can occur within the message. Length indicates the length of the value for the given element. An asterisk (*) indicates that an unlimited number of the element can occur or there is no limit on the length of the value. Additional information about the number of occurrences and the length can also be included in the Description column.
• Type – The element's data format type (e.g. String, Integer, Boolean, Date, Time).
• Description – Indicates whether the element is required for the message and provides a brief description of the element, including any relevant notes (e.g. country requirements, formatting notes).

1. Navigate to the guidelines table for the message you want to export.
2. Select the Download icon.
3. The file downloads locally.

Sample requests and responses, where relevant, are provided for each message.

Below is a Copy Direct Supplier Incident request example:

{
    "header": {
        "headerVersion": 1,
        "eventName": "agile-process-teams:copy-direct-supplier-incident:v2",
        "ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
        "processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
        "appName": "agile-process-teams",
        "dataspace": "default"
    },
    "payload": {
        "id": "fd04dd70-c162-43ef-8118-539ca01de471",
        "createdByPartner": false,
        "aptBusinessObjectSummary": "Shipment Damage",
        "copyGeneralInfo": true,
        "copyPartnerInfo": false,
        "copyMaterialInfo": true,
        "copyImpactInfo": false,
        "copyReferenceIds": false,
        "copyRelatedProcesses": true
    }
}

Sample requests and responses, where relevant, are provided for each message.

API examples can be easily copied and pasted into a text editor by selecting Copy.

1. Create a blank text file and save it locally.
2. Navigate to the API example that you want to copy.
3. Select Copy.
4. Navigate to the first row of the saved text file, right-click, and select Paste.

   The API example's structure is maintained.

   Syntax highlights will not reflect unless enabled in the file editor.

   There is a known issue in the documentation where the example might have extra spaces or quotation marks added if copied through a Chromium-based browser (e.g. Google Chrome, Microsoft Edge). This issue will be fixed in a future revision. For now, if this problem results in a validation error, either:

   • Manually copy the example by highlighting the full text, right-clicking, and selecting Copy.

     or

   • Use a non-Chromium-based browser (e.g. Apple Safari) to copy the example.