Skip to content

Test data entitlement

Using test data is a special case designed for new member organizations to try out IBM Food Trust before uploading production data to the ecosystem. To enable robust testing, all test data is integrated with production data. It is therefore important to understand the permanent implications of using test data with respect to data entitlement.

Data entitlement, also known as data access or data sharing, refers to the extent to which an organization enables access to product data for its supply chain partners. Data entitlement is provided at the JSON asset level, based on a common EPC (transitive entitlement) or a specific organization identifier (direct or explicit entitlement).

Uploading test data

Uploading test data enables organizations to integrate test data with production data on IBM Food Trust for trial or testing purposes. The organization uploading the data is responsible for clearly identifying test data for users, such as for Trace or Insights query results. Test data is not written to blockchain, and can therefore be subsequently deleted through an IBM support ticket.

Test data entitlement effects

The upload and integration of test data and production data has no effect on the default data entitlement selected by the data owning organization. That is, their data access control policy and data entitlement mode selections are fully applicable and most importantly, do not distinguish between the two data types. In other words, uploading test data can enable entitlement to production data, and vice versa, for supply chain partner organizations. The rule to remember is that any entitlement to production data enabled via test data upload cannot be reversed and persists even after the test data has been deleted. The example provided below demonstrates how these effects occur, in detail.

Data entitlement documentation

If you are new to IBM Food Trust data entitlement, you should review the following documentation before uploading your test (or production) data:

Test data entitlement example

The detailed test data example below illustrates the transitive effects of data entitlement, in this case upon production data. The example creates assets in IBM Food Trust, which are essentially blocks of JSON with various product and location identifiers. Data entitlement is granted or denied for the entire asset (block of JSON), not only for the individual EPC identifier.

Real world events

In can be helpful to map example real world events to IBM Food Trust data uploads and resulting data entitlement. The example events that occur behind this data usage example are as follows:

  1. Organization A (OrgA) ships a container (EPC/SSCC) to Organization B (OrgB).
  2. OrgA uploads this shipping event (Observation Event) XML for test data Asset 1 (JSON identifiers), specifying OrgB as the destination.
  3. OrgA uploads the same shipping event (Observation Event) XML as production data Asset 2 (JSON identifiers), but specifies no destination.
  4. OrgB ships a different container to OrgC, but uses the same EPC/SSCC that was used previously by OrgA.
  5. OrgB uploads the shipping event (Observation Event) XML as production data Asset 3 (JSON identifiers), specifying OrgC as the destination.

The key point about the real world events above are that the same EPC/SSCC is referenced in all three data uploads. This equivalency is used to efficiently demonstrate the direct and transitive data entitlement effects of test namespace usage.

Creating test data Asset 1

OrgA creates test data Asset 1 by uploading the Observation Event XML below to IBM Food Trust. Note that the test namespace is not identified in the XML; the test namespace is identified in the header of the Connector API call to the Assets endpoint.

The following API call properties are specified:

  • Entitlement Mode: Linked
  • Namespace: Test
  • Owning and submitting Organization: OrgA (company prefix 0614141)
  • EPC: urn:epc:id:sscc:0614141.0123456789
  • Destination: urn:epc:id:sgln:5012345.00001.0 (OrgB company prefix 5012345)

IBM Food Trust receives the following Observation Event XML (which creates test data Asset 1 as JSON identifiers):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<epcis:EPCISDocument
  xmlns:epcis="urn:epcglobal:epcis:xsd:1"
  xmlns:example="http://ns.example.com/epcis"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creationDate="2005-07-11T11:30:47.0Z" schemaVersion="1.2">
  <EPCISBody>
    <EventList>
      <ObjectEvent>
        <eventTime>2013-06-08T14:58:56.591Z</eventTime>
        <baseExtension>
          <eventID>urn:uuid:6926712e-599f-4c4e-b6e9-8dd888c906bd</eventID>
        </baseExtension>
        <epcList>
          <epc>urn:epc:id:sscc:0614141.0123456789</epc>
        </epcList>
        <readPoint><id>urn:epc:id:sgln:0614141.00777.0</id></readPoint>
        <bizLocation><id>urn:epc:id:sgln:0614141.00888.0</id></bizLocation>
        <bizTransactionList>
          <bizTransaction type="urn:epcglobal:cbv:btt:desadv">urn:epcglobal:cbv:bt:5412345000037:3352-349875</bizTransaction>
              </bizTransactionList>
        <extension>
          <quantityList>
          </quantityList>
                <sourceList>
                  <source type="urn:epcglobal:cbv:sdt:owning_party">urn:epc:id:sgln:0614141.00001.0</source>
                </sourceList>
                <destinationList>
                  <destination type="urn:epcglobal:cbv:sdt:owning_party">urn:epc:id:sgln:5012345.00001.0</destination>
          </destinationList>
        </extension>
      </ObjectEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Creating production data Asset 2

OrgA creates production data Asset 2 by uploading the Observation Event XML below to IBM Food Trust. Note that the DEFAULT (production) namespace is not identified in the XML; the DEFAULT namespace is identified in the header of the Connector API call to the Assets endpoint.

The following API call properties are specified:

  • Entitlement Mode: Linked
  • Namespace: DEFAULT
  • Owning and submitting Organization: OrgA (company prefix 0614141)
  • EPC: urn:epc:id:sscc:0614141.0123456789
  • Destination: None

IBM Food Trust receives the following Observation Event XML (which creates production data Asset 2 as JSON identifiers):

Attention: Note that the EPC/SSCC identifier above is the identical one used previously for test data! The same identifier (EPC: urn:epc:id:sscc:0614141.0123456789) is used for the two uploads, one as test data and one as production data, to demonstrate the potentially unintended entitlement effects of reusing a test EPC as a production EPC (or vice versa).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<epcis:EPCISDocument
  xmlns:epcis="urn:epcglobal:epcis:xsd:1"
  xmlns:example="http://ns.example.com/epcis"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creationDate="2005-07-11T11:30:47.0Z" schemaVersion="1.2">
  <EPCISBody>
    <EventList>
      <ObjectEvent>
        <eventTime>2013-06-08T14:58:56.591Z</eventTime>
        <baseExtension>
          <eventID>urn:uuid:6926712e-599f-4c4e-b6e9-8dd888c906bd</eventID>
        </baseExtension>
        <epcList>
          <epc>urn:epc:id:sscc:0614141.0123456789</epc>
        </epcList>
        <readPoint><id>urn:epc:id:sgln:0614141.00777.0</id></readPoint>
        <bizLocation><id>urn:epc:id:sgln:0614141.00888.0</id></bizLocation>
        <bizTransactionList>
          <bizTransaction type="urn:epcglobal:cbv:btt:desadv">urn:epcglobal:cbv:bt:5412345000037:3352-349875</bizTransaction>
              </bizTransactionList>
        <extension>
          <quantityList>
          </quantityList>
                <sourceList>
                  <source type="urn:epcglobal:cbv:sdt:owning_party">urn:epc:id:sgln:0614141.00001.0</source>
                </sourceList>
                <destinationList>
          </destinationList>
        </extension>
      </ObjectEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Entitlement results

The data entitlement results for the two Observation Event XML uploads above by OrgA, which created test data Asset 1 and production data Asset 2 (both of which reference the same EPC/SSCC) are as follows:

  1. The first Observation Event XML upload above, by OrgA using the test namespace, grants access to test data Asset 1 to OrgB by specification of OrgB as the destination for the shipping event. This XML upload creates a direct entitlement to OrgB from OrgA for Asset 1.
  2. The second Observation Event XML upload above, by OrgA using the default (production) namespace, grants OrgB access to Asset 2, not by specification of OrgB (there is no destination for this shipping event), but because the same EPC/SSCC/container identifier used in test data Asset 1 was also used in production data Asset 2. This XML upload creates a transitive entitlement to OrgB from OrgA for Asset 2.
  3. OrgB now has entitlement to both Asset 1 and Asset 2 owned by OrgA. OrgB can now entitle a third organization, OrgC, to both assets, by referencing the same EPC/SSCC in an XML upload of an event that identifies OrgC. This is the nature of transitive entitlement and is entirely by design, in order to keep interested supply chain partners informed of relevant supply chain events. (OrgC and Asset 3 are introduced below to further demonstrate transitive entitlement.)

Entitlement and deletion of test data

The following scenarios summarize the entitlement effects of uploading the two Observation Event XML examples above, which create test data Asset 1 and production data Asset 2 (JSON identifiers), followed by deletion of Asset 1.

Note: Deletion of test data (uploaded via the Connector API test namespace) is possible on IBM Food Trust because test data is not written to blockchain.

Scenario 1 - No deletion of test data

Scenario 1 uploads the test (Asset 1) and production (Asset 2) data described previously, followed by no deletion of the test data:

  1. OrgA uploads test data for Asset 1 (identifying OrgB as the destination) via Event XML
  2. OrgB is granted access to Asset 1 data via direct entitlement
  3. OrgA uploads production data for Asset 2 (using the same EPC/SSCC identifier as test Asset 1 but with no destination organization) via Event XML
  4. OrgB is granted access to Asset 2 data via transitive entitlement

Summary: Scenario 1 shows transitive entitlement of production data from test data by reusing a test EPC/SSCC for production data.

Scenario 2 - Intermediate deletion of test data

Scenario 2 uploads the test (Asset 1) and production (Asset 2) data described previously, followed by deletion of the test data:

  1. OrgA uploads test data for Asset 1 (identifying OrgB as the destination) via Event XML
  2. OrgB is granted access to Asset 1 data via direct entitlement
  3. OrgA deletes Asset 1 from IBM Food Trust (from Cloud Object Store via IBM Support ticket)
  4. OrgA uploads production data for Asset 2 (using the same EPC/SSCC identifier as test Asset 1 but no destination organization) via Event XML
  5. OrgB is granted access to Asset 2 data via transitive entitlement

Summary: Scenario 2 shows that deleting test data before uploading production data does not prevent or remove transitive entitlement for OrgB (which followed from reuse of a test EPC/SSCC for production data).

Scenario 3 - Subsequent deletion of test data

  1. OrgA uploads test data for Asset 1 (identifying OrgB as the destination) via Event XML
  2. OrgB is granted access to Asset 1 data via direct entitlement
  3. OrgA uploads production data for Asset 2 (using the same EPC/SSCC identifier as test Asset 1 but no destination organization) via Event XML
  4. OrgB is granted access to Asset 2 data via transitive entitlement
  5. OrgA deletes Asset 1 from IBM Food Trust (from Cloud Object Store via IBM Support ticket)
  6. OrgB continues with access to Asset 2 data, because entitlement cannot be reversed once granted

Summary: Scenario 3 shows that deleting test data after uploading production data does not prevent or remove transitive entitlement already created for OrgB (which followed from reuse of a test EPC/SSCC for production data).

General rule of thumb

A general rule of thumb can be used to understand test namespace data entitlement:

IBM Food Trust data entitlement effectively ignores any namespace value specified for any API call.

That is, regardless of namespace value (test, default, production, or other), data entitlement is generated as if all uploaded data has been uploaded as production (namespace=DEFAULT) data, which can never be deleted. And therefore, deletion of test data has no impact on entitlement already granted. This entitlement effect is entirely by design, to allow organizations to upload and integrate test data with production data for robust testing.

However, as shown below, deleting test data does prevent data entitlement further down the supply chain, for transitive data entitlement that has not yet been created.

Extending the example - OrgC and Asset 3

Understanding of IBM Food Trust data entitlement can be furthered by adding a third organization (OrgC) and a third asset (Asset 3) to the previous example. The real world event is OrgB shipping a container to OrgC and uploading the Event XML using the same EPC/SSCC that OrgA used previously for Asset 1 and Asset 2.

Creating production data Asset 3

Organization B (OrgB) uploads production data for Asset 3 via the Event XML below. Note that the DEFAULT (production) namespace is not identified in the XML; the DEFAULT namespace is identified in the header of the Connector API call to the Assets endpoint. OrgB references the same EPC that was used previously by OrgA, specifying OrgC as the destination.

The following API call properties are specified:

  • Entitlement Mode: Linked
  • Namespace: DEFAULT
  • Owning and uploading Organization: OrgB (company prefix 5012345)
  • EPC: urn:epc:id:sscc:0614141.0123456789
  • Destination: urn:epc:id:sgln:6789654.00003.0 (OrgC company prefix 6789654)

IBM Food Trust receives the following Observation Event XML (which creates production data Asset 3 as JSON identifiers):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<epcis:EPCISDocument
  xmlns:epcis="urn:epcglobal:epcis:xsd:1"
  xmlns:example="http://ns.example.com/epcis"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creationDate="2005-07-11T11:30:47.0Z" schemaVersion="1.2">
  <EPCISBody>
    <EventList>
      <ObjectEvent>
        <eventTime>2013-06-08T14:58:56.591Z</eventTime>
        <baseExtension>
          <eventID>urn:uuid:6926712e-599f-4c4e-b6e9-8dd888c906bd</eventID>
        </baseExtension>
        <epcList>
          <epc>urn:epc:id:sscc:0614141.0123456789</epc>
        </epcList>
        <readPoint><id>urn:epc:id:sgln:0614141.00777.0</id></readPoint>
        <bizLocation><id>urn:epc:id:sgln:0614141.00888.0</id></bizLocation>
        <bizTransactionList>
          <bizTransaction type="urn:epcglobal:cbv:btt:desadv">urn:epcglobal:cbv:bt:5412345000037:3352-349875</bizTransaction>
              </bizTransactionList>
        <extension>
          <quantityList>
          </quantityList>
                <sourceList>
                </sourceList>
                <destinationList>
                  <destination type="urn:epcglobal:cbv:sdt:owning_party">urn:epc:id:sgln:6789654.00003.0</destination>
          </destinationList>
        </extension>
      </ObjectEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Entitlement and deletion of test data

The following scenarios summarize the data entitlement effects of uploading the Event XML described previously, which create test data for Asset 1, production data for Asset 2, and production data for Asset 3. All three JSON assets reference the same EPC/SSCC - <epc>urn:epc:id:sscc:0614141.0123456789</epc>.

Scenario 4 - No deletion of test data

Scenario 4 uploads the test data for Asset 1, production data for Asset 2, and production data for Asset 3.

  1. OrgA uploads test data for Asset 1 (identifying OrgB as the destination) via Event XML
  2. OrgB is granted access to Asset 1 data via direct entitlement
  3. OrgA uploads production data for Asset 2 (with the same EPC/SSCC identifier as test Asset 1 but no destination) via Event XML
  4. OrgB is granted access to Asset 2 data via transitive entitlement
  5. OrgB uploads production data for Asset 3 (with the same EPC/SSCC identifier as Asset 1 and Asset 2 and identifying OrgC as the destination) via Event XML
  6. OrgC is granted access to Asset 1 data and Asset 2 data via transitive entitlement, and Asset 3 data via direct entitlement

Summary: Scenario 4 shows transitive entitlement (same EPC) of production data from test data.

Scenario 5 - Preemptive deletion of test data

Scenario 5 uploads the test data for Asset 1 described previously, deletes it, and then proceeds with upload of production data for Asset 2 and production data for Asset 3:

  1. OrgA uploads test data for Asset 1 (identifying OrgB as the destination) via Event XML
  2. OrgB is granted access to Asset 1 data via direct entitlement (destination Org)
  3. OrgA deletes Asset 1 from IBM Food Trust (from Cloud Object Store via IBM Support ticket)
  4. OrgA uploads production data for Asset 2 (using the same EPC/SSCC identifier as test Asset 1 but no destination) via Event XML
  5. OrgB is granted access to Asset 2 data via transitive entitlement (same EPC)
  6. OrgB uploads production data for Asset 3 (with the same EPC/SSCC identifier as Asset 1 and Asset 2 and identifying OrgC as the destination) via Event XML
  7. OrgC is granted access to Asset 2 data via transitive entitlement and Asset 3 data via direct entitlement. Because Asset 1 was deleted before transitive entitlement to OrgC was granted, OrgC does not have entitlement to Asset 1 data.

Summary: Scenario 5 shows that deleting test data (Asset 1) before granting transitive entitlement to OrgC (for Asset 2) prevents transitive entitlement to Asset 1 for OrgC.

Scenario 6 - Later deletion of test data

Scenario 6 uploads the test data for Asset 1 and production data for Asset 2 described previously, deletes Asset 1, and then proceeds with upload of production data for Asset 3:

  1. OrgA uploads test data for Asset 1 (identifying OrgB as the destination) via Event XML
  2. OrgB is granted access to Asset 1 data via direct entitlement (destination Org)
  3. OrgA uploads production data for Asset 2 (using the same EPC/SSCC identifier as test Asset 1 but no destination) via Event XML
  4. OrgB is granted access to Asset 2 data via transitive entitlement (same EPC)
  5. OrgA deletes Asset 1 from IBM Food Trust (from Cloud Object Store via IBM Support ticket)
  6. OrgB uploads production data for Asset 3 (with the same EPC/SSCC identifier as Asset 1 and Asset 2 and identifying OrgC as the destination) via Event XML
  7. OrgC is granted access to Asset 2 data via transitive entitlement and Asset 3 data via direct entitlement. Because Asset 1 was deleted before transitive entitlement to OrgC was granted, OrgC does not have entitlement to Asset 1 data.

Summary: Scenario 6 shows that deleting test data (Asset 1) before granting transitive entitlement to OrgC (for Asset 2) prevents transitive entitlement to Asset 1 for OrgC.