A pallet leaves an origin warehouse on schedule under bill of lading BOL-8841. The next morning, an alert queue opens three tasks for the same shipment: one for a missed hub scan, one for simultaneous dock arrivals at two facilities, and one for a late dock arrival whose carrier record simply landed in the repository after the physical scan.
A freight shipment exception event model breaks when alerting rules fire straight off raw carrier messages as if every scan arrives in order, on time, and without retractions. Operations staff close false alarms while real discrepancies or stalled freight sit buried in the queue.
Using GS1’s third-party EPCIS Standard 2.0 and Core Business Vocabulary (CBV) Standard 2.0 as the reference schema (not an Insonl client), this guide separates an append-only visibility log from derived shipment state so your business intelligence and analytics pipeline classifies late, missing, and conflicting events before creating an operations task.
One EPCIS trace with three failure modes
This JSON-LD response is a made-up example payload (not from a real shipper, carrier, or Insonl client) formatted as an EPCISQueryDocument conforming to the EPCIS 2.0 JSON-LD Context and EPCIS 2.0 JSON Schema. It uses GS1’s example prefix 952 for one pallet SSCC under one bill of lading:
{
"@context": ["https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"],
"type": "EPCISQueryDocument",
"schemaVersion": "2.0",
"creationDate": "2026-11-19T09:15:00Z",
"epcisBody": {
"queryResults": {
"queryName": "SimpleEventQuery",
"resultsBody": {
"eventList": [
{
"type": "ObjectEvent",
"eventID": "urn:uuid:11111111-1111-4111-8111-111111111111",
"eventTime": "2026-11-18T08:15:00Z",
"recordTime": "2026-11-18T08:17:00Z",
"eventTimeZoneOffset": "+07:00",
"epcList": ["https://id.gs1.org/00/095211010000004816"],
"action": "OBSERVE",
"bizStep": "departing",
"disposition": "in_transit",
"readPoint": {"id": "https://id.gs1.org/414/9521101000016/254/gate-1"},
"bizTransactionList": [
{"type": "bol", "bizTransaction": "urn:epcglobal:cbv:bt:9521101000016:BOL-8841"}
]
},
{
"type": "ObjectEvent",
"eventID": "urn:uuid:22222222-2222-4222-8222-222222222222",
"eventTime": "2026-11-19T06:40:00Z",
"recordTime": "2026-11-19T06:42:00Z",
"eventTimeZoneOffset": "+07:00",
"epcList": ["https://id.gs1.org/00/095211010000004816"],
"action": "OBSERVE",
"bizStep": "arriving",
"disposition": "in_transit",
"readPoint": {"id": "https://id.gs1.org/414/9521101000023/254/dock-9"},
"bizTransactionList": [
{"type": "bol", "bizTransaction": "urn:epcglobal:cbv:bt:9521101000016:BOL-8841"}
]
},
{
"type": "ObjectEvent",
"eventID": "urn:uuid:22222222-2222-4222-8222-222222222222",
"eventTime": "2026-11-19T06:40:00Z",
"recordTime": "2026-11-19T09:10:00Z",
"eventTimeZoneOffset": "+07:00",
"epcList": ["https://id.gs1.org/00/095211010000004816"],
"action": "OBSERVE",
"bizStep": "arriving",
"disposition": "in_transit",
"readPoint": {"id": "https://id.gs1.org/414/9521101000023/254/dock-9"},
"bizTransactionList": [
{"type": "bol", "bizTransaction": "urn:epcglobal:cbv:bt:9521101000016:BOL-8841"}
],
"errorDeclaration": {
"declarationTime": "2026-11-19T09:08:00Z",
"reason": "incorrect_data",
"correctiveEventIDs": ["urn:uuid:33333333-3333-4333-8333-333333333333"]
}
},
{
"type": "ObjectEvent",
"eventID": "urn:uuid:33333333-3333-4333-8333-333333333333",
"eventTime": "2026-11-19T06:40:00Z",
"recordTime": "2026-11-19T09:11:00Z",
"eventTimeZoneOffset": "+07:00",
"epcList": ["https://id.gs1.org/00/095211010000004816"],
"action": "OBSERVE",
"bizStep": "arriving",
"disposition": "in_transit",
"persistentDisposition": {"set": ["mismatch_quantity"]},
"readPoint": {"id": "https://id.gs1.org/414/9521101000030/254/dock-2"},
"bizTransactionList": [
{"type": "bol", "bizTransaction": "urn:epcglobal:cbv:bt:9521101000016:BOL-8841"}
]
}
]
}
}
}
}
With a planned dock arrival cutoff of 2026-11-19T07:00:00Z for BOL-8841, a naive consumer makes three mistakes:
- False conflict: Event 2 (
dock-9, GLN9521101000023) and Event 4 (dock-2, GLN9521101000030) shareeventTime. Without applying Event 3’serrorDeclaration, the engine flags simultaneous dock arrivals at two facilities. - False physical delay: Event 4’s repository
recordTime(09:11:00Z) is 2 hours 11 minutes past the07:00:00Zcutoff because it is a corrective event captured after the wrong-dock retraction, even thougheventTime(06:40:00Z) shows the pallet reacheddock-2twenty minutes early. - Missed real exception: Event 4 sets
persistentDisposition: {"set": ["mismatch_quantity"]}at dock check-in—defined in CBV 2.0 Section 7.2.3 as a quantity that disagrees with expectations (an underage or an overage). That quantity discrepancy is the only item here warranting an operations task (when counts are verified later during unpacking, record the mismatch on that separate observation rather than on gate arrival).
Separate the visibility log from derived shipment state
EPCIS 2.0 defines five core event subclasses under EPCISEvent—ObjectEvent, AggregationEvent, TransactionEvent, TransformationEvent, and AssociationEvent—sharing eventTime, eventTimeZoneOffset, repository-assigned recordTime, optional eventID, and optional errorDeclaration. Under EPCIS Section 7.4.1.2, corrections never modify or delete the prior event; instead, a new event is appended and subsequent queries return both the original event and its error declaration.
While an ObjectEvent can explicitly assert that an expected observation failed to occur (EPCIS Section 7.4.2), EPCIS does not store planned transit schedules or run absence-based SLA timers. Split the pipeline into two layers:
- Raw visibility log (append-only): Store every captured or queried event verbatim under its own internal storage key, because
eventIDis optional and an error declaration repeats the originaleventID. - Materialized shipment projection (mutable state): Match each
errorDeclarationagainst prior event content excludingrecordTimeanderrorDeclaration(EPCIS Section 7.4.1.2), track retraction state here, and join active events against the shipment plan—planned legs, destination GLNs, dock arrival cutoffs, carrier grace windows, and parent-child links fromAggregationEvent(parentID,childEPCs,actionADDorDELETE).
Normalize two inputs before updating the projection:
- Business step granularity. CBV 2.0 Section 7.1.3 states that
shippingcoversstaging_outbound,loading, anddepartingwhen granular steps are unavailable, and thatreceivingis mutually exclusive witharrivingandaccepting. Map partnerbizStepvalues into canonical milestone stages so a carrier sendingshippingthenreceivingdoes not trigger missingdepartingorarrivingalerts. - Identifier and vocabulary encoding. EPCIS 2.0 permits identifiers as GS1 Digital Link URIs (
https://id.gs1.org/00/...) or EPC URNs, and CBV values as Web URIs, CBV URNs, or JSON-LD bare words (arriving,in_transit,bol). Canonicalize both at ingest so one pallet never splits across two projection keys.
Rules to separate late, missing, and conflicting events
Classify every shipment deterministically before opening an operations task:
| Condition | Primary EPCIS signal | Meaning | Queue action |
|---|---|---|---|
| Late-recorded, on time | eventTime <= cutoff, recordTime > cutoff |
Physical dock arrival met cutoff; recording or correction lagged | Update projection; close missing-scan timer; log recording lag only |
| Physically late | eventTime > cutoff (active event) |
Shipment missed planned departure or dock arrival | Open or update LATE_PHYSICAL task with eventTime, eventTimeZoneOffset, readPoint |
| Missing milestone | now > cutoff + graceWindow, no active event for stage or parent conveyance |
Expected scan absent past carrier reporting lag | Open MISSING_MILESTONE task; suppress if a downstream stage already exists |
| Skipped intermediate step | Active downstream milestone exists without prior leg | Missed intermediate read or coarser bizStep |
Log data-quality warning; do not page ops as lost freight |
| Retracted conflict | Matching errorDeclaration (optional reason: did_not_occur or incorrect_data) |
Earlier event formally voided by source | Retract prior event; apply correctiveEventIDs if present; open no conflict task |
| Active conflict or discrepancy | Two incompatible active events, or a CBV discrepancy disposition / holding step |
Contradictory locations, post-DELETE movement, quantity/item mismatch, or dock hold |
Open CONFLICT_ACTIVE task with raw-record key(s) (eventID if present) and triggering bizStep, disposition, or persistentDisposition |
Three rules hold in production:
- Separate
eventTimefromrecordTime. Per EPCIS Section 7.4.1,eventTimeis when the capturing application asserts the physical event occurred, whilerecordTimeis ignored on capture and assigned by the repository for bookkeeping and standing queries. Check transit SLAs againsteventTime(keepingeventTimeZoneOffsetfor local dock curfews). BecauserecordTime - eventTimemeasures elapsed time until repository recording—which can include ingestion retries or later corrections—calibrate carrier grace windows from ordinary non-corrective observations. - Propagate container scans via
AggregationEvent. Freight often scans by trailer or containerparentIDinstead of pallet SSCC. Checking onlyObjectEvent.epcListtriggers falseMISSING_MILESTONEalerts while the parent conveyance moves normally. - Apply
errorDeclarationbefore checking conflicts. Per EPCIS Section 7.4.1.2, an error declaration repeats every field of the prior event (includingeventID, the sole case where a non-nulleventIDrepeats) exceptrecordTimeanderrorDeclaration. It can retract an event even whenreasonis omitted. Under CBV Section 7.5.3,reason: "did_not_occur"voids the event with no replacement (CBV-compliant documents prohibit one or morecorrectiveEventIDs), whilereason: "incorrect_data"may link replacements viacorrectiveEventIDs. Only unresolved two-event contradictions (two activereadPointfacilities at overlapping times, or active movement after anObjectEventwithaction: "DELETE") or single-event exception markers—such as business stepholding(CBV Section 7.1.3) or dispositionsdamaged,mismatch_quantity,mismatch_instance, andmismatch_class(CBV Section 7.2.3)—warrant a conflict or discrepancy task. CBV 2.0 recommends storingmismatch_dispositions inpersistentDisposition, where values persist until explicitly cleared withunset.
EPCIS 2.0 query and capture traps that break alert pipelines
- Polling by
GE_eventTimedrops backfilled scans. Advance incremental polling cursors onGE_recordTime(EPCIS Section 8.2.7.1), mirroring the automaticrecordTimebounds of standing queries (Section 8.2.5.2). BecauseGE_recordTimeis inclusive (>=), keep events sharing a boundary timestamp and deduplicate safely on replay. - Unfiltered queries return retracted events alongside error declarations. Per EPCIS Sections 7.4.1.2 and 8.2.7.1, queries return both the original event and its error declaration.
EXISTS_errorDeclarationfilters for error declarations; omitting it returns both ordinary and error-declared events. Never treat rawGET /eventsoutput as clean active state. - Default ordering is unspecified,
orderDirectiondefaults toDESC, and pagination defaults to 30. Per Section 8.2.7.1, omittingorderBylets a repository return events in arbitrary order, even varying across identical queries, andorderDirectiondefaults toDESC. PassorderBy=recordTimefor incremental ingestion ororderBy=eventTimefor trace replay withorderDirection=ASC, and follow the next-page URL in the server’sLinkheader (perPagedefaults to30, Section 12.5;rel="next"is optional, so do not require it) so later-page error declarations are never skipped. - Partial batch captures and missing
eventIDs. OnPOST /capture, EPCIS Section 12.6 defaultsGS1-Capture-Error-Behaviourtorollback(all-or-nothing), whileproceedlets the server capture as many valid events as possible—potentially orphaning a child event from itsAggregationEvent. BecauseeventIDis optional in EPCIS, enforce CBV-compliant IDs at ingest—UUID v1 or v4 (CBV Section 8.9.1) or deterministic EPCIS Event Hash IDs (CBV Section 8.9.2)—and route malformed partner batches to a separate recovery path like a dead-letter queue for ERP integrations. - Keep deterministic classification separate from AI summaries. Just as three-way invoice matching exceptions and Shopify order-status replies separate state lookup from prose generation, let deterministic projection logic compute
LATE_PHYSICAL,MISSING_MILESTONE, orCONFLICT_ACTIVEfirst. Write structured task fields—SSCC,bol, raw-record keys (pluseventIDwhen present),eventTime,recordTime,readPoint, and the triggeringbizStep,disposition, orpersistentDisposition—using the handoff pattern in Zendesk AI handoff ticket fields, and let any AI layer summarize history or draft outreach from that verified record.
Before routing freight events into an operations queue
Insonl is a Ho Chi Minh City engineering studio building business intelligence and analytics pipelines and operational AI workflows. Before wiring carrier feeds and EPCIS streams into an alert queue, map milestone stages, grace windows, and exception ownership with our free AI workflow audit.
The audit is free; work after it is charged separately.
Sources
- GS1 Standards (third-party): EPCIS Standard 2.0, Core Business Vocabulary (CBV) Standard 2.0, EPCIS 2.0 JSON-LD Context, EPCIS 2.0 JSON Schema
- Insonl: Business Intelligence and Analytics, Free AI workflow audit, Three-Way Invoice Matching Exceptions, Shopify Order-Status Replies, Zendesk AI Handoff Ticket Fields, Dead-Letter Queue for ERP Integrations
