Data entitlement mode

IBM Food Trust supports data entitlement (data access) specifications for all XML documents uploaded to the network. Along with the data access control policy selected by your organization, specifying an optional data entitlement mode at the document level enables control over sharing your data with other organizations.

The data uploader can specify a data entitlement mode for each XML document at the time of submission.

Private
The data is only visible to the submitting organization, unless it is shared by explicit grants. For example, event data that pertains to an organization’s internal processes, or location master data for private locations.
Restricted
The data is shared only with the organizations that are explicitly referenced in the XML document. These are typically business transaction partners who are identified in Purchase Order, Despatch Advice (Advanced Shipping Notice; ASN), and Receiving Advice documents.
Linked
The data is shared with all organizations up and down the supply chain for a specific trade item (GTIN). These are typically supply chain events documents, which are shared through a process of cross-referencing data such as Facility IDs and Event IDs.
Default
Applies the default entitlement mode per type of document, see Table 1.
Note: Specifying a data entitlement mode on your data upload API calls supersedes your organization's data access control policy.

Assigning entitlement mode on data submission

Entitlement mode is specified by using the IFT-Entitlement-Mode header in the data submission request. If an entitlement mode is not specified, the default entitlement mode is applied, based on the type of XML document (Table 1).

Table 1. Default entitlement modes for each document type
Default entitlement mode Document type
Restricted Purchase Order, Despatch Advice (Advance Shipping Notice), Receive Advice
Linked EPCIS Events, Item Master Data, Location Master Data
Private Payload data*

*Payload data is used in IBM Food Trust for data types that do not fit the standard GS1 data types. Use payload data to attach user-defined data to events, items (product lots, serial shipping containers, pallets), or locations.

Valid entitlement mode headers on data submission

  • IFT-Entitlement-Mode: restricted
  • IFT-Entitlement-Mode: linked
  • IFT-Entitlement-Mode: private

If no IFT-Entitlement-Mode header is provided on data submission, the default mode is applied based on the XML document type, see Table 1.

Specifying an invalid entitlement mode value returns the following error message:

{
  "message": "bad_entitlement_mode_value is not a valid IFT-Entitlement-Mode header value!"
}