B2B Integration

InFlight REST APIs

By Vince Tkac posted Tue July 13, 2021 02:09 AM

  
Co-authored by Drew Myers (acmyers@us.ibm.com)​

Within IBM Sterling Supply Chain Business Network, InFlight shows the status of transfer and translation of  electronic business data as it moves the network, allowing users to confirm it was sent or received successfully. The InFlight application is a component of IBM Sterling Supply Chain Business Network (SCBN) Standard and Premium Editions and consists of a datastore and user interface to collect, store and view tracking information related to business documents flowing through SCBN.  

It provides UI access to information about inbound and outbound electronic business data at a minimum of three points: when it is received from the sender, when it is processed, and when it is sent to the receiver.

The InFlight UI allows the user to search and filter on a variety of data from the tracking and business document record (see Figure 1).

Inflight UI showing filtering and results
Figure 1 - Inflight UI showing filtering and results

A full record view is available to see exactly which steps were executed on any given document (see Figure 2).

Inflight UI showing full record view
Figure 2 - Inflight UI showing full record view


To explore a live demo of the Inflight UI, sign up for a free 30 day trial here:  https://www.ibm.com/products/supply-chain-business-network

API Access to the InFlight data
For user that want direct access to the tracking data, Inflight includes REST APIs.  Instead of logging in to the SCBN UI, the APIs can be used to create custom scripts, alerts and reports or to augment a custom UI for more direct integration.  

If something goes wrong with an EDI transaction much of the time someone needs to login to InFlight to try and find the error.

Many customers want to script this activity or tie the results into an existing UI.  The InFlight APIs provide a convenient REST API to query your document transfer status and fetch details for each document.  This allows for automatic correlation of internal tracking data with the tracking data SCBN has available

Below are the high level use cases (in story form) for the InFlight REST APIs:

Use Case 1:  Query the state of documents SCBN is delivering to my partner from me
As an SCBN Customer using InFlight, I want to see the state of file delivery through SCBN outbound from my system so I know if the document was successfully delivered to my trading partner. 

This REST API could be used to extend the visibility of an in-house UI so that it includes events from SCBN.

Use Case 2:  Query the state of documents SCBN is delivering to me from my partner
As an SCBN Customer using InFlight, I want to see the state of file delivery through SCBN inbound to my system so I know if the document was successfully delivered from my trading partner. 

This REST API could be used to extend the visibility of an in-house UI so that it includes events from SCBN.

Use Case 3:  Show the list of documents pending delivery to my system
As an SCBN Customer using InFlight, I want to see a list of documents from trading partners bound for my system that have erred out and not been received by my system yet so I can know where failures are happening and address them.

These documents do not exist in Integrator tracking system yet as they failed inbound to Integrator systems through SCBN.

This REST API could be used to provide visibility of "red docs" via an in-house UI.

Use Case 4:
  Retrieve the full payload of a document referenced in a tracking record
As an SCBN Customer using InFlight, I want to retrieve the contents of a document from SCBN so I can examine the contents of a document when triaging problems.

This REST API could be used to extend the visibility of an in-house UI so that it includes payload data from SCBN.

API capabilities
The REST APIs support simple list and get operations using the HTTP GET verb.  Query parameters are used for filtering, sorting and paging of results data.  API output is standard JSON except for the payload API which is binary data.  

Filtering:
The following filter criteria can be provided as REST query parameters to return data matching only the provided values:
  • direction (INBOUND, OUTBOUND)
  • status (SUCCESS, FAILURE)
  • state (IN_PROGRESS, COMPLETE, INCOMPLETE)
  • doc_type (856, 810, 997...)
  • receiver_id - EDI receiver ID from the envelope header
  • sender_id - EDI sender ID from the envelope header
  • received_before
  • received_after

For example, to return data for only 850 document types received before 2021, the following query could be used:
.../documents?doc_type=850&received_before=2021-01-01T00%3A00%3A00.000%20UTC

In the example above, "%3A" is an encoding for a semicolon ":" and "%20" is an encoding for a space " ".  The unencoded received_before date would look like:  "2021-01-01T00:00:00.000UTC".  Be sure to  encode any reserved characters when passing them via REST API.  Following are reserved characters:

! * ' ( ) ; : @ & = + $ , / ? % # [ ]

Sorting:
The following criteria can be provided to sort the response data
  • direction (INBOUND, OUTBOUND)
  • status (SUCCESS, FAILURE)
  • state (IN_PROGRESS, COMPLETE, INCOMPLETE)
  • doc_type (856, 810, 997...)
  • receiver_id - EDI receiver ID from the envelope header
  • sender_id - EDI sender ID from the envelope header
  • received_at - the date/time of the first event

The sort attribute can be specified as sorted ascending or descending by providing a + or - preceding the parameter, the default is ascending if a direction is not explicitly provided.

.../documents?sort=received_at
.../documents?sort=+received_at
.../documents?sort=-received_at

Paging:
The following options can be used for paging
  • limit - controls the number of records returned in a list request
  • offset - controls the starting record in a list request

By default, APIs return a limit of 200 records.  To return more or less records, pass a limit value in the REST API call.

Technology and Implementation
InFlight APIs query against a NoSQL data store that exists in parallel to the InFlight relational data store used for the UI.  The same data feed is used to update both UI and API data stores.  The NoSQL datastore relies on a document centric model optimized for fast retrieval of records.  Retrieval can be very fast as there are no JOINs across relational tables.

All query results are returned as JSON.  Payload data is returned as an HTTP binary stream.

Authentication is done with a Client ID and Client Secret assigned and managed at the SCBN Company level.  The ID and Secret is associated with a company and allows access to one or more business aliases within that company.  

API samples and abbreviated responses 
Samples showing how to call the InFlight APIs with curl and pass in authentication credentials.  The pattern is very simple and only requires two additional header.  

Samples

Query and return a list of summary records for outbound documents.  The default is to return a maximum of 200 records.
curl https://api.ibm.com/inflight/bluerun/documents?direction=OUTBOUND -H "X-IBM-Client-Id: $CLIENT_ID" -H "X-IBM-Client-Secret: $CLIENT_SECRET"

Query and return a list of summary records for inbound 850 documents.  The default is to a maximum of 200 records.  
curl https://api.ibm.com/inflight/bluerun/documents?direction=INBOUND&doc_type=850&sort=state-H "X-IBM-Client-Id: $CLIENT_ID" -H "X-IBM-Client-Secret: $CLIENT_SECRET"

Query and return a list of summary records for inbound
documents that have erroredReturn a maximum of 10 records.
curl https://api.ibm.com/inflight/bluerun/documents?direction=INBOUND&status=ERROR&limit=10 -H "X-IBM-Client-Id: $CLIENT_ID" -H "X-IBM-Client-Secret: $CLIENT_SECRET"

Query and return a
full detail record for documentCode 123.  The documentCode can be found in the summary results
curl https://api.ibm.com/inflight/bluerun/documents/123 -H "X-IBM-Client-Id: $CLIENT_ID" -H "X-IBM-Client-Secret: $CLIENT_SECRET"

Query and return
the body of they payload with payloadID 123.  The payloadID can be found in any event of the full detail record.  The is the payload after the step has completed.  
curl https://api.ibm.com/inflight/bluerun/payloads/abc -H "X-IBM-Client-Id: $CLIENT_ID" -H "X-IBM-Client-Secret: $CLIENT_SECRET"


Example
These examples use the trial company from the Excel trial (SCBN Trial Buyer SCI00198755) as mentioned above.  The various API calls in the example are a progress for query, view results, view details and view payload.  Very similar to what a user would do in the InFlight UI.  

Query and return a summary list of outbound documents of type 850 and sorted by the received time.  Limit the results to 3 records.  The summary record contains the status and state as well as the sender/receiver ID and the document type.  This data can be used or shown to the user before additional drill-down.  

curl 'https://api.ibm.com/inflight/bluerun/documents?sort=-received_at&limit=3&direction=OUTBOUND&doc_type=850' -s -H 'X-IBM-Client-Id: $CLIENT_ID' -H 'X-IBM-Client-Secret: $CLIENT_SECRET'
[
   {
       "documentCode": "88564179-5d8e-4284-8d3a-37a3e5acd755",
       "summary": {
           "bytes": 432,
           "direction": "OUTBOUND",
           "receivedAt": "2021-07-01T09:15:40.000 UTC",
           "receiverID": "SCBNTRIALSUP",
           "senderID": "SCBNTRIALBUY",
           "state": "COMPLETE",
           "status": "SUCCESS",
           "type": "850"
       }
   },
   {
       "documentCode": "1766cd57-ff3d-4b37-aa7b-28657b1062dc",
       "summary": {
           "bytes": 767,
           "direction": "OUTBOUND",
           "receivedAt": "2021-07-01T09:15:10.000 UTC",
           "receiverID": "SCBNTRIALSUP",
           "senderID": "SCBNTRIALBUY",
           "state": "COMPLETE",
           "status": "SUCCESS",
           "type": "850"
       }
   },
   {
       "documentCode": "cfc546d9-cea2-469c-940c-115e4060bd43",
       "summary": {
           "bytes": 1179,
           "direction": "OUTBOUND",
           "receivedAt": "2021-07-01T09:15:09.000 UTC",
           "receiverID": "SCBNTRIALSUP",
           "senderID": "SCBNTRIALBUY",
           "state": "COMPLETE",
           "status": "SUCCESS",
           "type": "850"
       }
   }
]

A drill-down into the detailed record is available and shows all the events and data associated with the document. 
The summary section is the same as the results list.  Additional high level details are available in the details section.  The fields in this area will change based on the flow.   

There are three main events: receive, process, send. The process section is a list of events that cover any processing on the payload like translation, PGP decrypt or keyword replace.  Each event follows the same basic structure with an event ID, description, event specific detail data.  

curl https://api.ibm.com/inflight/bluerun/documents/88564179-5d8e-4284-8d3a-37a3e5acd755 -s -H 'X-IBM-Client-Id: $CLIENT_ID' -H 'X-IBM-Client-Secret: $CLIENT_SECRET'
{
   "details": {
       "processId": "01fcb2fa-c22c-4ebb-835a-31b59e7da386",
       "referenceNumber": "PO-Trl-Can-2107",
       "sourceFilename": "1_CANCELLED_850.edi",
       "sourceFolder": "inbound",
       "sourceMessageId": "76209017a615a3117node1",
       "typingMapUsed": "BPN_X12_SAT_Typing_XML"
   },
   "documentCode": "88564179-5d8e-4284-8d3a-37a3e5acd755",
   "postProcess": {
       "events": {
           "259be87d-6400-4f14-9086-4e685fdaaa37": {
               "createdAt": "2021-07-01T09:15:41.000 UTC",
               "description": "RulesEngineWorkerThread_doCarbonCopyRuleAction_send",
               "details": [
                   "2c92b383780d7ed50178218d9f5c364b",
                   "SCBN_TRIAL_SUPPLIER",
                   "6377d827-a9ff-487d-b82e-d24e8dc41d07"
               ],
               "eventCode": "259be87d-6400-4f14-9086-4e685fdaaa37",
               "senderAlias": "SCBN_TRIAL_BUYER"
           }
       },
       "ids": [
           "259be87d-6400-4f14-9086-4e685fdaaa37"
       ]
   },
  "receive": {
       "createdAt": "2021-07-01T09:15:40.000 UTC",
       "description": "BPN_ReceiveFTP_success_receive",
       "details": [
           "POD41",
           "398483330",
           "FTP"
       ],
       "eventCode": "b20428ef-cbd3-4f78-9cad-ee7339398459",
       "senderAlias": "SCBN_TRIAL_BUYER"
   },
   "process": {
       "events": {
           "6efa66aa-e28a-4e97-ac0c-415b75da93df": {
               "createdAt": "2021-07-01T09:15:41.000 UTC",
               "description": "TranslationDriver_processEMBMessage_typingInfo",
               "details": [
                   "TYPING SPE02",
                   "BPN_X12_SAT_Typing_XML",
                   "01fcb2fa-c22c-4ebb-835a-31b59e7da386"
               ],
               "eventCode": "6efa66aa-e28a-4e97-ac0c-415b75da93df",
               "parentEventCode": "b20428ef-cbd3-4f78-9cad-ee7339398459",
               "senderAlias": "SCBN_TRIAL_BUYER",
               "sourceBatchID": "3b4635c5-48a7-4da9-aa9d-1829f45f0fb5"
           }
       },
       "ids": [
           "6efa66aa-e28a-4e97-ac0c-415b75da93df"
       ]
   },
    "send": {
       "createdAt": "2021-07-01T09:15:41.000 UTC",
       "description": "RulesEngineWorkerThread_doFinishRuleAction",
       "details": [
           "2c92b383780d7ed50178218d9f5c364b"
       ],
       "eventCode": "39fa92dd-0fd4-4ff2-af70-94d0d75f8c21",
       "final": true,
       "senderAlias": "SCBN_TRIAL_BUYER",
"file": {
"name": "Finish.dat",
"guid": "85feddad-a715-4ddd-803f-c80e32ab2937.1811",
"size": 433
}
   },
   "summary": {
       "bytes": 432,
       "direction": "OUTBOUND",
       "receivedAt": "2021-07-01T09:15:40.000 UTC",
       "receiverID": "SCBNTRIALSUP",
       "senderID": "SCBNTRIALBUY",
       "state": "COMPLETE",
       "status": "SUCCESS",
       "type": "850"
   }
}

Corresponding record in
InFlight (see Figure 3): 

Inflight UI showing event data
Figure 3 - Inflight UI showing event data


Each event has a payload associated with it.  That payload can be directly fetched via API.  This is the payload after the step has completed indicating the results of that step.  A translation service error will also be stored as a payload and can be retrieved with the payload API.  
curl https://api.ibm.com/inflight/bluerun/payloads/49780098-98ee-4605-825c-02c62c691c67-s -H 'X-IBM-Client-Id: $CLIENT_ID' -H 'X-IBM-Client-Secret: $CLIENT_SECRET'
ISA*00*          *00*          *ZZ*SCBNTRIALBUY   *ZZ*SCBNTRIALSUP   *210701*0400*U*00401*311990157*0*P*:~
GS*PO*SCBNTRIALBUY*SCBNTRIALSUP*20210701*0400*54657108*X*004010~
ST*850*000001~
BEG*00*CP*PO-Trl-Can-210701**20210701~
CUR*SE*USD~
REF*C3*453095~
CSH*P2~
N9*CK*4758~
N1*BT*ATX~
N3*123 Buyer St~
N4*New York*NY**US~
N1*ST*ATX~
N3*123 Delivery St~
N4*San Francisco*CA**US~
CTT*0*57~
SE*35*000001~
GE*1*54657108~
IEA*1*311990157~


Colorized API call from shell window



Try them yourself!
Want to try these APIs directly?  Sign up for a free 30 day trial here:  https://www.ibm.com/products/supply-chain-business-network to retrieve an API key that will work in the examples.

Swagger API Definition
A Swagger 2.0 definition for the APIs is available and can be used to generate client code in a variety of languages.  This doc is from July 2021 and does changer periodically so you may see inconsistencies as the doc ages.  

ifapis-swagger-1_2_0.yml

Future push model
A push model that integrates with IBM Streams is in the works.  This model would support use cases requiring a constant feed of data and is an alternative to polling of the query APIs above.  
0 comments
55 views

Permalink