Skip to main content

EPCIS 2.0 Integration

EPCIS 2.0 (Electronic Product Code Information Services) is the GS1 global standard for supply chain event data. This guide covers mapping Optropic provenance events to EPCIS 2.0 and enabling interoperability with legacy supply chain systems.

Overview​

What is EPCIS 2.0?​

EPCIS 2.0 is a standardized XML/JSON framework for capturing and sharing supply chain events. It enables:

  • Visibility: Track products through the entire supply chain
  • Interoperability: Exchange data between different systems and trading partners
  • Standards Compliance: Align with GS1 global standards
  • Event Types: Object, Aggregation, Transaction, and Transformation events

Key Specifications:

  • Standard: GS1 EPCIS 2.0.1 (Latest)
  • Format: XML and JSON representations
  • EPC Identifiers: GTIN, Serial Numbers, Batch/Lot
  • Event Attributes: Timestamp, Location, Business Step, Disposition

Provenance Event Mapping​

Optropic provenance events map to EPCIS 2.0 event types as follows:

Optropic EventEPCIS 2.0 EventBusiness StepDispositionDescription
manufacturedTransformationEventcommissioningactiveProduct created; raw materials transformed into finished product
labeledObjectEventencodingencodedDPP or serial number assigned to product
enrolledObjectEventcommissioningactiveProduct registered in DPP Registry (approximate mapping)
shippedObjectEventshippingin_transitProduct handed to carrier/logistics provider
receivedObjectEventreceivingactiveProduct received at destination and inventory updated
transferredTransactionEventholdingactiveOwnership/custody transferred between parties (approximate)
verifiedObjectEventinspectingactiveQuality, compliance, or authenticity verified
recalledObjectEventholdingrecalledProduct recalled due to safety/compliance issue
destroyedObjectEventdecommissioningdestroyedProduct permanently destroyed/recycled
customObjectEventholdingactiveUser-defined event (fallback mapping)

Core Functions​

mapToEPCIS / map_to_epcis​

Converts a single Optropic provenance event to EPCIS 2.0 format:

import { ProvenanceEvent, mapToEPCIS, EventType } from '@heimdall/epcis';

const event: ProvenanceEvent = {
  eventType: EventType.SHIPPED,
  productId: "08714043123452",
  timestamp: "2026-03-15T14:30:00Z",
  location: "DE-BW-70174", // GS1 GLN (or ISO 3166-1 + postal code)
  actor: "logistics.company@example.com",
  metadata: {
    carrier: "DPD Express",
    trackingNumber: "DPD123456789",
    expectedDeliveryDate: "2026-03-18"
  }
};

const epcisEvent = mapToEPCIS(event);
console.log(JSON.stringify(epcisEvent, null, 2));
/* Output:
{
  "type": "ObjectEvent",
  "eventID": "urn:uuid:...",
  "eventTime": "2026-03-15T14:30:00Z",
  "recordTime": "2026-03-15T14:30:00Z",
  "epcList": ["urn:epc:id:sgtin:..."],
  "action": "OBSERVE",
  "bizStep": "urn:epcis:vtype:BusinessStep#shipping",
  "disposition": "urn:epcis:vtype:Disposition#in_transit",
  "readPoint": {
    "id": "urn:epc:id:sgln:...location"
  },
  "bizLocation": {
    "id": "urn:epc:id:sgln:...location"
  },
  "bizTransactionList": [
    {
      "type": "urn:epcis:vtype:BizTransactionType#po",
      "bizTransaction": "..."
    }
  ],
  "extension": {
    "carrier": "DPD Express",
    "trackingNumber": "DPD123456789"
  }
}
*/

toEPCISEvent / to_epcis_event​

Lower-level function for constructing EPCIS event objects with granular control:

import { toEPCISEvent, EPCISEventType } from '@heimdall/epcis';

const epcisEvent = toEPCISEvent({
  type: EPCISEventType.OBJECT,
  eventID: "urn:uuid:12345678-1234-5678-1234-567812345678",
  eventTime: "2026-03-15T14:30:00Z",
  recordTime: "2026-03-15T14:30:01Z",
  epcList: [
    "urn:epc:id:sgtin:0871404.312345.2026001",
    "urn:epc:id:sgtin:0871404.312345.2026002"
  ],
  action: "OBSERVE",
  bizStep: "urn:epcis:vtype:BusinessStep#shipping",
  disposition: "urn:epcis:vtype:Disposition#in_transit",
  readPoint: {
    id: "urn:epc:id:sgln:0871404.00001.0"
  },
  bizLocation: {
    id: "urn:epc:id:sgln:0871404.00001.0"
  },
  extension: {
    carrier: "DPD Express",
    temperature: 22.5,
    humidity: 45
  }
});

console.log(epcisEvent);

buildEPCISDocument / build_epcis_document​

Constructs a complete EPCIS document containing multiple events:

import { buildEPCISDocument } from '@heimdall/epcis';

const epcisDocument = buildEPCISDocument({
  version: "2.0.1",
  schemaVersion: "urn:gs1:gtin:13",
  creationDateTime: "2026-03-15T15:00:00Z",
  sender: {
    gln: "5412345000013",
    name: "ACME Corporation"
  },
  receiver: {
    gln: "4006381333931",
    name: "Distributor Ltd"
  },
  events: [epcisEvent1, epcisEvent2, epcisEvent3],
  masterData: {
    epcClassList: [
      {
        epc: "urn:epc:class:lgtin:0871404.312345.2026",
        attributes: {
          productName: "Eco Battery Pack 5000mAh",
          productBrand: "Green Energy"
        }
      }
    ]
  }
});

// Serialize to XML
const xmlDocument = epcisDocument.toXML();
console.log(xmlDocument);

provenanceChainToEPCIS / provenance_chain_to_epcis​

Converts an entire provenance chain to an EPCIS document:

import { provenanceChainToEPCIS } from '@heimdall/epcis';

const provenanceChain = [
  {
    eventType: EventType.MANUFACTURED,
    timestamp: "2026-01-10T08:00:00Z",
    location: "CN-SH-200010",
    actor: "factory@greenergy.cn"
  },
  {
    eventType: EventType.LABELED,
    timestamp: "2026-01-10T09:30:00Z",
    location: "CN-SH-200010",
    actor: "labeling@greenergy.cn"
  },
  {
    eventType: EventType.SHIPPED,
    timestamp: "2026-01-15T14:00:00Z",
    location: "CN-SH-200010",
    actor: "export@greenergy.cn",
    metadata: { carrier: "COSCO" }
  },
  {
    eventType: EventType.RECEIVED,
    timestamp: "2026-02-20T16:30:00Z",
    location: "DE-BW-70174",
    actor: "warehouse@distributor.de"
  }
];

const epcisDocument = provenanceChainToEPCIS(
  provenanceChain,
  {
    gs1CompanyPrefix: "0871404",
    gtin: "08714043123452",
    serialNumber: "2026001"
  }
);

console.log(epcisDocument.toJSON());

EPCIS 2.0 supports GS1 Digital Links, which enable web-resolvable product URLs:

import { mapToEPCIS, GenerateDigitalLinkOptions } from '@heimdall/epcis';

const event = {
  eventType: EventType.SHIPPED,
  productId: "08714043123452",
  timestamp: "2026-03-15T14:30:00Z",
  location: "DE-BW-70174"
};

const epcisEvent = mapToEPCIS(event, {
  gs1CompanyPrefix: "0871404",
  generateDigitalLink: true,
  digitalLinkBaseUrl: "https://id.gs1.org" // Default GS1 resolver
});

console.log(epcisEvent.extension?.digitalLink);
// Output: https://id.gs1.org/01/08714043123452

EPCIS Event Types Reference​

ObjectEvent​

Captures events where objects (products) are observed at a location:

  • Common Use: Shipping, receiving, quality checks
  • Action: OBSERVE, ADD, DELETE
  • Disposition: active, in_transit, recalled, destroyed

TransformationEvent​

Captures events where raw materials are transformed into finished products:

  • Common Use: Manufacturing, assembly
  • Input/Output EPCs: Distinguish consumed vs. produced items

TransactionEvent​

Captures business transactions:

  • Common Use: Purchase orders, invoices
  • Party: Seller, buyer, invoice recipient

AggregationEvent​

Captures grouping of products into larger units:

  • Common Use: Pallet formation, case packing

Integration Patterns​

Pattern 1: DPP + EPCIS Workflow​

  1. Create DPP metadata for product
  2. Generate initial manufactured and labeled provenance events
  3. Map events to EPCIS using mapToEPCIS
  4. Transmit EPCIS document to GS1 network or trading partner

Pattern 2: Existing Supply Chain System​

  1. Extract supply chain events from legacy system (ERP, WMS)
  2. Map to Optropic ProvenanceEvent format
  3. Use provenanceChainToEPCIS to generate EPCIS document
  4. Publish to GS1 Discovery Service or internal resolver

Pattern 3: Real-Time Event Streaming​

  1. Listen to supply chain events (IoT sensors, checkpoint scanning)
  2. Build EPCIS events incrementally
  3. Push to EPCIS repository or subscription service
  4. Enable downstream partners to query events

Best Practices​

1. Unique Event Identifiers​

Always generate unique eventID (UUID v4) for each event:

urn:uuid:12345678-1234-5678-1234-567812345678

2. Timestamp Accuracy​

Use ISO 8601 timestamps with timezone information:

2026-03-15T14:30:00Z (UTC)
2026-03-15T14:30:00+02:00 (with offset)

3. EPC Encoding​

Use standardized EPC URIs for traceability:

  • SGTIN (Serialized GTIN): urn:epc:id:sgtin:...
  • SSCC (Serial Shipping Container Code): urn:epc:id:sscc:...
  • GTIN (Global Trade Item Number): urn:epc:id:gtin:...

4. Business Context​

Always include business step and disposition for downstream queries:

bizStep: "urn:epcis:vtype:BusinessStep#receiving"
disposition: "urn:epcis:vtype:Disposition#active"

5. Extension Data​

Leverage extension field for custom metadata while maintaining standard compliance:

extension: {
  temperature: 22.5,
  humidity: 45,
  signedBy: "warehouse_manager@company.com"
}