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 Commission Event, which allows you to log when products or lots are created or initialized in your supply chain.

Commission Event

The Commission Event records the creation or initialization of a lot/serial within the supply chain.

Commissioning a Single Lot

If you are commissioning a single product lot, you only need to provide the lot information.
Each row represents one commissioned lot.

Example:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	Location-Id	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId
EVT123	commission	urn:epcglobal:cbv:bizstep:commissioning	urn:epcglobal:cbv:disp:active	2025-01-01T12:00:00Z	-05:00	PO001	INV001	Factory Line	LOC001	LOT001	100	PROD123

Download CSV Template Example

Required Fields for the Commission Event

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

Mandatory Fields for All Commission Events

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

Id – A unique identifier for this receive event. Each new row must have a unique ID.
Type – The type of event (e.g., "Receive").
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 receipt.
InvoiceNumber – The invoice number related to the purchase order.
ReadPoint – The place within the location where the event took place.
Location-Id - The internal ID of Location you are creating the lot at.
ProductInstance-LotSerial – The unique identifier for the lot received.
ProductInstance-Quantity – The quantity of the product created.
ProductInstance-ProductId – The identifier for the product.

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 if needed. Wholechain provides a template for adding these certifications.

You can attach any number of certifications to a specific lot. 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

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	Location-Id	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Certification1-Type	Certification1-Standard	Certification1-Agency	Certification1-Value	Certification1-Identification
EVT123	commission	urn:epcglobal:cbv:bizstep:commissioning	urn:epcglobal:cbv:disp:active	2025-01-01T12:00:00Z	-05:00	PO001	INV001	Factory Line	LOC001	LOT001	100	PROD123	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 product lots or containers.

Download CSV Template

Adding Global Dialogue for Seafood Traceability (GDST) Data

In the Wholechain system, a Commission Event marks the start of a supply chain. However, in Global Dialogue for Seafood Traceability (GDST), the initial events vary depending on the type of product:

For wild harvest (fishing/catch events), GDST recognizes a "Catch Event" as the first supply chain event.
For farmed products, GDST recognizes a "Farm Harvest Event" as the first supply chain event.

Since you are logging a Commission Event, you need to align it with the relevant GDST event. This means that additional fields specific to Fishing/Catch or Farm Harvest need to be added.

Most of the required GDST fields are already accounted for within the mandatory commission event fields. However, depending on whether your event is a Fishing/Catch Event or a Farm Harvest Event, you need to include the following additional fields.

1. Fishing and Catch Event (Wild Harvest) Additional Fields

If you are recording a fishing/catch event, include these additional fields:

Vessel Name → cbv-vesselName
Vessel Registration → shipFromLocation-vesselRegistration
Unique Vessel ID → cbv-vesselID
IMO Number → gdst-imoNumber
Public Vessel Registry Hyperlink → gdst-vesselPublicRegistry
Vessel Flag State → cbv-vesselFlagState
Availability of Catch Coordinates → gdst-gpsAvailability
Satellite Vessel Tracking Authority → gdst-satelliteTrackingAuthority
Catch Area → cbv-catchArea
Economic Zone → cbv-economicZone
RFMO Area → gdst-rfmoArea
Sub-National Permit Area → gdst-subnationalPermitArea
Fishery Improvement Project → gdst-fisheryImprovementProject
Vessel Trip Date Start → harvest-startDate
Date of Capture Start → harvest-endDate

Gear Type → cbv-gearType
Production Method → product-sharingPolicy
Fishing Authorization → Follow Certification Format Above
Harvest Certification → Follow Certification Format Above

Human Welfare Policy Standards → Follow Certification Format Above
Species (Scientific Name) → productMasterData-gdst-speciesName
Species (3-letter Code) → productMasterData-gdst-speciesCode
Product Form → productMasterData-gdst-productForm
Product Short Description → product-name
Product Owner → cbv-productOwner
Information Provider → cbv-informationProvider

Example with Fishing and Catch GDST Data:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-Id	cbv-productOwner	cbv-informationProvider	cbv-vesselName	shipFromLocation-vesselRegistration	cbv-vesselID	gdst-imoNumber	gdst-vesselPublicRegistry	cbv-vesselFlagState	gdst-gpsAvailability	gdst-satelliteTrackingAuthority	cbv-catchArea	cbv-economicZone	gdst-rfmoArea	gdst-subnationalPermitArea	gdst-fisheryImprovementProject	harvest-startDate	harvest-endDate	cbv-gearType	product-sharingPolicy	productMasterData-gdst-speciesName	productMasterData-gdst-speciesCode	productMasterData-gdst-productForm	product-name
EVT123	commission	urn:epcglobal:cbv:bizstep:commissioning	urn:epcglobal:cbv:disp:active	2025-01-01T12:00:00Z	-05:00	Port A	LOT001	100	PROD123	LOC123	OceanCorp	TraceData Ltd	FV Bluefin	ABC12345	VESSEL123	987654321	Public Registry	USA	Yes	NOAA	Area 31	EEZ123	RFMO-001	Permit-Area-XYZ	FIP-123	2024-12-20	2024-12-25	Longline	Wild Catch	Thunnus albacares	YFT	Frozen Whole	Whole Tuna

Download CSV Example

Farm Harvest Event (Aquaculture) Additional Fields

If you are recording a farm harvest event, you need to include the following additional fields to align with GDST requirements.

Required Fields for Farm Harvest Events

Product Owner → cbv-productOwner
Information Provider → cbv-informationProvider
Species (Scientific Name) → productMasterData-gdst-speciesName
Species (3-letter Code) → productMasterData-gdst-speciesCode
Product Form → product-unitOfMeasure
Product Short Description → product-name
Farming Method → product-sharingPolicy
Harvest Date per Tank → eventTime
Harvest Certification → Follow Certification Format Above
Chain of Custody Certification → Follow Certification Format Above
Human Welfare Policy Standards → Follow Certification Format Above
Date of Harvest Start → eventTime

Example with Farm Harvest GDST Data

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-Id	cbv-productOwner	cbv-informationProvider	productMasterData-gdst-speciesName	productMasterData-gdst-speciesCode	product-name	product-unitOfMeasure	product-sharingPolicy	eventTime (Harvest Start)	certification1-type	certification1-standard	certification1-agency
EVT456	commission	urn:epcglobal:cbv:bizstep:commissioning	urn:epcglobal:cbv:disp:active	2025-02-15T10:30:00Z	-05:00	Farm Tank 1	LOT002	500	PROD789	LOC123	AquaCorp	AquaTrace Ltd	Salmo salar	ATL	Fresh Salmon	Whole Fish	Closed Recirculation	2025-02-10T08:00:00Z	ASC CoC	ASC Chain of Custody	ASC

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 data

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

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

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

Example with Custom Data:

Id	Type	BizStep	Disposition	EventTime	EventTimeZone	PurchaseOrder	InvoiceNumber	ReadPoint	ProductInstance-LotSerial	ProductInstance-Quantity	ProductInstance-ProductId	Location-Id	custom-dogsname	ProductMasterData-CustomDashDogSpecies
EVT123	commission	urn:epcglobal:cbv:bizstep:commissioning	urn:epcglobal:cbv:disp:active	2024-03-30T16:00:00+00:00	-05:00	PO001	INV001	Factory Line	LOT001	100	PROD123	LOC001	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 ensures that all commission events meet regulatory and business-specific data requirements.

Download CSV Example

Download Template

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

Download CSV Template