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 Ship Event, which allows you to log when products or containers are shipped.

Ship Event

The Ship Event records the shipment of a product or a container. There are two ways to record a ship event:

Shipping a Single Lot – Used when shipping one specific lot without a container.
Shipping a Container with Multiple Lots – Used when shipping multiple product lots within a single container.

1. Shipping a Single Lot

If you are shipping a single product lot, you only need to provide the lot information.
Do not include the container ID or Container Type Columns in your CSV file.
Each row represents one shipped lot.

Example:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	ShipFromLocation-Id	ShipToLocation-Id
EVT123	ship	urn:epcglobal:cbv:bizstep:shipping	urn:epcglobal:cbv:disp:in_progress	2025-01-01T12:00:00Z	-05:00	PO001	INV001	Loading Dock	LOT001	100	PROD123	SUPPLIER001	WAREHOUSE001

Download Example CSV

2. Shipping a Container with Multiple Lots

If you are shipping a container, you must specify which lots are inside the container.
Use multiple rows with the same container ID to indicate the lots that are inside that container.
Each row should have a unique Lot Serial but share the same Container ID.

Example:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ShipFromLocation-Id	ShipToLocation-Id	Container-Id	Container-Type
SHIP11	ship	urn:epcglobal:cbv:bizstep:shipping	urn:epcglobal:cbv:disp:in_progress	2025-07-30T16:00:00+00:00	-05:00	PO001	INV001	Loading Dock	77777	77777	CONT029	SSCC

Download CSV Example

Required Fields for the ship Event

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

Mandatory Fields for All ship Events

Regardless of whether you are shipping a single lot or a container, these fields are required:

Id – A unique identifier for this ship event. Each new row must have a unique ID.
Type – The type of event (e.g., "ship").
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 shipment.
InvoiceNumber – The invoice number related to the purchase order.
ReadPoint – The place within the location where the event took place.
ProductInstance-LotSerial – The unique identifier for the lot shipped.
ProductInstance-Quantity – The quantity of the product shipped.
ProductInstance-ProductId – The identifier for the shipped product.
ShipFromLocation-Id – The ID of the location from where the shipment was sent.
ShipToLocation-Id – The ID of the destination location.

Additional Mandatory Fields for Container shipments

If you are shipping a container, you must also include:

Container-Id – The unique identifier of the shipped container.
Container-Type – The type of container used (Options: "SSCC" or "LogisticId").

Flexible Column Usage

Only include the columns that are relevant to your event type.
If a field is not applicable to your event, do not include it in your CSV file.
Example: If you are shipping a single lot (not a container), do not include the "Container-Id" and "Container-Type" columns.

Adding Certifications

You may want to add certifications that you have for specific lots. You are not limited in the number of certifications you can add. You may add multiple certifications to a lot or container if needed. Wholechain provides a template for adding these certifications.

Whether you are shipping a container or a lot, you can attach any number of certifications to that specific lot or container. To do this, you would add the certification information per row. If you are adding certifications, simply include 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:

🚨 Important Notice:
In the example, we have included both product-level data (ProductInstance-LotSerial, ProductInstance-Quantity) and container information (Container-Id, Container-Type).

However, when submitting the event, only populate either the product-level data or the container-level data—not both. ⚠️

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	ShipFromLocation-Id	ShipToLocation-Id	Container-Id	Container-Type	Certification1-Type	Certification1-Standard	Certification1-Agency	Certification1-Value
EVT123	ship	urn:epcglobal:cbv:bizstep:shipping	urn:epcglobal:cbv:disp:in_progress	2024-03-30T16:00:00+00:00	-05:00	PO001	INV001	Loading Dock	LOT001	100	PROD123	SUPPLIER001	WAREHOUSE001	CONT001	SSCC	urn:gdst:certType:fishingAuth	Los Angeles Fishing Certificate	Los Angeles Fishing Authorization	CAV

These fields are free-text fields, meaning you can enter any relevant certification details that apply to your product lots 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 ship 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:

🚨 Important Notice:
In the example, we have included both product-level data (ProductInstance-LotSerial, ProductInstance-Quantity) and container information (Container-Id, Container-Type).

However, when submitting the event, only populate either the product-level data or the container-level data—not both. ⚠️

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	ShipFromLocation-Id	ShipToLocation-Id	Container-Id	Container-Type	cbv-productOwner	cbv-informationProvider	productMasterData-gdst-speciesName	productMasterData-gdst-speciesCode	productMasterData-gdst-productForm	product-name
EVT123	ship	urn:epcglobal:cbv:bizstep:shipping	urn:epcglobal:cbv:disp:in_progress	2024-03-30T16:00:00+00:00	-05:00	PO001	INV001	Loading Dock	LOT001	100	PROD123	SUPPLIER001	WAREHOUSE001	CONT001	SSCC	OceanCorp	TraceData Ltd	Thunnus albacares	YFT	Frozen Loins	Premium-grade frozen tuna loins

These fields should be added per row in addition to the mandatory ship 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	ShipFromLocation-Id	ShipToLocation-Id	tlcSource-name	tlcSource-city	tlcSource-state	tlcSource-country	tlcSource-addressLine1	tlcSource-addressLine2	tlcSource-postalCode
EVT123	ship	urn:epcglobal:cbv:bizstep:shipping	urn:epcglobal:cbv:disp:in_progress	2024-03-30T16:00:00+00:00	-05:00	PO001	INV001	Loading Dock	LOT001	100	PROD123	SUPPLIER001	WAREHOUSE001	Ocean Logistics	Los Angeles	CA	USA	123 Seafood Way	Suite 200	90001

Download CSV Example

These fields should be added per row in addition to the mandatory ship event fields as well as any additional fields you have added when submitting FSMA 204 data.

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 or commission.

Example of Product-Level and Instance-Level Custom Data

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	ShipFromLocation-Id	ShipToLocation-Id	custom-dogsname	ProductMasterData-CustomDashDogSpecies
EVT123	ship	urn:epcglobal:cbv:bizstep:shipping	urn:epcglobal:cbv:disp:in_progress	2024-03-30T16:00:00+00:00	-05:00	PO001	INV001	Loading Dock	LOT001	100	PROD123	SUPPLIER001	WAREHOUSE001	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.

Download CSV Example

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

Download Template

You can download the CSV template, with all fields, using the link below:

Download CSV Template