How to Use the WholeChain CSV Template for Event Uploads

Overview

This guide explains how to use the WholeChain CSV template to upload supply chain events when you have already set up your products, locations, and trade partners in WholeChain. This method allows you to reference existing IDs for these entities, ensuring accuracy and consistency in your supply chain data.

The CSV template supports multiple event types, but this guide focuses on the Aggregation Event, which allows you to log when multiple product lots are aggregated into a container or unit in your supply chain.

Aggregation Event

The Aggregation Event records the grouping of multiple lots or product instances into a single container or logistic unit.

Aggregating Multiple Lots

If you are aggregating multiple lots into a container, you must specify which lots are being grouped together within that container.
Use multiple rows with the same Container ID to represent the individual lots inside the container.
Each row should have a unique Lot Serial, while sharing the same Container ID and Event ID -> Id, ensuring proper traceability of each lot within the aggregated shipment.

Example:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-Id	Container-Id	Container-Type
EVT001	aggregation	urn:epcglobal:cbv:bizstep:assembling	urn:epcglobal:cbv:disp:active	2024-03-30T14:00:00Z	-05:00	PO1990091	INV12314154	LOT1990091	190.75	PROD_000	LOC_000	CNT123456	LogisticId
EVT001	aggregation	urn:epcglobal:cbv:bizstep:assembling	urn:epcglobal:cbv:disp:active	2024-03-30T14:00:00Z	-05:00	PO1990091	INV12314154	LOT1990092	210.50	PROD_000	LOC_000	CNT123456	LogisticId
EVT001	aggregation	urn:epcglobal:cbv:bizstep:assembling	urn:epcglobal:cbv:disp:active	2024-03-30T14:00:00Z	-05:00	PO1990091	INV12314154	LOT1990093	175.25	PROD_000	LOC_000	CNT123456	LogisticId

Download CSV Example

Required Fields for the Aggregation Event

For a successful upload, your CSV file must include the following mandatory fields:

Mandatory Fields for All Aggregation Events

Regardless of the type of aggregation, these fields are required:

Id – A unique identifier for this aggregation event. Each new aggregation event must have a unique ID.
Type – The type of event (e.g., "Aggregation").
BizStep – The business step of the event (see possibilities here).
Disposition – The status of the product upon aggregation (see possibilities here).
EventTime – The timestamp of when the event occurred. (See format in example)
EventTimeZone – The time zone of the event timestamp. (See format in example)
PurchaseOrder – The purchase order number associated with this aggregation.
InvoiceNumber – The invoice number related to the purchase order.
ProductInstance-LotSerial – The unique identifier for the lot being aggregated.
ProductInstance-Quantity – The quantity of the product being aggregated.
ProductInstance-ProductId – The identifier for the aggregated product.
Location-Id - The internal ID of the location where the aggregation takes place.
Container-Id - The identifier for the container or logistic unit into which the products are aggregated.
Container-Type - The type of container or logistic unit used for the aggregation. ("SSCC" or "LogisticId")

Adding Certifications

You may want to add certifications that you have for specific lots being aggregated. The process for adding certifications is identical to other event types. You can add multiple certifications per lot by including the certification template headers in your row in addition to the mandatory fields.

To add the certifications, add the following fields:

Certification Type → certification1-type
Certification Standard → certification1-standard
Certification Agency → certification1-agency
Certification Value → certification1-value
Certification Identification → certification1-identification

If you would like to add multiple certifications, simply add additional fields and change the prefix (1 -> 2). For example:

Certification Type → certification2-type
Certification Type → certification3-type

Example with Certifications

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-Id	Container-Id	Container-Type	Certification1-Type	Certification1-Standard	Certification1-Agency	Certification1-Value	Certification1-Identification
EVT002	aggregation	urn:epcglobal:cbv:bizstep:assembling	urn:epcglobal:cbv:disp:active	2024-03-30T14:00:00Z	-05:00	PO1990091	INV12314154	LOT1990091	190.75	PROD_000	LOC_000	CNT123456	LogisticId	urn:gdst:certType:harvestCoC	MSC Chain of Custody	MSC	NO	NA

These fields are free-text fields, meaning you can enter any relevant certification details that apply to your aggregated products or containers.

Download CSV Example

Adding Global Dialogue for Seafood Traceability (GDST) Data

There may be instances where you want to add Global Dialogue for Seafood Traceability (GDST) data to your event. If this is the case, you need to use specific headers that enable the Wholechain system to identify that the data belongs to the GDST framework.

Understanding the Difference: Aquaculture vs. Wild Harvest

The required GDST fields differ depending on whether the seafood product comes from aquaculture (farmed seafood) or wild-harvest (wild-caught seafood).

For GDST, most of the necessary fields are already included within the mandatory aggregate event fields. These fields capture key information about the product however, there are additional fields that are needed.

Required GDST Fields

For both aquaculture and wild-harvest seafood, you must include:

Product Owner → cbv-productOwner
Information Provider → cbv-informationProvider
Species (Scientific Name) → productMasterData-gdst-speciesName
Species (3-letter Code) → productMasterData-gdst-speciesCode
Chain of Custody Certification → Use the same certification format explained in the certification section.

For wild-harvest seafood only, you must also include:

Product Form → productMasterData-gdst-productForm
Product Short Description → product-name

Example with GDST Data:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-Id	Container-Id	Container-Type	cbv-productOwner	cbv-informationProvider	productMasterData-gdst-speciesName	productMasterData-gdst-speciesCode	productMasterData-gdst-productForm	product-name	certification1-type	certification1-standard	certification1-agency	certification1-value	certification1-identification
EVT123	aggregation	urn:epcglobal:cbv:bizstep:receiving	urn:epcglobal:cbv:disp:in_progress	2024-03-30T16:00:00+00:00	-05:00	PO001	INV001	Loading Dock	LOT001	100	PROD123	WAREHOUSE001	CONT001	SSCC	OceanCorp	TraceData Ltd	Thunnus albacares	YFT	Frozen Loins	Premium-grade frozen tuna loins	MSC	Chain of Custody	Marine Stewardship Council	Certified	MSC-C-12345

These fields should be added per row in addition to the mandatory event fields when submitting GDST data.

Download CSV Example

Adding FSMA 204 Traceability Log Code (TLC) Data

If you need to comply with FSMA 204 regulations, you must provide data related to the Traceability Log Code (TLC) Source. The following additional fields are required:

TLC Source Name → tlcSource-name
TLC Source City → tlcSource-city
TLC Source State → tlcSource-state
TLC Source Country → tlcSource-country
TLC Source Address Line 1 → tlcSource-addressLine1
TLC Source Address Line 2 → tlcSource-addressLine2
TLC Source Postal Code → tlcSource-postalCode

Example with FSMA 204 Data:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-Id	tlcSource-name	tlcSource-city	tlcSource-state	tlcSource-country	tlcSource-addressLine1	tlcSource-addressLine2	tlcSource-postalCode
EVT123	aggregation	urn:epcglobal:cbv:bizstep:receiving	urn:epcglobal:cbv:disp:in_progress	2024-03-30T16:00:00+00:00	-05:00	PO001	INV001	Loading Dock	LOT001	100	PROD123	WAREHOUSE001	Ocean Logistics	Los Angeles	CA	USA	123 Seafood Way	Suite 200	90001

Download CSV Example

Adding Custom Data

There may be a time when you want to add custom data to your events or products when uploading your CSV to the Wholechain system. Wholechain allows users to define custom fields that can be added either at the product level or the instance (event) level, depending on whether the data should remain consistent across all events for a product or be specific to individual events.

Product-Level Data (Product Master Data) – This data is associated with the product itself and remains constant for all instances of that product.
Instance-Level Data (Event-Level Data) – This data is specific to an individual event and can change with each new transaction.

Example of Product-Level and Instance-Level Custom Data

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-ID	Container-Id	Container-Type	custom-dogsname	ProductMasterData-CustomDashDogSpecies
AGGREG9	aggregation	urn:epcglobal:cbv:bizstep:receiving	urn:epcglobal:cbv:disp:in_progress	2025-03-26T16:00:00+00:00	-05:00	PO001333	INV00133	Loading Dock	LOT034	10	676767	77777	CONT0334A	SSCC	Max	Canis familiaris

In this example:

ProductMasterData-CustomDashDogSpecies is defined at the product level and remains constant across all events.
custom-dogsname is defined at the instance level and can be customized for each event.

This flexibility allows users to maintain structured product attributes while dynamically updating specific event-level data when needed.

Download CSV Example

Download Excel Template

You can download the Excel template using the link below:

Download CSV Template