Using Purchase Order
This procedure describes how to create and manage purchase orders using Grid’s command-line interface.
This scenario describes how to create and manage a purchase order in a vendor-managed instance.
Prerequisites
- For Grid on Sawtooth
- A working Grid node
- A working Grid node
- For Grid on Splinter
-
Two or more working Grid nodes. (See Running Grid on Splinter for the procedure to set up and run Grid in Docker containers.) The examples in this procedure show two nodes,
alpha-node-000
andbeta-node-000
, that are running in a Docker environment. -
An organization
MyOrg
created in the Using Pike walkthrough. -
An approved Splinter circuit with two or more member nodes. (See Creating Splinter Circuits for more information.) This procedure assumes that there is a circuit with
alpha-node-000
andbeta-node-000
as members. -
A fully qualified service ID for the scabbard service on this circuit, in the format
CircuitID::ServiceString
. (See Determine the Service ID for the commands to display this information.) This procedure uses the example ID01234-ABCDE::gsAA
.
-
- The Grid daemon’s endpoint (URL and port) on one or both nodes.
This procedure uses
http://localhost:8080
.
Important Notes
The examples in this procedure use the node hostnames, container names, node
IDs, and URLs that are defined in the example docker-compose file,
examples/splinter/docker-compose.yaml
. If you are not using this example
environment, replace these items with the actual values for your nodes.
Procedure
Connect to a Grid Node
-
Start a bash session in your node’s
gridd
Docker container (such asgridd-alpha
). You will use this container to run Grid commands on the node (for example,alpha-node-000
)$ docker exec -it gridd-alpha bash
Generate Agent Keys
-
Generate a secp256k1 key pair for the organization’s agent on the alpha node. This key will be used to sign the Grid transactions that create purchase orders and set agent permissions.
This example uses the base name
alpha-agent
to indicate that you will be acting as your organization’s agent to add POs and other Grid items from the alpha node.root@gridd-alpha:/# grid keygen alpha-agent Writing /root/.grid/keys/alpha-agent.priv Writing /root/.grid/keys/alpha-agent.pub
Set Environment Variables
Set the following Grid environment variables to simplify entering the
grid
commands in this procedure.
-
Set
GRID_DAEMON_KEY
to the base name of the agent’s public/private key files (such asalpha-agent
). This environment variable replaces the-k
option on thegrid
command line.Tip: If you’re using this example docker-compose environment, this variable is already defined for the
gridd-alpha
andgridd-beta
containers.root@gridd-alpha:/# export GRID_DAEMON_KEY="alpha-agent"
Note: Although this variable has “daemon” in the name, it should reference the user key files in
$HOME/.grid/keys
, not the Grid daemon’s key files in/etc/grid/keys
. -
Set
GRID_DAEMON_ENDPOINT
to the endpoint for the node’sgridd
container (such ashttp://localhost:8080
). This environment variable replaces the--url
option on thegrid
command line.Tip: If you’re using this example docker-compose environment, this variable is already defined for the
gridd-alpha
andgridd-beta
containers.root@gridd-alpha:/# export GRID_DAEMON_ENDPOINT="http://localhost:8080"
-
For Grid on Splinter: Set
GRID_SERVICE_ID
to the fully qualified service ID for the scabbard service on this circuit (such as01234-ABCDE::gsAA
). This environment variable replaces the--service_id
option on thegrid
command line.root@gridd-alpha:/# export GRID_SERVICE_ID=01234-ABCDE::gsAA
-
Follow this same procedure in a separate command line for the
gridd-beta
container.$ docker exec -it gridd-beta bash
Create a “Buyer” Organization
- The
MyOrganization
organization created using the procedure outlined in the Using Pike section will operate as the “buyer” for this scenario.
Create a Purchase Order Admin Role
In order to submit transactions using other Grid features the submitting agent must possess an active role with the appropriate permissions.
-
Verify that the agent’s public key file exists in
~/.grid/keys/alpha-agent.pub
. If not, you must specify contents of the public key file in the next command. -
Create a role that has the appropriate permissions. The following command shows how to create a role called
po-admin
with permissions to create and update orders and versions. These permissions are included in the workflow aliaspo::partner
.root@gridd-alpha:/# grid role create \ myorg po-admin \ --description "purchase order admin permissions" \ --active \ --allowed-orgs gnrl \ --permissions "po::partner"
-
Assign this role to the admin agent for this organization
root@gridd-alpha:/# grid agent update \ myorg $(cat ~/.grid/keys/alpha-agent.pub) \ --active \ --role admin \ --role po-admin
Create a “Vendor” Organization
-
In the
gridd-beta
command line, create an organization to act as a vendor.root@gridd-beta:/# grid organization create \ gnrl "General Store"
Create a Purchase Order Manager Role
Create a role that inherits the purchase order permissions from the po-admin
permission belonging to MyOrg
-
Verify that the agent’s public key file exists in
~/.grid/keys/beta-agent.pub
. If not, you must specify contents of the public key file in the next command. -
Create a role that inherits the purchase order permissions from the
po-admin
permission belonging toMyOrganization
root@gridd-beta:/# grid role create gnrl po-manager \ --active \ --permissions "po::partner" \ --inherit-from "myorg.po-admin"
-
Add the new role to the admin agent for General Store
root@gridd-beta:/# grid agent update \ gnrl $(cat ~/.grid/keys/beta-agent.pub) \ --active \ --role admin \ --role po-manager
Download the Schemas
-
Download the purchase order schemas so that the purchase order XML data can be validated
root@gridd-alpha:/# grid download-xsd
Follow this same procedure in a separate command line for the
gridd-beta
container.For in-depth information on this utility, read
grid download-xsd
Create Purchase Order and Versions
-
Using the
gridd-beta
command line, propose a draft purchase order on behalf of MyOrg. An example purchase order XML file can be downloaded with this link: Example PO XML.root@gridd-beta:/# grid po create \ --buyer-org gnrl \ --seller-org myorg \ --alternate-id po_number:0123456 \ --workflow-state issued \ --workflow-id built-in::collaborative::v1 \ --wait 100 root@gridd-beta:/# grid po version create \ po_number:0123456 \ 1 \ --order-xml <path to order> \ --draft \ --workflow-state proposed \ --wait 100
-
At the same time, MyOrganization is creating a version of their own. Using the
gridd-alpha
command line, create a version for the purchase orderroot@gridd-alpha:/# grid po version create \ po_number:0123456 \ 2 \ --order-xml <path to order> \ --draft \ --workflow-state proposed \ --wait 100
Display Purchase Order Information
-
List all existing purchase orders to verify that the new purchase order has been added.
root@gridd-alpha:/# grid po list
-
To see the versions for a specific purchase order, use
grid po version list
root@gridd-alpha:/# grid po version list po_number:0123456
-
To see the details of a purchase order or a version, use
grid po show
orgrid po version show
, respectively.root@gridd-alpha:/# grid po show po_number:0123456 root@gridd-alpha:/# grid po version show po_number:0123456 1
Update Purchase Order
-
After some deliberation, MyOrganization decides that the version created by General Store is more accurate. Using the
gridd-alpha
command line, accept the proposed purchase orderroot@gridd-alpha:/# grid po update \ po_number:0123456 \ --version-id 1 \ --version-not-draft \ --version-workflow-state accepted \ --set-accepted-version \ --workflow-state confirmed \ --wait 100