Track and Trace Quick Start | Vendia
Track and Trace Quick Start
Note: This quickstart uses a 4-workspace project configuration, which is not viable for Starter tier users given the workspace limits enforced. See full details on the Pricing page.
The management of risk within a supply chain is crucial to control cost and ensure customer commitments are met. Visibility into supply chain activities and inventory handling is paramount in identifying risks and opportunities. For example, manufacturers may wish to identify patterns in shipping activities that have previously damaged goods. When supply chain logistics extended beyond a single organization to include shippers, retailers, and other parties, this visibility can only be enabled through the sharing of data. Vendia projects provide a platform for sharing data and code with partners in real-time across geographies, cloud-accounts, and technology stacks.
In this Quick start, you will demonstrate how Vendia projects can easily be implemented to track and trace goods in a supply chain as they move from manufacturer to shipper and ultimately to retailers.
By the end of this Quick start you will have:
- Created a Vendia project with a pre-defined data-model
- Defined a network of business partners and on-boarded them to the project
- Used the automatically generated HTTPS GraphQL API to interact with the project
- Quickly performed an analysis of supply chain data to answer business questions
Prerequisites
This Quick start uses the Vendia share-cli, a Command Line Interface (CLI) for creating and managing projects. We will be using the share-cli to deploy and manage our project.
Command Line Installation
The share-cli can be installed using the NodeJS Node Package Manager (NPM).
To install the CLI globally, run the following command:
npm install @vendia/share-cli -g
Note: You can also install Vendia CLI inside a project (instead of globally).
For more information, please visit the @vendia/share-cli NPM package page or view the CLI commands list.
You will need to have a valid Vendia user in order to deploy this Quick start. Please sign up for Vendia if you have not already done so.
Step 1 - Prepare the Deployment Files for the project
In this Quick start, we have provided sample files including a data-model for your use that describes four collections of data:
| Type | Description |
|---|---|
| Inventory | Inventory records provide information about products including their Name, SKU, Location, and Quantity on Hand. |
| Shipment | Shipment records reflect the movement of products to and from locations in the supply chain. |
| Order | Order records reflect a purchase of inventory from the manufacturer that will require a shipment for delivery to a retailer. |
| Warehouse | Warehouse records detail the locations along the supply chain where partners may store goods throughout the manufacturing, shipping, and receiving activities. |
Save the Quick Start Files Below
The registration.json, schema.json, and initial-state.json will be referenced by the CLI later. Please save these files locally by expanding each section and copying the contents.
Registration file - save as registration.json
The registration.json file defines the project name, location of the schema, and the workspace configuration representing partners in the supply chain network. In this example, you will define a manufacturer, a shipper, and two retailers.
{
"name": "test-track-and-trace",
"schema": "schema.json",
"nodes": [
{
"name": "manufacturer",
"userId": "me@domain.com",
"region": "us-east-2",
"csp": "aws"
},
{
"name": "shipper",
"userId": "me@domain.com",
"region": "us-east-2",
"csp": "aws"
},
{
"name": "retailer01",
"userId": "me@domain.com",
"region": "us-west-2",
"csp": "aws"
},
{
"name": "retailer02",
"userId": "me@domain.com",
"region": "us-west-2",
"csp": "aws"
}
]
}
Schema file - save as schema.json
The schema.json file defines the data model for the project and is used to automatically generate the API that will be used later to interact with the system. This file defines the record types previously mentioned. Save it as schema.json on your local workstation in the same directory as the registration.json file you saved prior.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://vendia.net/schemas/demos/track-and-trace.json",
"title": "Track and Trace",
"description": "Track and trace shipments among a manufacturer, shipper, and retailer",
"x-vendia-indexes": {},
"x-vendia-acls": {
"InventoryAcl": {
"type": "Inventory"
},
"ShipmentAcl": {
"type": "Shipment"
},
"OrderAcl": {
"type": "Order"
},
"WarehouseAcl": {
"type": "Warehouse"
}
},
"type": "object",
"properties": {
"Inventory": {
"description": "Inventory information",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Product name",
"type": "string"
},
"sku": {
"description": "Product SKU",
"type": "string"
},
"warehouse": {
"description": "Manufacturer warehouse code",
"type": "string"
},
"availableInventory": {
"description": "Available inventory",
"type": "integer"
}
},
"required": [],
"x-vendia-unique": []
}
},
"Shipment": {
"description": "Shipment information",
"type": "array",
"items": {
"type": "object",
"properties": {
"originWarehouse": {
"description": "Shipment origin",
"type": "string"
},
"destinationWarehouse": {
"description": "Shipment destination",
"type": "string"
},
"orderId": {
"description": "Order ID",
"type": "string"
},
"created": {
"description": "When the order was placed",
"type": "string",
"format": "date-time"
},
"lastUpdated": {
"description": "When the order was last updated",
"type": "string",
"format": "date-time"
},
"location": {
"description": "Current Lat/long of the shipment",
"type": "array",
"items": {
"type": "number"
},
"minItems": 2
},
"delivered": {
"description": "Delivery status",
"type": "boolean"
}
},
"required": [],
"x-vendia-unique": []
}
},
"Order": {
"description": "Order information",
"type": "array",
"items": {
"type": "object",
"properties": {
"orderId": {
"description": "Order ID",
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sku": {
"description": "Product SKU in order",
"type": "string"
},
"quantity": {
"description": "Quantity of product in order",
"type": "integer"
}
}
}
},
"manufacturerWarehouseCode": {
"description": "Manufacturer warehouse that holds the inventory",
"type": "string"
},
"manufacturerWarehouseLocation": {
"description": "Lat/long of manufacturer warehouse",
"type": "array",
"items": {
"type": "number"
},
"minItems": 2
},
"retailerWarehouseCode": {
"description": "Retailer warehouse that placed the order",
"type": "string"
},
"retailerWarehouseLocation": {
"description": "Lat/long of retailer warehouse",
"type": "array",
"items": {
"type": "number"
},
"minItems": 2
},
"delivered": {
"description": "Order status",
"type": "boolean"
},
"created": {
"description": "When order was placed",
"type": "string",
"format": "date-time"
},
"updated": {
"description": "When order was last updated",
"type": "string",
"format": "date-time"
}
},
"required": [],
"x-vendia-unique": []
}
},
"Warehouse": {
"description": "Warehouse information",
"type": "array",
"items": {
"type": "object",
"properties": {
"companyName": {
"description": "Company name",
"type": "string"
},
"code": {
"description": "Warehouse code",
"type": "string"
},
"street1": {
"description": "Warehouse Street Address",
"type": "string"
},
"street2": {
"description": "Warehouse Warehouse Street Address Continued",
"type": "string"
},
"city": {
"description": "Warehouse City",
"type": "string"
},
"state": {
"description": "Warehouse State",
"type": "string"
},
"postalCode": {
"description": "Warehouse Postal Code",
"type": "string"
},
"country": {
"description": "Warehouse Country Code",
"type": "string"
},
"phone": {
"description": "Warehouse Phone Number",
"type": "string"
},
"fax": {
"description": "Warehouse Fax Number",
"type": "string"
},
"created": {
"description": "When the Warehouse record was created",
"type": "string",
"format": "date-time"
},
"updated": {
"description": "When Warehouse record was last updated",
"type": "string",
"format": "date-time"
}
},
"required": [],
"x-vendia-unique": []
}
}
}
}
Step 2 - Command Line Deployment
Once the files are saved, deploy the project using the share-cli.
If not already logged in to the share service, do so by running:
share login
The share uni create command can be used to deploy our project.
share uni create --config registration.json
Check on Project Status
The project deployment will take approximately 4 minutes. The status of the project deployment can be viewed by running the share get command.
Note: Your project name should differ from the example. Set the value of the
--uniargument accordingly to match thenameproperty in registration.json
share get --uni test-track-and-trace
Please refer to the Vendia CLI documentation for more detailed information.
Step 3 - Preparing to Interact with Project Data
The easiest way to work with project data is via the Graphql API. You can access the GraphQL API with a web browser by visiting the GraphQL Explorer for your project.
Open the details page for your project and click on the GraphQL explorer button for any workspace.
Run your first Query
The GraphQL Explorer window will be pre-populated with an example query. Delete this query and replace it with the sample below to list the pre-loaded inventory information. Run the query by pressing the play button and review the list of products.
query listInventory {
list_InventoryItems {
_InventoryItems {
_id
name
sku
availableInventory
warehouse
}
}
}
Step 4 - Track Products in the Supply Chain Network
Now that the project is operational and data has been loaded, the GraphQL Explorer can be used to further inspect the state of orders and shipments.
Where is My Delivery?
Imagine that Retailer Inc., represented by the code retailer01 in our network, has called regarding a delivery. The retailer provides the order id manufacturer-01.
Using the following query in the GraphQL Explorer, determine the Delivery status and Location of the related shipment.
query manufacturing0102Shipment {
list_ShipmentItems(filter: { orderId: { eq: "manufacturer-01" } }) {
_ShipmentItems {
_id
orderId
delivered
originWarehouse
destinationWarehouse
location
created
lastUpdated
}
}
}
Example Output:
{
"data": {
"list_ShipmentItems": {
"_ShipmentItems": [
{
"_id": "017d1206-7881-4279-995a-e4176d8f223a",
"orderId": "manufacturer-01",
"delivered": false,
"originWarehouse": "manufacturer",
"destinationWarehouse": "retailer01",
"location": [47.3744, -122.035],
"created": "2020-12-02T14:10:02Z",
"lastUpdated": "2020-12-02T14:10:02Z"
}
]
}
}
}
A quick review of the results shows the order was not delivered and was last reported at the location 47.3744, -122.035.
Step 5 - Trace issues with package handling
Sharing scalar data such tracking updates for shipments is easy with Vendia but it is only part of the data-sharing story. Another feature that logistics customers value is the ability to share files with workspaces inside a project.
Imagine that the shipment with which you have been working finally makes it to its intended destination. Upon inspection however, the retailer reports the package has been damaged. Using Vendia, we can begin to add physical evidence to the activities in the supply chain to identify where such damage occurs.
Vendia’s Glenn Dierkes details a solution for gathering such evidence in a recent Blog Article. This solution takes advantage of Vendia’s file-sharing feature to allow partners to upload photos of products as they traverse the supply-chain. These photos can then later be correlated to reports of damage to identify loss patterns.
Adding photos to the supply chain
Using the GraphQL Explorer, provide a photo of the damaged item.
mutation addShipmentPhoto {
addVendia_File(
input: {
sourceBucket: "source-s3-bucket"
sourceKey: "box-image.jpg"
sourceRegion: "us-east-1"
destinationKey: "shipment-017d1206-7881-4279-995a-e4176d8f223a-delivery.jpg"
}
syncMode: ASYNC
) {
transaction {
_id
transactionId
}
}
}
This mutation has posted an update to the shipment record and added a file to the project at shipment-017d1206-7881-4279-995a-e4176d8f223a-delivery.jpg. This file can be shared with other workspaces and presented directly via cloud-based storage services. As the workspaces in this project are deployed to AWS, the file is accessible via Amazon S3.
Run the following query in GraphQL Explorer to retrieve a temporary URL for the added file.
query listFiles {
listVendia_FileItems {
Vendia_FileItems {
_id
temporaryUrl
destinationKey
}
}
}
Example Output:
{
"data": {
"listVendia_FileItems": {
"Vendia_FileItems": [
{
"_id": "<file_id>",
"temporaryUrl": "<temporary_url>",
"destinationKey": "shipment-017d1206-7881-4279-995a-e4176d8f223a-delivery.jpg"
}
]
}
}
}
The returned TemporaryUrl can be opened from a web browser to inspect the photo.
Step 6 - Clean up
It is important that the project created in this Quick Start is destroyed to prevent any unexpected charges. You can destroy the project from the Website or with the CLI command below.
share uni delete --uni test-track-and-trace
IMPORTANT: The --uni argument must be adjusted to reflect the actual name of your project as defined by the name property in the registration.json file. Failure to do so may result in the accidental deletion of the wrong project.
WARNING Deleting a project is destructive and will remove all of its underlying data.
Summary and Next Steps
This Quick Start demonstrated the ease and speed with which Vendia can be leveraged to support supply chain logistics. With zero-code, data was quickly accessible between multiple parties and updates could be recorded and validated in real-time across parties.