All Categories > Capability Tool > First-Mile Capability Test

First-Mile Capability Test

Updated 4 months ago by Philip Heggelund

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).

Querying the Digital Link Resolver of the Capability Tool to Obtain the EPCIS URL

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.

Querying the Digital Link Resolver of the Capability Tool to Obtain the EPCIS URL

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?

(opens in a new tab)

First-Mile Capability Test

Registration

Capability Process

Before we get started...

Variables

Step 1: Starting the Process

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

Querying the Digital Link Resolver of the Capability Tool to Obtain the EPCIS URL

Querying the EPCIS Query Interface for all events associated with the EPC

HTTP Response

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

Querying the Digital Link Resolver of the Capability Tool to Obtain the EPCIS URL

Querying the EPCIS Query Interface for All Events using Record Time

HTTP Response

Step 4: Request the Report

Understanding the Errors

How did we do?

Related Articles

Contact