Skip to content

Commit 772f674

Browse files
ZvonimirZvonimir
Zvonimir
authored and
Zvonimir
committed
docs
1 parent 3cfde8c commit 772f674

1 file changed

Lines changed: 194 additions & 44 deletions

File tree

‎packages/plugin-epcis/docs/EPCIS-Integration-Guide.md‎

Lines changed: 194 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ This document explains all fields used in EPCIS 2.0 documents and provides compr
1515
9. [GS1 URN Schemes](#9-gs1-urn-schemes)
1616
10. [API Reference](#10-api-reference)
1717
11. [MCP Tools Reference](#11-mcp-tools-reference)
18+
- [Source Knowledge Assets](#source-knowledge-assets)
19+
- [Event Result Structure](#event-result-structure)
1820
12. [Query Examples](#12-query-examples)
1921
13. [Data Flow & DKG Publishing](#13-data-flow--dkg-publishing)
2022
14. [Sample EPCIS Documents](#14-sample-epcis-documents)
@@ -725,22 +727,59 @@ Query EPCIS events from the DKG using SPARQL.
725727
| `limit` | integer | Results per page (default: 100, range: 1-1000) | `50` |
726728
| `offset` | integer | Results to skip (pagination, min: 0) | `0` |
727729

728-
**Response:**
730+
**Responses:**
731+
732+
| Status | When | Description |
733+
| ----------------------------- | ----------------- | ---------------------------------------------- |
734+
| **200 OK** | Query succeeded | Returns matching events with pagination |
735+
| **400 Bad Request** | Validation failed | Missing filters, invalid date range, or params |
736+
| **500 Internal Server Error** | DKG query failed | Failed to execute SPARQL query against DKG |
737+
738+
**Example (HTTP 200 OK):**
729739

730740
```json
731741
{
732742
"success": true,
733743
"results": [
734-
/* array of matching events */
744+
{
745+
"ual": "did:dkg:otp:2043/0x.../1/private",
746+
"eventType": "https://gs1.github.io/EPCIS/ObjectEvent",
747+
"eventTime": "2024-03-01T08:00:00.000Z",
748+
"bizStep": "https://ref.gs1.org/cbv/BizStep-receiving",
749+
"bizLocation": "urn:epc:id:sgln:4012345.00001.0",
750+
"disposition": "https://ref.gs1.org/cbv/Disp-in_progress",
751+
"readPoint": "urn:epc:id:sgln:4012345.00001.0",
752+
"action": "ADD",
753+
"epcList": "urn:epc:id:sgtin:4012345.011111.1001"
754+
}
735755
],
736-
"count": 5,
756+
"count": 1,
737757
"pagination": {
738758
"limit": 100,
739759
"offset": 0
740760
}
741761
}
742762
```
743763

764+
> Each result row includes a `ual` field identifying which Knowledge Asset graph the event was found in. Array fields (`epcList`, `childEPCList`, `inputEPCs`, `outputEPCs`) are returned as comma-separated strings.
765+
766+
**Example (HTTP 400 Bad Request):**
767+
768+
```json
769+
{
770+
"error": "At least one filter parameter is required."
771+
}
772+
```
773+
774+
**Example (HTTP 500 Internal Server Error):**
775+
776+
```json
777+
{
778+
"success": false,
779+
"error": "Failed to query events"
780+
}
781+
```
782+
744783
---
745784

746785
### GET `/epcis/events/track`
@@ -753,24 +792,42 @@ Track a single EPC through its full supply chain journey. This endpoint always p
753792
| --------- | ------ | -------- | ----------------------------------------- |
754793
| `epc` | string | **Yes** | EPC identifier to track across all events |
755794

756-
**Response:**
795+
**Responses:**
796+
797+
| Status | When | Description |
798+
| ----------------------------- | --------------------- | ---------------------------------- |
799+
| **200 OK** | Query succeeded | Returns matching events for EPC |
800+
| **400 Bad Request** | Missing/invalid `epc` | Query validation failed |
801+
| **500 Internal Server Error** | DKG query failed | Failed to execute full-trace query |
802+
803+
**Example (HTTP 200 OK):**
757804

758805
```json
759806
{
760807
"success": true,
761808
"results": [
762-
/* array of matching events for the EPC */
809+
{
810+
"ual": "did:dkg:otp:2043/0x.../6/private",
811+
"eventType": "https://gs1.github.io/EPCIS/TransformationEvent",
812+
"eventTime": "2024-03-01T14:00:00.000Z",
813+
"bizStep": "https://ref.gs1.org/cbv/BizStep-assembling",
814+
"bizLocation": "urn:epc:id:sgln:4012345.00003.0",
815+
"inputEPCs": "urn:epc:id:sgtin:4012345.011111.1001, urn:epc:id:sgtin:4012345.022222.2001",
816+
"outputEPCs": "urn:epc:id:sgtin:4012345.099999.9001"
817+
}
763818
],
764-
"count": 3
819+
"count": 1
765820
}
766821
```
767822

768-
**Error Responses:**
823+
**Example (HTTP 500 Internal Server Error):**
769824

770-
| Status | When | Description |
771-
| ----------------------------- | --------------------- | ---------------------------------- |
772-
| **400 Bad Request** | Missing/invalid `epc` | Query validation failed |
773-
| **500 Internal Server Error** | DKG query failed | Failed to execute full-trace query |
825+
```json
826+
{
827+
"success": false,
828+
"error": "Failed to query events"
829+
}
830+
```
774831

775832
---
776833

@@ -801,10 +858,39 @@ General-purpose query tool with the same filtering capabilities as `GET /epcis/e
801858

802859
> **Note:** At least one filter parameter is required (excluding `fullTrace`, `limit`, `offset`). Unlike the HTTP API where `fullTrace` is a string (`"true"`/`"false"`), the MCP tool accepts a native boolean.
803860
804-
**Response includes:**
861+
**Response (first content block):**
805862

806-
- Event data with count and pagination
807-
- Source Knowledge Assets with UALs and DKG Explorer links for provenance
863+
```json
864+
{
865+
"summary": "Found 3 EPCIS event(s)",
866+
"count": 3,
867+
"events": [
868+
{
869+
"ual": "did:dkg:otp:2043/0x.../1/private",
870+
"eventType": "https://gs1.github.io/EPCIS/ObjectEvent",
871+
"eventTime": "2024-03-01T08:00:00.000Z",
872+
"bizStep": "https://ref.gs1.org/cbv/BizStep-receiving",
873+
"bizLocation": "urn:epc:id:sgln:4012345.00001.0",
874+
"disposition": "https://ref.gs1.org/cbv/Disp-in_progress",
875+
"readPoint": "urn:epc:id:sgln:4012345.00001.0",
876+
"action": "ADD",
877+
"epcList": "urn:epc:id:sgtin:4012345.011111.1001"
878+
}
879+
],
880+
"pagination": {
881+
"limit": 100,
882+
"offset": 0
883+
}
884+
}
885+
```
886+
887+
When results contain events from DKG Knowledge Assets, a second content block is appended with **Source Knowledge Asset** provenance (see [Source Knowledge Assets](#source-knowledge-assets)).
888+
889+
**Error cases:**
890+
891+
- No filter parameters → `{ "error": "At least one filter parameter is required." }`
892+
- Invalid date range → `{ "error": "Parameter 'to' must be greater than or equal to 'from'." }`
893+
- DKG query failure → `{ "error": "Query failed" }`
808894

809895
---
810896

@@ -818,24 +904,24 @@ Specialized tool for tracking a single item's complete journey through the suppl
818904
| --------- | ------ | -------- | --------------------------------------------------------------- |
819905
| `epc` | string | **Yes** | The EPC to track (e.g., `urn:epc:id:sgtin:0614141.107346.2017`) |
820906

821-
**Response includes:**
907+
**Response (first content block):**
908+
909+
```json
910+
{
911+
"summary": "Tracking: urn:epc:id:sgtin:4012345.011111.1001\nFound 4 event(s) in the supply chain.\n\nJourney Timeline:\n1. [2024-03-01T08:00:00.000Z] receiving @ urn:epc:id:sgln:4012345.00001.0\n2. [2024-03-01T10:00:00.000Z] inspecting @ urn:epc:id:sgln:4012345.00002.0\n3. [2024-03-01T14:00:00.000Z] assembling @ urn:epc:id:sgln:4012345.00003.0\n4. [2024-03-01T16:00:00.000Z] packing @ urn:epc:id:sgln:4012345.00004.0\n",
912+
"epc": "urn:epc:id:sgtin:4012345.011111.1001",
913+
"eventCount": 4,
914+
"events": [
915+
/* chronologically ordered event objects */
916+
]
917+
}
918+
```
822919

823-
- Human-readable timeline summary
824-
- Full event data in chronological order
825-
- Source Knowledge Assets with UALs and DKG Explorer links
920+
The `summary` field contains a human-readable timeline with numbered steps showing `[eventTime] bizStep @ location` for each event. When results are found, a second content block is appended with **Source Knowledge Asset** provenance (see [Source Knowledge Assets](#source-knowledge-assets)).
826921

827-
**Example timeline output:**
922+
**Error cases:**
828923

829-
```
830-
Tracking: urn:epc:id:sgtin:4012345.011111.1001
831-
Found 4 event(s) in the supply chain.
832-
833-
Journey Timeline:
834-
1. [2024-03-01T08:00:00.000Z] receiving @ urn:epc:id:sgln:4012345.00001.0
835-
2. [2024-03-01T10:00:00.000Z] inspecting @ urn:epc:id:sgln:4012345.00002.0
836-
3. [2024-03-01T14:00:00.000Z] assembling @ urn:epc:id:sgln:4012345.00003.0
837-
4. [2024-03-01T16:00:00.000Z] packing @ urn:epc:id:sgln:4012345.00004.0
838-
```
924+
- DKG query failure → `{ "error": "Tracking failed" }`
839925

840926
---
841927

@@ -850,17 +936,22 @@ Validates an EPCIS document and queues it for publishing via the DKG publisher s
850936
| `epcisDocument` | object | **Yes** | EPCIS 2.0 JSON-LD document |
851937
| `publishOptions` | object | No | Optional publishing settings (`privacy`, `epochs`) |
852938

853-
**Success Response includes:**
939+
**Success Response:**
854940

855-
- `captureID` (publisher tracking ID)
856-
- `requestId` (plugin-generated request ID)
857-
- `receivedAt` timestamp
858-
- `eventCount`
941+
```json
942+
{
943+
"captureID": "456",
944+
"requestId": "epcis-1709280001123-a1b2c3",
945+
"receivedAt": "2024-03-01T08:00:01.123Z",
946+
"eventCount": 1
947+
}
948+
```
859949

860950
**Error cases:**
861951

862-
- Validation error (`Invalid EPCISDocument`, empty events)
863-
- Publisher unavailable error
952+
- Validation error → `{ "error": "Invalid EPCISDocument", "details": ["..."] }`
953+
- Empty events → `{ "error": "EPCISDocument contains no events", "message": "..." }`
954+
- Publisher unavailable → `{ "error": "Something went wrong with publishing the EPCIS document.", "message": "..." }`
864955

865956
---
866957

@@ -874,25 +965,84 @@ Checks the publisher-tracked status for a capture request by numeric `captureID`
874965
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
875966
| `captureID` | string | **Yes** | Numeric capture ID (`^[0-9]{1,20}$`) returned by capture handlers |
876967

877-
**Success Response includes:**
968+
**Success Response:**
969+
970+
```json
971+
{
972+
"status": "published",
973+
"captureID": "456",
974+
"UAL": "did:dkg:otp/0x1234.../789",
975+
"publishedAt": "2024-03-01T08:01:23.456Z"
976+
}
977+
```
878978

879-
- `status`
880-
- `captureID`
881-
- Optional `UAL`, `publishedAt`, and `error`
979+
> Fields `UAL`, `publishedAt`, and `error` are only present when applicable to the current status.
882980
883981
**Error cases:**
884982

885-
- Capture not found
886-
- Publisher timeout
887-
- Upstream status lookup failure
983+
- Capture not found → `{ "error": "Capture not found", "captureID": "456" }`
984+
- Publisher timeout → `{ "error": "Publisher timeout", "captureID": "456" }`
985+
- Upstream failure → `{ "error": "Failed to get capture status", "captureID": "456" }`
986+
987+
---
988+
989+
## Source Knowledge Assets
990+
991+
MCP tool responses (`epcis-query` and `epcis-track-item`) include **Source Knowledge Asset provenance** when results are found. This is returned as a second MCP content block (markdown text) listing the unique Knowledge Assets that contained the matching events.
992+
993+
**Format:**
994+
995+
```
996+
**Source Knowledge Assets:**
997+
- **EPCIS ObjectEvent**: EPCIS Plugin
998+
[did:dkg:otp:2043/0x.../1](https://dkg.origintrail.io/explore?ual=did:dkg:otp:2043/0x.../1)
999+
- **EPCIS TransformationEvent**: EPCIS Plugin
1000+
[did:dkg:otp:2043/0x.../6](https://dkg.origintrail.io/explore?ual=did:dkg:otp:2043/0x.../6)
1001+
```
1002+
1003+
Each entry includes:
1004+
1005+
- **Title**: Derived from the event type (e.g., `EPCIS ObjectEvent`)
1006+
- **Issuer**: Always `"EPCIS Plugin"`
1007+
- **UAL**: The cleaned Knowledge Asset UAL (with `/private` or `/public` suffix removed), linked to the DKG Explorer
1008+
1009+
### Event Result Structure
1010+
1011+
SPARQL query results (from both the HTTP API and MCP tools) return events with the following fields:
1012+
1013+
| Field | Description | Example |
1014+
| -------------- | ------------------------------------------------- | ------------------------------------------------------ |
1015+
| `ual` | Knowledge Asset graph containing this event | `did:dkg:otp:2043/0x.../1/private` |
1016+
| `eventType` | Full EPCIS event type URI | `https://gs1.github.io/EPCIS/ObjectEvent` |
1017+
| `eventTime` | When the event occurred (ISO 8601) | `2024-03-01T08:00:00.000Z` |
1018+
| `bizStep` | Business step URI | `https://ref.gs1.org/cbv/BizStep-receiving` |
1019+
| `bizLocation` | Business location identifier | `urn:epc:id:sgln:4012345.00001.0` |
1020+
| `disposition` | Current state/condition URI | `https://ref.gs1.org/cbv/Disp-in_progress` |
1021+
| `readPoint` | Scan/read location identifier | `urn:epc:id:sgln:4012345.00001.0` |
1022+
| `action` | Event action (`ADD`, `OBSERVE`, `DELETE`) | `ADD` |
1023+
| `parentID` | Parent EPC (AggregationEvent) | `urn:epc:id:sscc:4012345.0000000001` |
1024+
| `epcList` | Observed EPCs (comma-separated) | `urn:epc:id:sgtin:4012345.011111.1001` |
1025+
| `childEPCList` | Child EPCs (comma-separated, AggregationEvent) | `urn:epc:id:sgtin:4012345.099999.9001` |
1026+
| `inputEPCs` | Input EPCs (comma-separated, TransformationEvent) | `urn:epc:id:sgtin:4012345.011111.1001, ...` |
1027+
| `outputEPCs` | Output EPCs (comma-separated, TransformationEvent)| `urn:epc:id:sgtin:4012345.099999.9001` |
1028+
1029+
> Array fields (`epcList`, `childEPCList`, `inputEPCs`, `outputEPCs`) are returned as comma-separated strings from the SPARQL `GROUP_CONCAT`. Fields that don't apply to a specific event type will be empty strings.
8881030
8891031
---
8901032

8911033
## 12. Query Examples
8921034

1035+
### Track a Single Item's Journey
1036+
1037+
Use the dedicated track endpoint for full-trace item tracking:
1038+
1039+
```bash
1040+
curl "http://localhost:9200/epcis/events/track?epc=urn:epc:id:sgtin:4012345.011111.1001"
1041+
```
1042+
8931043
### Track All Events for a Product
8941044

895-
Find all events where the carbon frame appears:
1045+
Find all events where the carbon frame appears using the general query with full trace:
8961046

8971047
```bash
8981048
curl "http://localhost:9200/epcis/events?epc=urn:epc:id:sgtin:4012345.011111.1001&fullTrace=true"

0 commit comments

Comments
 (0)