All Categories > Capability Tool > Full Chain Capability Test

Full Chain Capability Test

Updated 3 months ago by Philip Heggelund

Registration

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

Capability Test

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} - this is the API key generated by the solution provider to access 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 Query Interface URL returned from the Solution Provider's GS1 Resolver.

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       {API-KEY-FOR-ACCESSING-CAPABILITY-TOOL-API}

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

The {GDST-VERSION} should be either "11" or "12" to indicate the GDST version. "11" is for GDST 1.1 for the XML format, and "12" is for GDST 1.2 for the JSON-LD format.

This HTTP Request will return the following response:

Content-Type    application/json
{
    "SolutionName" : "{SOLUTION-NAME}",
    "Version" : "{VERSION-OF-SOLUTION}",
    "EPCs" : [
        "{CAPABILITY-TOOL-GENERATED-EPC}"
    ],
    "UUID" : "{CAPABILITY-PROCESS-UUID}"
}

Step 2: Querying for Traceability Data from the Capability Tool

This step will require you to take the {CAPABILITY-TOOL-GENERATED-EPC} and use it to query the traceability data associated with this EPC from the Capability Tool using the communication protocol in the GDST Technical Standard v1.2.

A summary of these steps will include:

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
Performing a trace-back by scanning all inputs of any events returned and querying the EPCIS Query Interface for events associated with those inputs. This step may need to be performed until no more unknown inputs are found.

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

In order to perform this step you will need to execute the following HTTP Request:

HTTP GET 1.1
{CAPABILITY-TOOL-API-URL}/digitallink/00/{CAPABILITY-TOOL-GENERATED-EPC}?linkType=gs1:epcis

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

In this case, we are assuming that the {CAPABILITY-TOOL-GENERATED-EPC} is an SSCC, indicated by the application identifier "00" in the URL path. If it is not an SSCC, but rather an GTIN + LOT NUMBER or a GTIN + SERIAL NUMBER, the URL would be different, following the GS1 Digital Link Resolver standard.

This HTTP Request will return the following response:

[
    {
        "linkType" : "gs1:epcis",
        "link" : "{CAPABILITY-TOOL-API-URL}/epcis",
        "authRequired" : true,
    }
]

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

In order to perform this step, you will need to execute the following HTTP Request:

HTTP GET 1.1
{CAPABILITY-TOOL-API-URL}/epcis/events?MATCH_anyEPC={CAPABILITY-TOOL-GENERATED-EPC}

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

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...
                ]
            }
        }
    }
}

You will also need to perform a trace-back. This is covered in our Trace-Backs and Trace-Forwards article.

Step 3: Moving the Capability Process to the next stage.

Step 3 involves you moving the capability process to the next stage, which tells the Capability Tool that you have pulled across the traceability data from Step 2 and have saved it into your system.

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

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

{
    "SolutionName" : "{SOLUTION-NAME}",
    "Version" : "{VERSION-OF-SOLUTION}"
    "EPCs" : ["{SOLUTION-PROVIDER-GENERATED-EPC}"]
}

There will be no body in the response.

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.

Solution Provider Data

In Step 2, traceability data was generated by the Capability Tool and imported into your traceability system. The generated data should be unique and should demonstrate the full CTE/KDE matrix of the GDST standard. The {SOLUTION-PROVIDER-GENERATED-EPC} above should be the EPC for the final product in the traceability history of that generated data. In the following steps, the Capability Test will query your system for the traceability data associated with that EPC, and perform a trace-back, getting the full history including any source-products. After which, it will then verify that the history has an example of each CTE in the GDST standard and that each CTE has all the KDEs required of it.

Step 4: Capability Tool requests its data back from you

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. However, there is a minor difference here. This step will use the Internal System-to-System communication protocols to pull the data.

NOTE: This step will use the GErecordTime and LErecordTime.

NOTE: this step will not provide an EPC when querying for the EPCIS Query Interface URL from the GS1 Digital Link Resolver.

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}/417/{PGLN}?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 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?GE_recordTime={START-OF-CAPABILITY-PROCESS}&LE_recordTime={CURRENT-UTC-DATETIME}

Accept          application/json
X-API-Key       {CAPABILITY-TOOL-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...
                ]
            }
        }
    }
}

No trace-back is required here.

Step 5: The capability tool requests traceability data for the data generated by the solution provider.

During step 3, you provided one or more EPCs to the Capability Tool. This step will repeat what is in step 4, except starting with the {SOLUTION-PROVIDER-GENERATED-EPC} and using the trace-back method.

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.

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}/sscc/{SOLUTION-PROVIDER-GENERATED-EPC}?linkType=gs1:epcis

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

In this scenario, we are assuming that the {CAPABILITY-TOOL-GENERATED-EPC} is an SSCC. If it is not, the GS1 Digital Link Resolver URL would be formed differently.

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/xml
X-API-Key       {CAPABILITY-TOOL-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...
                ]
            }
        }
    }
}

The Capability Tool will also perform a trace-back. This is covered in our Trace-Backs and Trace-Forwards article.

Step 6: 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                   {YOUR-API-KEY}
X-Compliance-Process-UUID   {CAPABILITY-PROCESS-UUID}

This would respond with:

{
    "solutionName" : "Test Solution",
    "complianceProcessUUID" : "9ed4c7e6-a37c-4597-b650-c0cf73d58b82",
    "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.

Statuses:

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

Stages:

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 has 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:

** Compliance Process Generated Data Errors - CTE/KDE Completeness Check **

    --- Fishing Event

        EVENT ID: 13fbfa98-3df5-49bc-b98b-588b0631363f
            - has no satellite tracking authority specified on the vessel catch information


    --- Landing Event

        EVENT ID: dc90494c-971b-4ba8-9e98-abe5699926c9
            - requires a certificate with type set to 'urn:gdst:certType:humanPolicy'

    --- Receive Event

        EVENT ID: f45a9866-e66f-4dfd-90fe-55035b7cd57b
            - requires a certificate with type set to 'urn:gdst:certType:harvestCoC'

        EVENT ID: 621c73b5-c3f6-499e-b466-b964800cc4f7
            - requires a certificate with type set to 'urn:gdst:certType:harvestCoC'

    --- Farm Harvest Event

        EVENT ID: 7f9490a8-54ea-4f3a-8beb-3928affd9b6c
            - no aquaculture method set
            - requires a certificate with type set to 'urn:gdst:certType:harvestCoC'



** Compliance Process Generated Data Errors - Equality Check

    EVENT ID: 607985c0-93af-4b98-b102-495fcc84d419
        - the disposition values did not match. the source value was "urn:epcglobal:cbv:disp:active" and the target value was "<null>"

    EVENT ID: f45a9866-e66f-4dfd-90fe-55035b7cd57b
        - the disposition values did not match. the source value was "urn:epcglobal:cbv:disp:active" and the target value was "<null>"
        - the source event has a certificate with type urn:gdst:certType:harvestCoC but found no certificate on the target with the same certificate type


    EVENT ID: 13fbfa98-3df5-49bc-b98b-588b0631363f
        - the vessel information - GearType values did not match. the source value was "1" and the target value was "<null>"
        - the vessel information - SatelliteTrackingAuthority values did not match. the source value was "test" and the target value was "<null>"
        - the vessel information - VesselPublicRegistry values did not match. the source value was "test" and the target value was "<null>"

    EVENT ID: 621c73b5-c3f6-499e-b466-b964800cc4f7
        - the disposition values did not match. the source value was "urn:epcglobal:cbv:disp:active" and the target value was "<null>"
        - the source event has a source list item with type urn:epcglobal:cbv:sdt:owning_party and value urn:gdst:example.org:party:Fisherman01.1 that was not found on the target event
        - the source event has a certificate with type urn:gdst:certType:harvestCoC but found no certificate on the target with the same certificate type
        - the source event with event ID 66455272-eb6a-4538-ab36-a27d180dc2ab was not found on the target epcis document
        - the source event with event ID dd824bb5-2aef-4d3a-bc87-91d6c92ecb1a was not found on the target epcis document

    EVENT ID: e5b260a8-4db5-45e3-9ff8-8da095825b62
        - the action values did not match. the source value was "DELETE" and the target value was "ADD"
        - the disposition values did not match. the source value was "" and the target value was "<null>"
        - the kde cbvmda:certificationList is on the source event extension, but not on the target event extension



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

Full Chain Capability Test

Registration

Capability Test

Before we get started...

Variables

Step 1: Starting the Process

Step 2: Querying for Traceability Data from the Capability Tool

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: Moving the Capability Process to the next stage.

Solution Provider Data

Step 4: Capability Tool requests its data back from you

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 5: The capability tool requests traceability data for the data generated by the solution provider.

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 6: Request the Report

Understanding the Errors

How did we do?

Related Articles

Contact