Reference Application: Supply Chain Application

Overview

The Supply Chain application demonstrates a generic example between a Buyer, Seller, Supplier, two Warehouses, and two independent Transport Companies. The process includes:

Creating a quote request from Buyer to Seller for a given product
Supplier collecting quotes for product and transportation from the Warehouses and Transport Companies
Aggregating delivery details with price, adding margin, and sending a quote to Buyer
Upon acceptance by Buyer of the quote, order creation and initiation of goods delivery from the Warehouses
Upon delivery of goods, payment from Buyer to Seller, either in full or partially, and creation of a payment obligation through the supply chain

Getting Started

Installing

Disclaimer: This reference application is intended to demonstrate the capabilities of the DAML. You are recommended to consider other non-functional aspects, like security, resiliency, recoverability, etc prior to production use.

Prerequisites

Be sure you have the following installed.

DAML SDK
Java
Yarn
Node v12
Make
Python Pipenv

Starting the App

Build the App. Type:
```
make build
```
Note: If you change the DAML models locally, you need to re-run this command before starting the application.
Use separate terminals to launch the individual components:
```
launchers/sandbox+jsonapi+populate
launchers/automation
launchers/ui
```
The demo will run at http://localhost:3000

Stopping the App

Stop the every running command by pressing Ctrl+C.

Working with DAML Hub

As a first step, build the whole project:

make clean build

Start a new project at DAML Hub. Upload the DARs to DAML Hub (in your new project, Deployments tab / Upload file, two files target/*.dar), deploy the model (supplychain.dar, Deploy Instance).
Add the parties to the DAML Hub project: Buyer, Seller, Supplier, Warehouse1, Warehouse2, TransportCompany1, TransportCompany2.
- Download participants.json (Ledger settings tab).
- Download parties.json (Users tab).
Run the market setup:

daml script \
  --participant-config participants.json \
  --json-api \
  --dar target/supplychain.dar \
  --script-name DA.RefApps.SupplyChain.LedgerSetupScript:setupMarketWithDablParties \
  --input-file parties.json

Run the triggers from the DAML Hub UI:

Seller
DA.RefApps.SupplyChain.Triggers.AggregatedQuoteTrigger:trigger
DA.RefApps.SupplyChain.Triggers.DeliveryCompleteTrigger:trigger

Warehouse1
DA.RefApps.SupplyChain.Triggers.InventoryQuoteRequestTrigger:trigger

Warehouse2
DA.RefApps.SupplyChain.Triggers.InventoryQuoteRequestTrigger:trigger

Supplier
DA.RefApps.SupplyChain.Triggers.CalculateAggregatedQuoteTrigger:trigger

Run make package LEDGER_ID=<ledgerId> Upload target/supplychain.zip to DAML Hub and deploy the UI. Follow "View site". Upload parties.json to the UI using the button on the login screen (Upload parties.json (tokens)). Receiving no error means you have succeeded.

Note: parties.json needs to be re-uploaded to the UI every time the tokens change.

User Guide

This User Guide will take you step-by-step through the whole supply chain process described in the Overview.

Note: This demo is designed to show successful conclusion of the supply chain workflow without exceptions or error conditions. A full production implementation would include additional features, handle errors and exceptions, and incorporate appropriate security controls.

Workflow

Roles and Responsibilities

Role	Responsibility
Buyer	Buyer places a request for price and delivery for a quantity of goods with Seller. Once trade details are received from Seller, Buyer can review and accept trade details. After confirmation of trade details, the delivery process can begin. Buyer is responsible for making full or partial payments upon delivery of goods.
Seller	Seller receives an order for goods. Seller is responsible for providing the price and delivery date confirmation to Buyer. Once the order is finalized, Seller is responsible for delivering the goods. Seller is in relationships with Supplier. Seller does not need to know the full details on inventories or how orders are allocated.
Supplier	In the example, we model Supplier as a logistics provider with established contractual relationship with warehouse owners and transport companies. It is responsible for allocating orders to warehouses and finding transport companies for delivery. Suppliers need to be notified of issues during order fulfillment and transportation. Warehouses are directly owned by Supplier.
Warehouse	Warehouse keeps records of inventory and is responsible for fulfilling orders. In our simplified workflow, once goods are handed off to Transport Companies, its responsibilities are complete.
Transport Company	Transport Company is in possession of goods during transportation. It notifies relevant participants of any changes in the status of the delivery.

Steps

The Supply Chain application includes the following steps:

Market Setup: The application starts with an automated market setup process. Participants and their roles are created, and relationships are set up.
Quote Request: Buyer requests a trade quote from Seller for the price and delivery date for a quantity of goods. Seller reviews the quote request and starts the pricing and delivery collection process.

Supplier receives notification of the new trade quote request from Seller.
Inventory Management: Supplier starts the quote collection process by selecting Warehouses to fulfill the product order request. At the same time, Supplier also sends a quote request for delivery from Transport Company 1 and 2. Transport Companies give a quote for price and estimated time of arrival for the delivery.
Delivery Management: Supplier uses an automated algorithm optimized for best price to calculate and finalize delivery. The algorithm computes quantities to be delivered from the Warehouses and calculates the amount of goods Transport Company needs to deliver from the Warehouses.
Order Finalization: Supplier sends an aggregated quote to Seller. Seller can review the quote details (quantity of goods, place of shipment, transport company, price) and can add margin to the price. Seller then sends the quote to Buyer. Buyer can review the quote and approve the order. Once the order is finalized, delivery of goods can start.
Transport: Transport companies pick up product from Warehouses. Pickup of goods is affirmed by the Warehouse. Transport companies then deliver goods to Buyer.
Delivery and Payment: Buyer needs to acknowledge the delivery. When a successful delivery is acknowledged by Buyer, an automated payment obligation is created between Buyer and Seller for the amount of goods delivered. If goods are arriving separately, then partial delivery and partial payment occurs. Consecutive payment obligations can also be initiated between Seller, Supplier, Warehouses, and Transport Companies.

Running the Application

Choosing and Changing Roles

When you launch the Supply Chain application, you will see the login screen with the option to choose your role.

To log in:

On the home screen, select the party from the list.

To switch users:

Click the name of the current party at the top of the screen.
On the home screen, select a different party.

Setup

During startup, the basic buyer-seller relationship and other reference data is set up.

Requesting a New Quote

Entering the New Quote Request

To request a quote:

Log in as Buyer.
Choose the Buyer Seller Relationships tab.
Select the relationship contract.
Click on the Send Quote Request choice.
Click Add.
Fill in the parameters:
- productName: the name of the ordered product (must match an existing inventory item, so use either "Product 1" or "Product 2")
- quantity: the ordered quantity
- deliveryFrom: the start of the acceptable delivery period
- deliveryTo: the end of the acceptable delivery period
More products can be added by clicking on Add.
Choose Okay.

Accepting the Quote Request

Log in as Seller.
Choose the Quote Requests tab.
Select the contract.
Fill in the parameter of the choice Accept:
- workflowId: unique identifier of the order workflow
Click on Accept.

Sending the Request to the Supplier

Log in as Seller.
Choose the Accepted Quote Request tab.
Select the contract.
Fill in the parameter of the choice Send To Supplier:
- supplier: the Supplier party
Click on Send To Supplier.

Accepting the Supply Invitation

Log in as Supplier.
Choose the Supply Invitations tab.
Select the contract.
Click on Accept.

Preparing the Supply

Starting Price Collection

Log in as Supplier.
Choose the Supply Request tab.
Select the contract.
Click Start Price Collection.
Fill in the parameters:
- warehouses: list of Warehouse parties from which to collect the products
- transportCompanies: list of Transport Companies from whom to request transport quotes
Choose Okay.

Note that Supplier can see the available quantity of goods in each warehouse, as they are owned by Supplier.

Sending Transport Quotes

Log in as any Transport Company (TransportCompany1, TransportCompany2).
Choose the Transport Quote Request tab.
Select the contract.
Click Accept.
Fill in the parameters:
- transportableQuantity: the quantity this transport company is able to deliver from the given location (Warehouse)
- price: the total price of transportableQuantity
- pickUpDate: date of pickup at Warehouse
- deliveryDate: date of delivery to Buyer
Choose Okay.

Choosing the Best Delivery Plan

Log in as Supplier.
Choose the Pending Transport Quote Request tab.
Select the contract.
Click on ChooseTransport.

Sending the Aggregated Quote to Seller

Log in as Supplier.
Choose the Pending Aggregated Quote tab.
Select the contract.
Click Send To Seller.

Preparing and Sending the Quote

Adding Margin

Log in as Seller.
Choose the Aggregated Quotes tab.
Select the contract.
Fill in the parameter of the choice Add Margin:
- margin: a decimal number describing the margin (e.g. 0.1 means 10% margin)
Click on Add Margin.

Note: You cannot click on the contract if you did not start the triggers. In this case you need to start over, and make sure the triggers run.

Order and Delivery

Accepting the Quote

Log in as Buyer.
Choose the Quotes tab.
Select the contract.
Click on Accept.

Accepting the Order

Log in as Seller.
Choose the Order tab.
Select the contract.
Click on the StartDelivery choice.

Pick Up Products

Log in as a Transport Company (TransportCompany1, TransportCompany2).
Choose the Delivery Instruction tab.
Select the contract.
In a real system we could check if it is the pickup date of the delivery instruction, but we don't require this for sake of the demo.
Click on PickUp.

Acknowledge Pickup

Log in as a Warehouse (Warehouse1, Warehouse2).
Choose the Pickup Request tab.
Select the contract.
Click on Accept.

Start Delivery

Log in as a Transport Company (TransportCompany1, TransportCompany2).
Choose the Pending Transport tab.
Select the contract.
Click on Deliver.

Acknowledge Delivery

Log in as Buyer.
Choose the Delivery tab.
Select the contract.
In a real system we could check if it is the delivery date, but we don't require this for sake of the demo.
Click on Acknowledge.

madbence/ex-supply-chain