Skip to content

Connector API (upload XML)

IBM Food Trust™ organizations upload data in XML format using the GDPR notice

Attention: To comply with EU General Data Protection Regulation (GDPR) data privacy requirements, you must ensure that no personal data is uploaded to IBM Food Trust in any free-form text fields or in any comments.

Overview

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

  1. Upload data manually, using API calls (human users)
  2. 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 Figure 1 below. The user must include a valid IBM Food Trust Service token with each submitted XML message:

Figure 1. IBM Food Trust - uploading data flow IBM Food Trust flow

Prerequisites

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

  1. Register human users: Register the user's IBMid (email address) with IBM Food Trust, at Users dashboard.

  2. Register system users and applications: Obtain a Service ID for each system user, as described in the prerequisites section in Authenticate 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:

  1. Sign in to IBM with your IBMid.
  2. Connect to the Swagger IBM Food Trust Connector API.
  3. Expand the Assets POST /fs/connector/v1/assets API.
  4. 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.
  5. At the bottom of the API, upload the XML message (data) by clicking the Try it out! button.
  6. 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:

  1. Retrieve a token for the ServiceId from IBM Food Trust authentication.
  2. Start a POST request to: https://food.ibm.com/ift/api/connector/fs/connector/v1/assets
  3. Paste the token in the Authorization Header, as follows: Bearer <token>.
  4. Submit the XML message to IBM Food Trust.
  5. 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 API error messages.

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"
    ]
  }
}
  • Common error responses can be found here.

IBM Food Trust will return a new asset ID for the uploaded data, or an error code.