# Internal Traceability One of the big challenges for organisations implementing EUDR is internal traceability, that is linking *inbound* goods with *outbound* goods. This is essential for a few key reasons: 1. Where your customers require you to share DDS Reference Numbers you need to be able to identify the DDS Reference(s) associated on inbound delivery(ies). 2. Where you have to generate a DDS for an outbound delivery you need to be able to identify all the inbound deliveries so you can ultimately identify all the point's of origin related to those deliveries so you can provide the information requires for the DDS statement. 3. When you need to be able to share end-to-end traceability information to your customers. ## Reality Whilst this seems great on paper, the reality of how to achieve is very dependent on your internal systems and processes. Often the data needed for this level of traceability is not immediately available and so the challenge of fulfilling end-to-end traceability without causing disruption to your existing processes is challenging. ## Approach Interu provides mechanisms to capture the data needed for end-end-end traceability. This can be broken down as follows: ```mermaid flowchart LR in(Inbound Deliveries) pro("Process(es)") out(Outbound Deliveries) in-- items --> pro pro-- items -->out ``` Items that arrive in deliveries need to be linked to processes that happen within your organisation and items that come out of those proceess need to be linked with outbound deliveries. ## Examples Note that for all these examples the assumption is that this flow is for the same product, there is no processing or conversion. 1-to-1 mapping This is a simplistic model which doesn't involve any processing but purely picking of goods that come in to send out to customers. It assumes that the specific goods can be identified as part of the picking process. ```mermaid flowchart TB inA("`**Delivery 1** (DDS Ref:ABC) *- Item001* Qty: 100`") inB("`**Delivery 2** (DDS Ref:DEF) *- Item002* Qty: 200`") inC("`**Delivery 3** (DDS Ref:GHI) *- Item003* Qty: 150`") procA("`**Process001** picking process`") procB("`**Process002** picking process`") outA("`**Delivery 4** (DDS Refs: ABC, DEF) *- Item004* Qty: 150`") outB("`**Delivery 5** (DDS Refs: DEF, GHI) *- Item005* Qty: 200`") inA -- 100 --> procA inB -- 50 --> procA inB -- 150 --> procB inC -- 50 --> procB procA -- 150 --> outA procB -- 200 --> outB ``` As you can see, for each outbound delivery, because you can identify the specific items that went into the picking process then Interu is able to link everything required to support EUDR and other traceability requirements. Batching approach A potentially more likely scenario is one where you cannot definitely link the items that come in with the items that go out. This may be determined by what information is available at the time of picking, whether or not you can operate a *FIFO* (First In First Out) or a *LIFO* (Last In Last Out) approach to the flow of goods internally. ```mermaid flowchart TB inA("`**Delivery 1** (DDS Ref:ABC) *- Item001* Qty: 100`") inB("`**Delivery 2** (DDS Ref:DEF) *- Item002* Qty: 200`") inC("`**Delivery 3** (DDS Ref:GHI) *- Item003* Qty: 150`") procA("`**Batch** Item 'Bucket'`") outA("`**Delivery 4** (DDS Refs: ABC, DEF, GHI) *- Item004* Qty: 150`") outB("`**Delivery 5** (DDS Refs: ABC, DEF, GHI) *- Item005* Qty: 200`") inA -- 100 --> procA inB -- 200 --> procA inC -- 150 --> procA procA -- pick 150 --> outA procA -- pick 200 --> outB ``` In this approach, all the goods flow into a single 'bucket' from which the deliveries are picked. This means that outbound deliveries will be linked with all inbound deliveries where the items in those deliveries have been added to the bucket. In the context of EUDR this means all inbound DDS References will be associated with a given *outbound* delivery. Cut off point This bucket cannot continue indefinitely, you need to determine a bounding factor - typically this would be time. It makes sense for this to coincide with a *stock take* where the items that still remain within stock can be identified and moved to a new bucket. ## The Data Model ```mermaid classDiagram direction LR Item "1" .. "1" Product : references Item "1" .. "many" Material : references Item "1" .. "1" Location : references Process "1" .. "1" Location : references Delivery "1" *-- "many" DeliveryItem : contains DeliveryItem "1" .. "1" Item : references ProcessType "1" .. "1" Process :references Process "1" .. "many" InputItem : /inputs Process "1" .. "many" OutputItem : /outputs InputItem "1" .. "1" Item : references OutputItem "1" .. "1" Item : references class Item { } class Delivery { } class DeliveryItem { } class Process { } class InputItem { } class OutputItem { } class ProcessType { } namespace Static { class Product { } class Location { } class Material { } } ``` Item ```json { "$ref": "#/components/schemas/Transactional.ItemCreate", "components": { "schemas": { "Common.BaseCreate": { "type": "object" }, "Common.BaseWithIdCreate": { "type": "object", "properties": { "id": { "type": "string", "description": "System assigned or user defined id field." }, "sid": { "type": "string", "description": "An identifier you can supply to reference this record by your own id. It is not used by the system and does not need to be unique." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseCreate" } ] }, "iov42.Core.Models.DateTime.DateOrRange": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "EXACT", "RANGE" ], "description": "The type of captured date." }, "on": { "type": "string", "format": "date-time", "description": "If Type is EXACT then this precise date is used." }, "start": { "type": "string", "format": "date-time", "description": "If type is RANGE then this is the start date." }, "end": { "type": "string", "format": "date-time", "description": "If type is RANGE then this is the end date." } } }, "Transactional.AdditionalQuantity": { "type": "object", "required": [ "baseUnit", "conversionQuantity", "overrideQuantity" ], "properties": { "baseUnit": { "type": "string", "description": "The additional quantity base unit of measurement." }, "conversionQuantity": { "type": "number", "format": "decimal", "description": "The additional quantity calculated if the product has a conversion to that base unit." }, "overrideQuantity": { "type": "number", "format": "decimal", "description": "An override quantity provided irrespective of whether or not there is a conversion on the product." } } }, "Transactional.ItemCreate": { "type": "object", "required": [ "itemId", "product", "createdAtLocation", "currentLocation", "created", "initialQuantity", "additionalInitialQuantities" ], "properties": { "itemId": { "type": "string", "description": "User defined id for the item." }, "product": { "type": "string", "format": "uri", "description": "URI for the product that the item is.", "examples": [ "/organisations/{orgId}/products/{productId}" ] }, "createdAtLocation": { "type": "string", "format": "uri", "description": "URI for the location where the product was created.", "examples": [ "/organisations/{orgId}/locations/{locationId}" ] }, "materials": { "type": "array", "items": { "type": "string" }, "description": "List of material URIs that are used within the item.", "examples": [ [ "/organisations/{orgId}/materials/{materialId}" ] ] }, "currentLocation": { "type": "string", "format": "uri", "description": "URI for the location that the item is at or was last at (perhaps it no longer exists as it entered a manufacturing process).", "examples": [ "/organisations/{orgId}/locations/{locationId}" ] }, "created": { "allOf": [ { "$ref": "#/components/schemas/iov42.Core.Models.DateTime.DateOrRange" } ], "description": "The Date or Date Range that the item was created on." }, "initialQuantity": { "type": "number", "format": "decimal", "description": "This quantity contained within this item at the point when it was created." }, "additionalInitialQuantities": { "type": "array", "items": { "$ref": "#/components/schemas/Transactional.AdditionalQuantity" }, "description": "Additiononal quantities can be specified directly on the item." }, "remainingQuantity": { "type": "number", "format": "decimal", "description": "If an item enters a process then this quantity The remaining quantity, some of the item may have been used in a process." }, "productVariant": { "type": "string", "format": "uri", "description": "The uri of the product variant if applicable to this item.", "examples": [ "/organisations/{orgId}/products/{productId}/variants/{variantId}" ] }, "batchNumbers": { "type": "array", "items": { "type": "string" }, "description": "If the item is associated with a particular batch (or multiple batches) then you can use this field to record the batch numbers." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseWithIdCreate" } ], "description": "Represents an item within the supply chain. Items can be found in deliveries or processes, they represent goods as they flow through the supply chain." } } } } ``` Delivery ```json { "$ref": "#/components/schemas/Transactional.DeliveryCreate", "components": { "schemas": { "Common.BaseCreate": { "type": "object" }, "Common.BaseWithIdCreate": { "type": "object", "properties": { "id": { "type": "string", "description": "System assigned or user defined id field." }, "sid": { "type": "string", "description": "An identifier you can supply to reference this record by your own id. It is not used by the system and does not need to be unique." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseCreate" } ] }, "Transactional.DeliveryStatus": { "type": "string", "enum": [ "DELIVERED", "PENDING", "IN_PROGRESS" ] }, "Transactional.DeliveryItem": { "type": "object", "required": [ "item", "quantity" ], "properties": { "item": { "type": "string", "format": "uri", "description": "The URI of the item included in the delivery.", "examples": [ "/organisations/{orgId}/items/{itemId}", "/organisations/{orgId}/items/{itemId}" ] }, "quantity": { "type": "number", "format": "decimal", "description": "The quantity of the item included in the delivery." } }, "description": "Represents an item that is part of the delivery." }, "Transactional.DeliveryCreate": { "type": "object", "required": [ "deliveryId", "from", "to", "status" ], "properties": { "deliveryId": { "type": "string", "description": "User-assigned unique identifier for the delivery." }, "from": { "type": "string", "format": "uri", "description": "The URI of the location from which the delivery is being delivered from.", "examples": [ "/organisations/{orgId}/locations/{locationId}" ] }, "to": { "type": "string", "format": "uri", "description": "The URI of the location to which the delivery is being delivered to.", "examples": [ "/organisations/{orgId}/locations/{locationId}" ] }, "status": { "allOf": [ { "$ref": "#/components/schemas/Transactional.DeliveryStatus" } ], "description": "The current status of the delivery." }, "sent": { "type": "string", "format": "date-time", "description": "The date and time of when the delivery has been sent." }, "delivered": { "type": "string", "format": "date-time", "description": "The date and time of when the delivery has been delivered." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transactional.DeliveryItem" }, "description": "List of items included in the delivery." }, "agents": { "type": "array", "items": { "type": "string" }, "description": "List of agent organisation URIs that are associated with the delivery." }, "purchaseOrderNumbers": { "type": "array", "items": { "type": "string" }, "description": "Associated Purchase Orders" }, "supplyChainUri": { "type": "string", "format": "uri", "description": "The URI of the supply chain associated with this delivery." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseWithIdCreate" } ], "description": "Represents a delivery/shipment within a supply chain. This may be inbound or outbound for an organisation." } } } } ``` Process ```json { "$ref": "#/components/schemas/Transactional.ProcessCreate", "components": { "schemas": { "Common.BaseCreate": { "type": "object" }, "Common.BaseWithIdCreate": { "type": "object", "properties": { "id": { "type": "string", "description": "System assigned or user defined id field." }, "sid": { "type": "string", "description": "An identifier you can supply to reference this record by your own id. It is not used by the system and does not need to be unique." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseCreate" } ] }, "Transactional.ProcessState": { "type": "string", "enum": [ "INPUT_OUTPUT", "OUTPUT_ONLY", "CLOSED" ] }, "Transactional.ProcessCreate": { "type": "object", "required": [ "processId", "type", "location", "state", "firstInputDate", "lastOutputDate" ], "properties": { "processId": { "type": "string", "description": "The process id." }, "type": { "type": "string", "format": "uri", "description": "The URI of the type of process.", "examples": [ "/organisations/{orgId}/process-types/{processTypeId}" ] }, "location": { "type": "string", "format": "uri", "description": "The URI of the location that this process was carried out at.", "examples": [ "/organisations/{orgId}/locations/{locationId}" ] }, "state": { "allOf": [ { "$ref": "#/components/schemas/Transactional.ProcessState" } ], "description": "Contains the process state. It governs what you can or cannot do with the process." }, "firstInputDate": { "type": "string", "format": "date-time", "description": "The first date for input." }, "lastOutputDate": { "type": "string", "format": "date-time", "description": "The last date for output." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseWithIdCreate" } ], "description": "A process represents an activity that occurs within an organisation. This may be a conversion from one or more Item types into other Item types or a processes such as bundling." } } } } ``` Process Input ```json { "$ref": "#/components/schemas/Transactional.ProcessInputCreate", "components": { "schemas": { "Common.BaseCreate": { "type": "object" }, "Common.BaseWithoutIdCreate": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Common.BaseCreate" } ] }, "iov42.Core.Models.DateTime.DateOrRange": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "EXACT", "RANGE" ], "description": "The type of captured date." }, "on": { "type": "string", "format": "date-time", "description": "If Type is EXACT then this precise date is used." }, "start": { "type": "string", "format": "date-time", "description": "If type is RANGE then this is the start date." }, "end": { "type": "string", "format": "date-time", "description": "If type is RANGE then this is the end date." } } }, "Transactional.ProcessInputItem": { "type": "object", "required": [ "item", "selectedQuantity" ], "properties": { "item": { "type": "string", "format": "uri", "description": "The URI of the item that was put into the process.", "examples": [ "/organisations/{orgId}/items/{itemId}" ] }, "selectedQuantity": { "type": "number", "format": "decimal", "description": "The quantity of the item that was processed." } }, "description": "The item that was input to a process." }, "Transactional.ProcessInputCreate": { "type": "object", "required": [ "date", "items", "note" ], "properties": { "date": { "allOf": [ { "$ref": "#/components/schemas/iov42.Core.Models.DateTime.DateOrRange" } ], "description": "The date or date range that the items were added." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transactional.ProcessInputItem" }, "description": "The process input items URIs" }, "note": { "type": "string", "description": "A note to attach to the particular input." }, "sid": { "type": "string", "description": "An identifier you can supply to reference this record by your own id. It is not used by the system and does not need to be unique." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseWithoutIdCreate" } ], "description": "Captures a set of items that were input to a Process and the quantity that was used." } } } } ``` Process Output ```json { "$ref": "#/components/schemas/Transactional.ProcessOutputCreate", "components": { "schemas": { "Common.BaseCreate": { "type": "object" }, "Common.BaseWithoutIdCreate": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Common.BaseCreate" } ] }, "iov42.Core.Models.DateTime.DateOrRange": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "EXACT", "RANGE" ], "description": "The type of captured date." }, "on": { "type": "string", "format": "date-time", "description": "If Type is EXACT then this precise date is used." }, "start": { "type": "string", "format": "date-time", "description": "If type is RANGE then this is the start date." }, "end": { "type": "string", "format": "date-time", "description": "If type is RANGE then this is the end date." } } }, "Transactional.ProcessOutputItem": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "string", "format": "uri", "description": "The URI of the item that was output from the process.", "examples": [ "/organisations/{orgId}/items/{itemId}" ] } }, "description": "The item that was output from a process." }, "Transactional.ProcessOutputCreate": { "type": "object", "required": [ "date", "items", "note" ], "properties": { "date": { "allOf": [ { "$ref": "#/components/schemas/iov42.Core.Models.DateTime.DateOrRange" } ], "description": "The date or date range that the items were output." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transactional.ProcessOutputItem" }, "description": "The process output items" }, "note": { "type": "string", "description": "A note to attach to the particular output." }, "sid": { "type": "string", "description": "An identifier you can supply to reference this record by your own id. It is not used by the system and does not need to be unique." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseWithoutIdCreate" } ], "description": "Captures a set of items that were output from a Process." } } } } ``` ## Using the API ### Adding Materials Materials represent the raw materials that are incorporated into goods. This is of particular importance in regards to EUDR as it provides the means to specify the Common and Scientific names as required by the regulation. Upcoming change We currently capture Scientific Name and Common Name custom fields. This is about to be replaced with standard fields within the Material model. Material Schema ```json { "$ref": "#/components/schemas/Static.MaterialCreate", "components": { "schemas": { "Common.BaseCreate": { "type": "object" }, "Common.BaseWithIdCreate": { "type": "object", "properties": { "id": { "type": "string", "description": "System assigned or user defined id field." }, "sid": { "type": "string", "description": "An identifier you can supply to reference this record by your own id. It is not used by the system and does not need to be unique." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseCreate" } ] }, "Static.MaterialCreate": { "type": "object", "required": [ "name", "category" ], "properties": { "name": { "type": "string", "description": "The name of the material." }, "scientificName": { "type": "string", "description": "This is the Scientific Name for this material. It is an optional field but is required for sbmission to the Traces NT system." }, "commonName": { "type": "string", "description": "This is a Common Name for this material. It is an optional field but is required for sbmission to the Traces NT system." }, "category": { "type": "string", "description": "The category for the material." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseWithIdCreate" } ], "description": "The definition of a material." } } } } ``` ### Adding Products Products represent the type of goods that are flowing through the system. If you are submitting DDS Statements to the EU Traces NT system then the Product definition must have an HS Code attached. Upcoming change We currently capture HS Codes through a custom field. This is about to be replaced with a standard field within the Product model. Product Schema ```json { "$ref": "#/components/schemas/Static.ProductCreate", "components": { "schemas": { "Common.BaseCreate": { "type": "object" }, "Common.BaseWithIdCreate": { "type": "object", "properties": { "id": { "type": "string", "description": "System assigned or user defined id field." }, "sid": { "type": "string", "description": "An identifier you can supply to reference this record by your own id. It is not used by the system and does not need to be unique." } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseCreate" } ] }, "Static.AdditionalUnit": { "type": "object", "required": [ "baseUnit", "conversionFactor" ], "properties": { "baseUnit": { "type": "string", "format": "uri", "description": "The URI to the base unit of measurement to convert the base qty to. So if the product is specified in units and the conversion specifies kg then this conversion will provide the per unit mass.", "examples": [ "/common/base-units/{unitId}", "/common/base-units/{unitId}" ] }, "conversionFactor": { "type": "number", "format": "decimal", "description": "The conversion factor from product base unit to conversion base unit." } } }, "Static.ProductCreate": { "type": "object", "required": [ "name", "allowedMaterials", "baseUnit", "additionalUnits" ], "properties": { "name": { "type": "string", "description": "The name for the product." }, "hsCode": { "type": "string", "description": "This is the HS (Harmonised Standard) code for the product. This is optional unless this product will be part of submission to the Traces NT system." }, "description": { "type": "string", "description": "This is a simple description for the product. This is optional unless this product will be part of submission to the Traces NT system." }, "allowedMaterials": { "type": "array", "items": { "type": "string" }, "description": "The URI(s) of the material(s) that are allowed to be used for this product.", "examples": [ [ "/organisations/{orgId}/materials/{materialId}" ] ] }, "baseUnit": { "type": "string", "format": "uri", "description": "The URI to the base unit of measurement that this product is specified in.", "examples": [ "/common/base-units/{unitId}" ] }, "defaultUnit": { "type": "string", "format": "uri", "description": "The URI to the unit of measurement that you wish to use as the default unit of measurement.", "examples": [ "/common/base-units/{unitId}" ] }, "additionalUnits": { "type": "array", "items": { "$ref": "#/components/schemas/Static.AdditionalUnit" }, "description": "A list of additional units that specify the factor for converting from the base unit to other base units: e.g. unit to kg" } }, "allOf": [ { "$ref": "#/components/schemas/Common.BaseWithIdCreate" } ], "description": "This is a definition of a product. Typically this represents an SKU." } } } } ``` ### Adding Items Items represent goods flowing through the supply chain. Each item represents a quantity of a Product. It can also define the Materials that were used to make that Item. ### Adding Deliveries Deliveries represent the movement of items (or goods) between two locations. #### Adding items to deliveries. Items are referenced within the Delivery model by providing the URIs to each Item within the delivery.items collection: Delivery Item Schema ```json { "$ref": "#/components/schemas/Transactional.DeliveryItem", "components": { "schemas": { "Transactional.DeliveryItem": { "type": "object", "required": [ "item", "quantity" ], "properties": { "item": { "type": "string", "format": "uri", "description": "The URI of the item included in the delivery.", "examples": [ "/organisations/{orgId}/items/{itemId}", "/organisations/{orgId}/items/{itemId}" ] }, "quantity": { "type": "number", "format": "decimal", "description": "The quantity of the item included in the delivery." } }, "description": "Represents an item that is part of the delivery." } } } } ``` ### Adding Processes Processes are used to represent what goes on within an organisation, that may be manufacturing or it may simply be used to represent goods that are picked to send to a customer in the case of a trader. They are needed to link inbound goods with outbound goods to maintain end-to-end traceability. Processes can be long lasting and they are linked to a location where they happened. #### Inputs & Outputs Items that enter and exit processes are added by linking them to the process via the .../inputs and .../outputs endpoints.