how to upload data to IBMFoodTrust

How to Upload Data

This document describes how to upload data to the IBM Food Trust network. Data is encoded in an XML message, and uploaded to IBM Food Trust by an authenticated and registered user. If the POST upload operation is successful, a new asset is created on the network.

IBM Food Trust users will execute one of two methods to upload data:

Upload data manually, using the Swagger API (human users)
Upload data automatically, using a defined workflow (system users and applications).

In either case, the user (human, system or application) uploading the data must be authenticated (and registered with IBM Food Trust), as shown in the following IBM Food Trust flow diagram (Figure 1). The user includes their IBM Food Trust token with each submitted XML message:

Figure 1. IBM Food Trust Flow - uploading data

IBM Food Trust Flow

Prerequisites

To upload data (XML messages) to IBM Food Trust, the user (human, system or application) must have a valid IBMid. Each IBMid must also be registered with IBM Food Trust, by the Organization Administrator:

Register human users: Register the user's IBMid (email address) with IBM Food Trust, at Manage Users Dashboard.
Register system users and applications: Obtain a ServiceId for each system user, as described in the Prerequisite section in How To Get an Authentication Token for System Users.

Manual Submission

Use the following steps to manually (using the Swagger API) upload data to IBM Food Trust. An authenticated and registered user ID (human users only) is required. Each successfully submitted XML message creates an asset on the network:

Sign in to IBM with your IBMid.
Connect to the Swagger IBM Food Trust API.
Expand the Assets POST /fs/connector/v1/assets API.
From your local system, copy the XML message file contents (e.g. EPCIS event, Purchase Order, Receive Advice or Despatch Advice); then paste the contents into the Create Asset API Parameters asset field.
At the bottom of the API, upload the XML message (data) by clicking the Try it out! button.
If successful, a 201 response message is displayed. If an error occurs, a 40x response message is displayed, with an explanation. If necessary, correct the error and retry the Create asset API.

Automated Submission

Only authenticated system users or applications (ServiceId) can automatically upload data to IBM Food Trust. Before defining an automated workflow to upload data, ensure that the ServiceId has a valid token and is registered with IBM Food Trust. If necessary, follow the process to obtain a valid token (example POST request using CURL to send EPCIS_Observation.xml).

Complete the following process to configure a system user or application (authenticated ServiceId) to automatically upload data to IBM Food Trust:

Retrieve a token for the ServiceId from IBM Food Trust Authentication.
Start a POST request to: https://food.ibm.com/ift/api/connector/fs/connector/v1/assets
Paste the token in the Authorization Header, as follows: Bearer <token>.
Submit the XML message to IBM Food Trust.
Receive a new Asset ID from IBM Food Trust, which indicates a successful POST and upload of data.

Curl

The following command line example POST request uses the cURL command to send the XML message file EPCIS_Observation.xml to the IBM Food Trust service (URL). The user's Bearer (onboarding) token is specified:

$ curl -X POST --header 'Content-Type: application/xml' --header 'Accept: application/json' --header 'Authorization: Bearer <ONBOARDING_TOKEN>' -d @EPCIS_Observation.xml 'https://food.ibm.com/ift/api/connector/fs/connector/v1/assets'

A successful POST returns the following message containing a list of the asset ids created:

[
  {"ids":
      ["urn:ibm:provenance:asset:event:observation:9dd5cfaf-802b-4c70-8ae3-0770232f61a1:default:default:e2952199846fee144b34f06ea5485d2afbb04edc7297c03bf19c03ab8b3060e6"]
  }
]

If necessary, review the CURL error responses and solutions.

Bash

A sample Bash script is available to configure an automated data submission workflow for system users and applications. The code snippet is shown below; the ServiceId authentication token, and the XML File to upload must be specified:

$ POST_IFT.sh -t <token> -f <File>

Responses

201 Asset Created. This is returned when the submitted XML has been successfully processed. A response body will also be returned containing the asset ids that were generated for each asset contained in the xml.

Sample 201 Asset Created response body with asset ids

{
  "message": {
    "ids": [
      "urn:ibm:provenance:asset:event:transformation:org:default:default:dbdadc0dc3b2d36d4028c1d8f24b090cea63c5017b1d272fd688d9189907e10e",
      "urn:ibm:provenance:asset:object:lotILMD:org:default:default:95bc06fef9dd2a7081bdb795399b7d1c8f52dfc6630d095d2dda10620b421c4a",
      "urn:ibm:provenance:asset:object:lotILMD:org:default:default:0d38c56f0886a5cd7ee69fd63030b170bbc0997a926e441ecba7296410db6335"
    ]
  }
}