Skip to content

Wholechain Data Model Overview

Introduction

Wholechain operates on two fundamental categories of data:

  1. Master Data (static, reference data)
  2. Event-Based Data (dynamic, transactional data)

Understanding the relationship between these two data types is critical for successfully connecting to and operating within the Wholechain traceability platform.

1. Master Data

Master data represents the foundational, relatively static entities that events reference. These entities must be created and maintained before event-based data can be submitted.

1.1 Product Master Data

Products represent the items being tracked within the system.

  • Each product must have a unique internal product ID.
  • This ID is the primary reference used in all event-based data.
  • Products are immutable reference points for traceability.

Key Principle:

Events do not define products—they reference them.

1.2 Trade Partner Master Data

Trade partners represent external or internal business entities involved in the supply chain.

A trade partner can be categorized as:

  • Supplier
  • Buyer (Customer)
  • Other

Locations Within Trade Partners

Each trade partner can have one or more locations.

Example: A retail chain (e.g., "Wholechain Retail Supermarket") is a single trade partner, but it may have multiple store locations.

  • Trade Partner: Wholechain Retail Supermarket
  • Locations:
  • Store 001
  • Store 002
  • Distribution Center

1.3 Self Trade Partner (Your Organization)

Each Wholechain account includes exactly one self trade partner, representing your own organization.

  • This is the account holder (e.g., "Wholechain Fisheries").
  • It can also have multiple locations.

1.4 Location Master Data

Locations are critical entities used across all events.

  • Each location must have a globally unique location ID.
  • Uniqueness is required across all locations, not just within a trade partner.

Locations exist for:

  • Trade partners (external)
  • Self trade partner (internal)

1.5 Summary of Master Data Requirements

Entity Key Identifier Notes
Product Product ID Must be unique
Trade Partner Trade Partner ID Can be supplier, buyer, or other
Location Location ID Must be globally unique
Self Trade Partner Account-level entity Only one per account

2. Event-Based Data

Event-based data represents actions performed on inventory (lots/serials) over time.

Unlike master data, event data is dynamic and captures the state and movement of products through the supply chain.

2.1 What Is an Event?

An event is a transaction that:

  • Creates
  • Modifies
  • Moves
  • Transforms

inventory in the form of lots/serials.

Examples of events include:

  • Creating a lot (commissioning)
  • Transforming or processing a lot
  • Shipping a lot
  • Receiving a lot

See all event types explained here

2.2 Lots/Serials

  • A lot is dynamic (its quantity, and associations may change).
  • A lot is always associated with:
  • A product (master data)
  • A location (master data)

Key Principle:

A lot cannot exist without referencing both a product and a location.

2.3 Relationship Between Events and Master Data

Events always reference master data.

For every event, you must specify:

  • Product ID (what product the lot belongs to)
  • Location ID(s) (where the event occurs)

Depending on the event type, the number of locations varies.

2.4 Event Types and Location Usage

Single-Location Events

These events occur at one location, shuch as:

  • Commission (create a lot)
  • Transform (process a lot)

Required references:

  • Product ID
  • Location ID

Dual-Location Events

These events involve movement between locations:

  • Ship
  • Receive

Required references:

  • Product ID
  • Ship From Location ID
  • Ship To Location ID

2.5 Dynamic Nature of Events

Event data can change over time and includes fields such as:

  • Timestamp
  • Lot number
  • Quantity
  • Inputs and outputs (for transformations)

Unlike master data, event data is not static and reflects real-world operations.

3. Key Concepts

All event data must reference valid master data:

  • Invalid product IDs or location IDs will result in integration failure.

3.2 Traceability Model

Wholechain uses an event-based traceability model, meaning:

  • Every change to inventory is recorded as an event
  • Lots/serials are tracked through their lifecycle via these events

4. Integration Requirements

To successfully integrate with Wholechain, your system must:

1. Create and maintain master data first

  • Products
  • Trade partners
  • Locations

2. Ensure all identifiers are unique

  • Product IDs
  • Location IDs (globally unique)

3. Submit event data that references master data

  • Every event must include valid product and location references

4. Model inventory as lots

  • Lots/serials must always be tied to a product and location

5. Use appropriate event types

  • Single-location vs dual-location depending on the operation

5. Summary

Wholechain’s data model is built on a clear separation between:

  • Master Data (products, trade partners, locations)
  • Event-Based Data (transactions that manipulate lots/serials)

Events are the mechanism by which inventory is created, transformed, and moved, while master data provides the stable reference framework that ensures consistency and traceability across the supply chain.

Understanding and correctly implementing this structure is essential for any successful integration with the Wholechain platform.