Bulk Event Upload Detailed Guide

1. Introduction

CSV Bulk Event Uploads allow Wholechain users to log multiple supply chain events at once using a familiar spreadsheet format. This feature is designed for organizations that manage high‑volume operations or need to streamline traceability logging without manual entry.

Through the CSV file, you can:

• Log multiple events and shipments at once
• Capture lot‑specific traceability
• Use familiar tools (Excel + email or Wholechain App)
• Meet FSMA 204 and GDST requirements
• Reduce manual data entry 

2.  Understanding the CSV Structure

Flat File Format

Each row in the CSV represents one product–lot–quantity combination involved in an event. Because the file is a flat structure, all event‑level information must be repeated on every row belonging to the same event.

Customizable Fields

Depending on your workflow, the CSV may include:

• Framework/Requirement KDEs

• Certifications

• Custom KDEs

Column order is flexible. Wholechain maps fields by column header, not position.

3. How Wholechain Interprets Each Line of Your CSV

Wholechain reads your CSV file line by line and treats each row as a self‑contained instruction about what happened to a specific lot. By processing these rows in order, the system reconstructs the full traceability story of your products. Understanding how Wholechain interprets each line will help you prepare accurate files and avoid common validation errors.

3.1 One Row Represents One Product Lot in One Event

Each line in the CSV describes a single lot participating in a single event. If an event involves multiple lots, the file must include one row per lot. All rows belonging to the same event must share the same Event ID and identical event‑level information.

This structure allows Wholechain to understand exactly which lots were involved and how they moved or changed.

3.2 Rows Are Grouped Into Events Using the Event ID

Wholechain groups rows into a single event when they share the same Event ID. The system expects all event‑level fields - such as event type, event time, and event location - to match across those rows. 

3.3 Event‑Level Fields Tell Wholechain What Happened

Before interpreting the lot itself, Wholechain reads the event‑level fields on the row to understand the context of the action:

• Id
• Event Type (e.g., ship, receive, transform)
• EventTime and EventTimeZone
• Location-Id or ShipFromLocation-Id / ShipToLocation-Id

This information tells Wholechain what occurred, when it occurred, and where it occurred.

3.4 Lot‑Level Information Identifies the Product and Quantity

After identifying the event, Wholechain reads the lot‑specific fields, identified by ProductInstance+ :

• ProductId
• LotSerial (Lot or Serial Number)
• Quantity 

These fields tell Wholechain which product and which quantity were involved in the event. Because each row represents one lot, these values may differ across rows within the same event.

3.5 Master Data Provides the Full Product and Location Details

The CSV contains only IDs. Wholechain uses these IDs to look up the full product and location records in your master data. If a Product Id or Location Id in the CSV does not exist in master data, the system cannot interpret the row.

This is why completing master data before uploading a CSV is essential.

3.6 Wholechain Validates Logical Continuity

Wholechain checks whether each row makes sense based on prior events:

• A lot must be at a location before transformation
• Quantities must be consistent

3.7 Shipping Rows Describe Movement Between Locations

For shipping and receiving events, Wholechain reads the Ship From and Ship To Location IDs to understand how the lot moved. This updates the lot’s current location in the system.

3.8 Transformation Rows Describe Inputs and Outputs

For transformation events, Wholechain uses the Event ID to group all input and output rows. The field ProductInstance-Type is used to identify whether that specific line is to be read as an input or output in the transform event. 

This allows the system to understand how lots were combined, split, or converted into new lots.

3.9 Transformation Rows Describe Inputs and Outputs

Downstream events depend on upstream events being logged first. The system validates each event based on what has already occurred.

3.10 Transformation Rows Describe Inputs and Outputs

By reading line by line, Wholechain reconstructs the entire supply chain:

• Where each lot originated
• How it moved
• How it was transformed
• Which documents apply
• Records additional KDEs captured at each event

4. Before you begin

4.1 Master data setup

• Complete your Products and Locations master templates so you can use consistent alphanumeric IDs.
• If logging on behalf of suppliers, include their products and locations as well.

4.2 Map your events

Downstream events depend on upstream events being logged first. The system validates each event based on what has already occurred.

Common sequences:

• Commission → Ship → Receive → Transform → Aggregate/Disaggregate
• GDST: Landing, Transshipment, Fishing, Farm Harvest, Farm Stocking, Hatching

Planning the sequence ensures your CSV follows real‑world order and avoids validation errors.

4.3 Identify regulatory and operational requirements

Consider what KDEs and processes apply to your supply chain:

• FSMA 204, GDST, or other requirements
• Whether your (or your supplier’s) WMS/ERP changes lot codes at receipt
• Whether you are tracing wild‑caught or aquacultured seafood

5. Getting Started With the CSV Template

Using the CSV template provided by Wholechain, begin by entering the first event in the supply chain on the first row of your file. Each event is represented across one or more rows, depending on how many lots are involved.

Creating event rows

• Each lot involved in an event must appear on its own row

• If needed, duplicate the event row so that each lot has a separate line, and update the lot‑specific fields as needed

• All rows belonging to the same event share the same Event ID. For example, if three lots were shipped in a single shipment, each of the three rows would use Event ID “1”

Example: If three lots were shipped in one shipment, all three rows use Event ID “1”.

Fill in required fields

Every row must include the core event fields - ID, Type, Event Time, and Event Timezone - as well as the event‑specific fields such as product, lot/serial, quantity, and locations. For more information on specific fields per event, refer to sections 6 and 7.

Reference products and locations

The CSV does not contain full product or location details. Instead, it references Product IDs and Location IDs that must already exist in your master data. The CSV uses the Product ID to identify which item is being shipped, received, or transformed. The CSV uses Location IDs to indicate where each event occurred.

Wholechain looks up these IDs in your master data to retrieve the product attributes and physical location details needed to validate and connect events.

6. Event-by-Event Instructions

6.1 Commission

• An event in which a new product instance is created/documented for the first time. 
• These events typically occur in the far upstream steps of a supply chain
• Commissions will be logged separately when they are uploaded into Wholechain (just ensure that the commission event precedes the subsequent event) 
• Supply chain data sets will start with a commission OR a receive event. Not all supply chain data sets will include a commission event. 
• Required Fields: Lot/Serial, Quantity*, ProductID, LocationID

*You must commission the total amount of raw material (vs. a partial amount) in the commission event for that specific Lot/Serial. 

6.3 Receive

• An event in which shipped product is received by the ship-to facility. Receiving events can occur internally (between facilities of a single organization) or externally (from one organization to another).
• If multiple lots are received in the event, list each lot on a separate row. All of the rows for the receive event would have the same ID number. 
• Required fields: ShipFromLocationID, ShipToLocationID, LotSerial, Quantity, ProductID, ContainerID (if applicable)
• If you receive a container, you must include a row for each lot received. In each row (for each lot included):
• Container ID (and for SSCC, container type as applicable)
• A subsequent disaggregate event to break the container into the lots within the container

6.3.1 Receive Scenarios

• There are 2 main scenarios in which your company will log a receive event:
• 1) If your supplier has sent you complete shipping KDEs (to log on their behalf); OR
• 2) If you are NOT receiving traceability data from your supplier and the only data available is what your own system generated. This is called a direct receive or orphan receive.
• For scenario 1 (receive based on supplier shipping KDEs): 
• Log your supplier’s shipping KDEs in a ship event PRIOR to logging the receive event at your company’s facility. 
• For scenario 2 (direct receive / orphan receive)*:
• Log the first event in the CSV as a receive event with the limited KDEs you have available at the time (i.e. product ID, quantity, lot/serial, etc.). 
• If you reassign a lot number during your receive event: 
• Use your own lot code in lot/serial (not the suppliers)
• If you are aware of the supplier’s lot code, enter the supplier lot/serial in the TLC field

*For the ship event, you need to include the Purchase Order number you issued to your customer. On the receive event, you need to include the same Purchase Order number. This will be a pre-requisite for future automation of orphans resolution

6.4 Disaggregate

• An event in which previously aggregated items are separated (e.g. breaking down a pallet into distinct cases).
• Disaggregate event is needed if you received a container
• Disaggregate event goes on 1 row (because on the receive, you have 1 row per lot received)
• Required Fields: Location ID, Container ID

6.5 Transform

• An event that involves irreversible changes to a products physical form (e.g. manufacturing, processing) or packaging (e.g. commingling, re-packing, re-labeling). See FDA FSMA 204 definition here. 
• Always have at least 2 rows (input and output) and 1 ID for all of the lots involved in the event.
• Required Fields: INPUT AND OUTPUT LotSerial, Quantity, ProductID. ProductInstance-Type (i.e. input or output)
• Example:

6.6 Aggregate

• An event in which one or more distinct products are physically grouped together. Aggregation is always reversible and usually performed for shipping/storage purposes (e.g. combining several distinct cases onto one pallet).
• Use a single row for each of the input lots
• For the subsequent ship event, only include the container ID (along with the other required shipping data)
• Required Fields: LotSerial, Quantity, ProductID, LocationID, ContainerID, ContainerType

6.7 Ship

• An event in which product is shipped from one physical location to another. Shipping events can occur internally (between facilities of a single organization) or externally (from one organization to another).
• If multiple lots are shipped in the event, list each lot on a separate row. All of the rows for the ship event would have the same ID number. 
• If you ship a container, you must include Container ID. If multiple containers are shipped in the event, list each on a separate row. ll of the rows for the ship event would have the same ID number. 
• Required fields: ShipFromLocationID, ShipToLocationID, Lot/Serial, quantity, productID.
• For containers, ContainerID is used in place of lot/serial
• For the ship event, it is recommended to include the Purchase Order number you issued to your customer. On the receive event, you need to include the same Purchase Order number. This will be a pre-requisite for future automation of orphans resolution

7. Summary table of minimum required KDEs by Event 

8. CSV Field Descriptions

General

Certifications

9. Best Practices

• Keep backups of all original spreadsheets and submitted files.
• Always start from a fresh CSV when logging new data.
  • Once uploaded, the information is permanently registered in your account.
  • Re‑uploading the same file (or a file containing previously uploaded rows) will create duplicate events.
• Remove columns that do not apply to your supply chain.
• Follow the CSV Field Descriptions to ensure all required KDEs are included.

10. Uploading your CSV

1. Save your spreadsheet as a CSV file.
2. Log into Wholechain.
3. Go to Products → Actions → Bulk Event Upload.
4. Select your CSV file and upload.
5. Review any error messages and correct your file if needed..

For additional file submission methods, please reach out to your Wholechain contact. 

11. Troubleshooting

Wholechain will display specific error messages if something needs correction. Examples include:

• If any errors occur, a message will pop-up with the exact errors. 
• 500 Errors: take a screenshot and send to Wholechain, along with CSV. 
• Other Common Errors:
• "The payload provided contains no data." (when the CSV is empty or has no rows)
• "Id is required on line: {rowCount}"
• "Type is required on line: {rowCount}"
• "EventTime and EventTimeZone are required on line: {rowCount}"
• "Either ProductId or ProductUrn are required on line: {rowCount}"
• "Invalid UnitOfMeasure on line: {rowCount}"
• "Product details are required on line: {rowCount}"
• "A valid ProductInstance-Type (Input/Output) is required for the event type on line: {rowCount}"
• "Either LocationId or LocationUrn are required on line: {rowCount}"
• "Invalid quantity value '{quantityText}' on line: {rowCount}"
• Location not found
• Product not found
• LotSerial Already exists
• Product not found at the specific location

In case of 500 Errors, take a screenshot and send to Wholechain, along with CSV. 

12. Helpful Resources

• GDST Event Based Traceability Overview
• GDST Core Normative Standards
• GDST-1.2-Basic-Universal-List-of-KDEs
• Wholechain Help Doc: What is Event-based Traceability?
• FSMA Final Rule on Requirements for Additional Traceability Records for Certain Foods
• GS1 Core Business Vocabulary - attributes for fish traceability