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 errored. Return 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):