First-Mile Capability Test

Registration

Please reach out to info@thegdst.org to register.

Capability Process

The capability process is an automated process that can be executed by a solution provider to determine if a specific version of a traceability solution is GDST Capable.

Before we get started...

Before we get started make sure that you have registered for the GDST Capability Tool by following the registration steps above. After that, you will need:

  • the URL to the Capability Tool API
  • your API Key for accessing the Capability Tool API
  • the exact name of the traceability solution provided during registration
  • the version number of the traceability solution you will be accessing
Variables

During this documentation, you will encounter many variables that will be wrapped in curly braces like so "{CAPABILITY_TOOL-API-URL}".

Below is a list of these variables and what they mean:

  • {CAPABILITY-TOOL-API-URL} - the base URL to the capability tool.
  • {SOLUTION-NAME} - the name of your registered solution.
  • {SOLUTION-PROVIDER-API-KEY} - API key generated by the solution provider to grant access to the API of the solution provider.
  • {CAPABILITY-TOOL-API-KEY} - this is the API key that the capability tool will use to access your digital link resolver and EPCIS query interface.
  • {VERSION-OF-YOUR-SOLUTION} - the version of the traceability solution you are testing
  • {CAPABILITY-TOOL-GENERATED-EPC} - one or more EPCIS for product instances generated by the capability tool.
  • {SOLUTION-PROVIDER-GENERATED-EPC} - one or more EPCIS for product instances generated by the solution provider.
  • {CAPABILITY-PROCESS-UUID} - the UUID of the capability process generated and returned to you when you start the capability process.
  • {SOLUTION-PROVIDER-URL} - This is the GS1 Resolver URL provided to the Capability Tool by the solution provider.
  • {SOLUTION-PROVIDER-EPCIS-URL} - This is the EPCIS URL.

Step 1: Starting the Process

In order to start the process, you will perform the following HTTP Request:

HTTP Post 1.1
{CAPABILITY-TOOL-API-URL}/process/start

Accept application/json
Content-Type application/json
X-API-Key {YOUR-API-KEY}

{
"SolutionName" : "{YOUR-SOLUTION-NAME}",
"Version" : "{VERSION-OF-YOUR-SOLUTION}",
"APIKey" : "{API-KEY-FOR-ACCESSING-SOLUTION-PROVIDER-API}",
"URL" : "{SOLUTION-PROVIDER-URL}",
"PGLN" : "{YOUR-SOLUTION-PGLN}",
"GDSTVersion": "{GDST-VERSION}",
"EPCS": ["{SOLUTION-PROVIDER-GENERATED-EPC}"]
}

The 'Version' should be the version of your solution that you are testing. This version number is what will be displayed on the public GDST Capable Solutions list.

The 'GDSTVersion' must be either '11' for GDST 1.1 or '12' for GDST 1.2.

This HTTP Request will return the following response:

Content-Type    application/json
{
"SolutionName" : "{YOUR-SOLUTION-NAME}",
"Version" : "{VERSION-OF-YOUR-SOLUTION}",
"UUID" : "{CAPABILITY-PROCESS-UUID}"
}

Step 2: Capability Tool Requests Solution Generated Data using B2B Workflow

When you started the capability process, you provided one or more EPCs represented in this documentation as {SOLUTION-PROVIDER-GENERATED-EPC}. In this step, the Capability Tool is going to query your GS1 Resolver / EPCIS Query Interface to pull back traceability data related to this EPC(s).

In order to perform this step the capability tool will execute the following HTTP Request:

HTTP GET 1.1
{SOLUTION-PROVIDER-URL}/00/{SOLUTION-PROVIDER-GENERATED-EPC}?linkType=gs1:epcis

Accept application/json
X-API-Key {SOLUTION-PROVIDER-API-KEY}

This HTTP Request will return the following response:

[
{
"linkType" : "gs1:epcis",
"link" : "{SOLUTION-PROVIDER-EPCIS-URL}",
"authRequired" : true,
}
]
Querying the EPCIS Query Interface for all events associated with the EPC

In order to perform this step, the capability tool will execute the following HTTP Request:

HTTP GET 1.1
{SOLUTION-PROVIDER-EPCIS-URL}/events?MATCH_anyEPC={SOLUTION-PROVIDER-GENERATED-EPC}

Accept application/json
X-API-Key {SOLUTION-PROVIDER-API-KEY}
HTTP Response
Content-Type	            application/json
GS1-EPCIS-Version 2.0
GS1-EPCIS-Min 2.0
GS1-EPCIS-Max 2.0
GS1-CBV-Version 2.0
GS1-EPC-Version ALWAYS_EPC_URN
GS1-CBV-XML-Format ALWAYS_URN

{
"@context": [
"https://ref.gs1.org/standards/epcis/epcis-context.jsonld",
{
"gdst": "https://traceability-dialogue.org/epcis"
}
],
"type": "EPCISQueryDocument",
"creationDate": "2022-09-05T19:04:37.5450000+00:00",
"schemaVersion": "2.0",
"epcisBody": {
"queryResults": {
"subscriptionID": "32d2aec1-a6d2-46d9-900a-24124288cce1",
"queryName": "SimpleEventQuery",
"resultsBody": {
"eventList": [
// events go here...
]
}
}
}
}

This example assumes the {SOLUTION-PROVIDER-GENERATED-EPC} is an instance-level EPC, if it was a class-level EPC, then you would use the MATCH_anyEPCClass filter instead.

The Capability Tool will also perform a trace-back. This is covered in our Communication Protocol / Trace-back article.

Master data is resolved using the GS1 Digital Link resolution method as described in the GDST technical standard (both 1.1 and 1.2).

Step 3: Capability Tool Requests Solution Generated Data using Internal System-to-System

At this point the Capability Tool is going to use the same communication protocols from step 2 to request the same data back from you.

NOTE: This step will use the GE_recordTime and LE_recordTime. It will scan the events returned in step 2 to find the min/max record time.

In order to perform this step, the capability tool will execute the following HTTP Request:

HTTP GET 1.1
{SOLUTION-PROVIDER-URL}/00/{SOLUTION-PROVIDER-GENERATED-EPC}?linkType=gs1:epcis

Accept application/json
X-API-Key {CAPABILITY-TOOL-API-KEY}

This HTTP Request will return the following response:

[
{
"linkType" : "gs1:epcis",
"link" : "{SOLUTION-PROVIDER-EPCIS-URL}",
"authRequired" : true,
}
]

Querying the EPCIS Query Interface for All Events using Record Time

In order to perform this step, the capability tool will execute the following HTTP Request:

HTTP GET 1.1
{SOLUTION-PROVIDER-EPCIS-URL}/events?GE_recordTime={START_OF_CAPABILITY_PROCESS}&LE_recordTime={CURRENT_UTC_DATETIME}

Accept application/json
X-API-Key {API-KEY-FOR-ACCESSING-SOLUTION-PROVIDER-API}

HTTP Response
Content-Type	            application/json
GS1-EPCIS-Version 2.0
GS1-EPCIS-Min 2.0
GS1-EPCIS-Max 2.0
GS1-CBV-Version 2.0
GS1-EPC-Version ALWAYS_EPC_URN
GS1-CBV-XML-Format ALWAYS_URN

{
"@context": [
"https://ref.gs1.org/standards/epcis/epcis-context.jsonld",
{
"gdst": "https://traceability-dialogue.org/epcis"
}
],
"type": "EPCISQueryDocument",
"creationDate": "2022-09-05T19:04:37.5450000+00:00",
"schemaVersion": "2.0",
"epcisBody": {
"queryResults": {
"subscriptionID": "32d2aec1-a6d2-46d9-900a-24124288cce1",
"queryName": "SimpleEventQuery",
"resultsBody": {
"eventList": [
// events go here...
]
}
}
}
}

No trace-back is required here.

Step 4: Request the Report

At any point during the capability process you can request a report about the capability process. You can use this method to poll for the status until steps 4 and 5 are complete.

Once completed, you can see if you passed or fail and a list of errors about what failed, if anything.

HTTP Get 1.1
{CAPABILITY-TOOL-API-URL}/process/report

Accept application/json
Content-Type application/json
X-API-Key {CAPABILITY-TOOL-API-KEY}
X-Capability-Process-UUID {CAPABILITY-PROCESS-UUID}

This would respond with:

{
"solutionName" : "{SOLUTION-NAME}",
"complianceProcessUUID" : "{CAPABILITY-PROCESS-UUID}",
"status" : 0,
"stage" : 3,
"errors" : []
}

For the this call you need to make sure to include the X-Capability-Process-UUID header in the request call including the UUID for the capability process you started.

Stage:

  • 0 = unknown
  • 1 = full-chain stage #1
  • 2 = full-chain stage #2
  • 3 = first mile stage #1
  • 4 = finished

Status:

  • 0 = started
  • 10 = failed - indicates you completed the capability process with errors
  • 11 = passed - indicates you completed the capability process with no errors
  • 12 = approved - a gdst team member as reviewed your passed capability process and approved it
  • 13 = timed out - automatically set to this if not passed or failed within 2 hours
Understanding the Errors

Potential when you get the report, it might contain errors. The report also provides a text-formatted copy of the report for human reading. It also contains an array of each error.

Using the error report, you can have errors from three categories:

  • Found an error when checking the capability process generated data for CTE/KDE completeness errors. This is the data that the capability tool generated, you requested from the capability tool, and then the capability tool then requested back from you.
  • Found an error when checking the capability process generated data for equality errors. The data that was generated by the capability tool, requested by you, and then requested back by the capability tool needs to be the same as the original generated data.
  • Found an error when checking the data you generated for CTE/KDE completeness errors.

The human-readable version might look something like this:

** Traceability Solution Generated Data Errors - CTE/KDE Completeness Check **

- none of the product definitions have a product form set, at least one shave have the product form set

--- Landing Event

EVENT ID: 42f45aae-6bba-4e94-95f7-c0f27726a46e
- requires a certificate with type set to 'urn:gdst:certType:humanPolicy'

--- Processing Event

EVENT ID: 9553669b-2942-42a2-8c10-400968fd056a
- has no expiration date set on the ILMD
- has no country of origin set or the value was invalid

EVENT ID: 442a7cab-cf87-4269-8a65-8913f9431316
- has no expiration date set on the ILMD
- has no country of origin set or the value was invalid

--- Aggregate Event
* Failed to find event with type Aggregation, action ADD, and business step urn:epcglobal:cbv:bizstep:packing


How did we do?


Powered by HelpDocs (opens in a new tab)

Powered by HelpDocs (opens in a new tab)