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 Transform Event, which allows you to log when products or lots are created or initialized in your supply chain.
Transforming a Product
When transforming a product, you must record both the input (raw material) and the output (finished product). These transformations should be logged using the same Event ID to maintain traceability.
Key Points:
- The input product represents the materials or ingredients being used.
- The output product represents the finished or intermediate product after processing.
- Both the input and output must share the same Event ID to indicate that they are part of the same transformation process.
Example:
| Id | Type | BizStep | Disposition | EventTime | EventTimeZone | PurchaseOrder | InvoiceNumber | ReadPoint | Location-Id | ProductInstance-LotSerial | ProductInstance-Quantity | ProductInstance-Type | ProductInstance-ProductId |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00+00:00 | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 123 | 180.75 | Input | raw_goods_000 |
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00+00:00 | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 456 | 180 | Output | finished_goods_000 |
Explanation:
- Event ID 0002 shows a transformation process.
- The first row records the input product (
raw_goods_000) with a quantity of180.75. - The second row records the output product (
finished_goods_000) with a quantity of180.
Required Fields for the Transform Event
For a successful upload, your CSV file must include the following mandatory fields:
Mandatory Fields for All Transform Events
When recording a product transformation, these fields are required:
- Id – A unique identifier for this transform event. Each new row must have the same ID for both input and output products.
- Type – The type of event (e.g., "Transform").
- 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 transformation occurred. (See format in example)
- EventTimeZone – The time zone of the event timestamp. (See format in example)
- PurchaseOrder – The purchase order number associated with the transformation.
- 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 the location where the transformation occurred.
- ProductInstance-LotSerial – The unique identifier for the lot being transformed.
- ProductInstance-Quantity – The quantity of the product before or after transformation.
- ProductInstance-Type – Specifies whether the product instance is an "Input" or "Output".
- ProductInstance-ProductId – The identifier for the input or output product.
Each transformation event must contain at least one input product and one output product, both linked by the same Id.
Adding Certifications
You can add certifications to specific lots as needed, with no limit on the number of certifications per lot.
To attach certifications, include the certification details in separate rows. Simply add the certification template headers alongside the mandatory fields for each entry. This allows for multiple certifications per lot, ensuring all relevant information is captured efficiently.
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 2 Type →
certification2-type - Certification 3 Type →
certification3-type
Example with Certifications
| Id | Type | BizStep | Disposition | EventTime | EventTimeZone | PurchaseOrder | InvoiceNumber | ReadPoint | Location-Id | ProductInstance-LotSerial | ProductInstance-Quantity | ProductInstance-Type | ProductInstance-ProductId | Certification1-Type | Certification1-Standard | Certification1-Agency | Certification1-Value | Certification1-Identification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00Z | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 123 | 180.75 | Input | raw_goods_000 | urn:gdst:certType:harvestCoC | MSC Chain of Custody | MSC | Yes | CERT123 |
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00Z | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 456 | 180 | Output | finished_goods_000 | urn:gdst:certType:processing | BAP | GSA | Yes | CERT456 |
These fields are free-text fields, meaning you can enter any relevant certification details that apply to your product lots
Adding Global Dialogue for Seafood Traceability (GDST) Data
In the Wholechain system, a Transform Event marks the start of a supply chain. However, in Global Dialogue for Seafood Traceability (GDST), the events are labelled differently. The GDST labels a transform event as a processing event.
Since you are logging a Transform Event, you need to align it with the relevant GDST event. This means that additional fields specific to Processing events need to be added.
Most of the required GDST fields are already accounted for within the mandatory transform event fields. However, you need to include the following additional fields.
Required GDST Fields
For processing event, in addition to what is already accounted for, 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.
- Product Form →
productMasterData-gdst-productForm - Product Short Description →
product-name
Examaple with GDST data
| Id | Type | BizStep | Disposition | EventTime | EventTimeZone | PurchaseOrder | InvoiceNumber | ReadPoint | Location-Id | ProductInstance-LotSerial | ProductInstance-Quantity | ProductInstance-Type | ProductInstance-ProductId | 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00+00:00 | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 123 | 180.75 | Input | raw_goods_000 | cbv-productOwner_001 | cbv-informationProvider_001 | productMasterData-gdst-speciesName_001 | productMasterData-gdst-speciesCode_001 | productMasterData-gdst-productForm_001 | productMasterData-gdst-productShortDescription_001 | CERT_TYPE_001 | CERT_STANDARD_001 | CERT_AGENCY_001 | YES | CERT_ID_001 |
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00+00:00 | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 456 | 180 | Output | finished_goods_000 | cbv-productOwner_002 | cbv-informationProvider_002 | productMasterData-gdst-speciesName_002 | productMasterData-gdst-speciesCode_002 | productMasterData-gdst-productForm_002 | productMasterData-gdst-productShortDescription_002 | CERT_TYPE_002 | CERT_STANDARD_002 | CERT_AGENCY_002 | YES | CERT_ID_002 |
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-Type | ProductInstance-ProductId | tlcSource-name | tlcSource-city | tlcSource-state | tlcSource-country | tlcSource-addressLine1 | tlcSource-addressLine2 | tlcSource-postalCode |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00+00:00 | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 123 | 180.75 | Input | raw_goods_000 | Source A | New York | NY | USA | 123 Main St | Suite 200 | 10001 |
| 0002 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-25T15:00:00+00:00 | -05:00 | 1990091 | 12314154 | RP790 | processing_000 | 456 | 180 | Output | finished_goods_000 | Source A | New York | NY | USA | 123 Main St | Suite 200 | 10001 |
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.
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 event.
Example with Custom Data:
| Id | Type | BizStep | Disposition | EventTime | EventTimeZone | PurchaseOrder | InvoiceNumber | ReadPoint | Location-Id | ProductInstance-LotSerial | ProductInstance-Quantity | ProductInstance-Type | ProductInstance-ProductId | custom-dogsname | ProductMasterData-CustomDashDogSpecies |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| EVT123 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-30T16:00:00+00:00 | -05:00 | PO001 | INV001 | Factory Line | processing_001 | LOT001 | 100 | Input | raw_material_001 | Max | Canis familiaris |
| EVT123 | Transform | urn:epcglobal:cbv:bizstep:assembling | urn:epcglobal:cbv:disp:in_progress | 2024-03-30T16:00:00+00:00 | -05:00 | PO001 | INV001 | Factory Line | processing_001 | LOT002 | 100 | Output | finished_product_001 | Max | Canis familiaris |
In this example:
ProductMasterData-CustomDashDogSpeciesis defined at the product level and remains constant across all events.custom-dogsnameis defined at the instance level and can be customized for each event.
Download Full Template
You can download the full CSV template, with all fields included, using the link below: