# 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](https://www.vendia.com/pricing). 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**](https://docs.vendia.com/platform/vendia-terminology#project) 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)](https://www.npmjs.com/get-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](https://www.npmjs.com/package/@vendia/share-cli) or view the [CLI commands list](https://docs.vendia.com/platform/cli). You will need to have a valid Vendia user in order to deploy this Quick start. Please sign up for [Vendia](https://share.vendia.net/) 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](https://docs.vendia.com/platform/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 `--uni` argument accordingly to match the `name` property in registration.json ``` share get --uni test-track-and-trace ``` Please refer to the [Vendia CLI documentation](https://docs.vendia.com/platform/cli) 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](https://vendia.com/blog/track-and-trace). 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": "", "temporaryUrl": "", "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](https://share.vendia.net/) 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.