Creating Products with Grid on Splinter
This procedure explains how to create and manage Grid products (trade item data) using Grid’s command-line interface.
This procedure starts with steps to connect to a Splinter node and set
environment variables to simplify entering the grid
commands in the procedure.
Next, it explains how to define a product with a product YAML file, create the
product with grid product create
, and display product information with
grid product list
.
Finally, this procedure shows how to change a product with grid product
update
, then delete it with grid product delete
when it is no longer
needed.
Prerequisites
-
For Grid on Sawtooth:
- A working Grid node.
- A working Grid node.
-
For Grid on Splinter:
-
Two (or more) nodes running Grid on Splinter.
-
An approved Splinter circuit that has two (or more) member nodes.
-
A fully qualified service ID for the scabbard service on this circuit, in the format
CircuitID::ServiceString
. This procedure uses the example ID01234-ABCDE::gsAA
.
Tip: Use
splinter circuit list
to display the circuit ID, then runsplinter circuit show CIRCUIT_ID
to see the four-character service string (also called the “partially qualified service ID”). In the example Docker environment, you must run this command in the node’ssplinterd
container. -
-
The Grid daemon’s endpoint (URL and port) on one or both nodes. The example environment uses
http://localhost:8080
. -
The ID of an existing Pike organization that will own the new products. You must be defined as an agent with full product permissions for this organization. That is, one agent must be identified with your public key and must have permission to create, update, and delete products.
Tip: You can use
curl
to request organization and agent information from the Grid REST API, as in these examples:$ curl http://localhost:8080/organization?service_id=01234-ABCDE::gsAA
$ curl http://localhost:8080/agent?service_id=01234-ABCDE::gsAA
-
Existing public/private key files in
$HOME/.grid/keys/
(as generated bygrid keygen
). The example environment uses the key files$HOME/.grid/keys/alpha-agent.priv
and$HOME/.grid/keys/alpha-agent.pub
to indicate that you will be acting as your organization’s agent to add products from the alpha node. -
An existing schema for the new product. The schema name must be
gs1_product
, which tells Grid that the product schema will use the GS1 namespace. For the commands to create a product schema, see grid/examples/splinter/README.md.
Procedure
IMPORTANT: The commands in this procedure show host names, IDs, Docker
container names, and other values from the example Grid environment that are
defined by
grid/examples/splinter/docker-compose.yaml
and grid/examples/sawtooth/docker-compose.yaml
This file sets up the nodes alpha-node-000
and beta-node-000
and runs the
Grid and Splinter components in separate containers; these names appear in
example prompts and commands. (See Running Hyperledger Grid on
Splinter or Running Hyperledger Grid on
Sawtooth for more information.)
If you are not using this example environment, replace these items with the actual values for your environment when entering each command.
Connect to a Grid Node
-
Connect to the first node’s
gridd
container and start a bash session.For the example environment, use this command to connect to the
gridd-alpha
container and run Grid commands onalpha-node-000
.$ docker exec -it gridd-alpha bash root@gridd-alpha:/#
Set Up Your Environment
Set the following Grid environment variables to specify information for the
grid
commands in this procedure.
-
Set
GRID_DAEMON_KEY
to the base name of your public/private key files (the example environment usesalpha-agent
). This environment variable replaces the-k
option on thegrid
command line.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 Grid daemon’s endpoint (URL and port), such ashttp://localhost:8080
. This environment variable replaces the-url
option on thegrid
command line.root@gridd-alpha:/# export GRID_DAEMON_ENDPOINT="http://localhost:8080"
-
Set
GRID_SERVICE_ID
to the fully qualified service ID (such as01234-ABCDE::gsAA
) for the scabbard service on the circuit. This environment variable replaces the--service_id
option on thegrid
command line.root@gridd-alpha:/# export GRID_SERVICE_ID="01234-ABCDE::gsAA"
Tip: See Prerequisites for the
splinter
commands that display the circuit ID and four-character service ID string.
Define and Create a Product
Each product requires an organization ID (the owner) and at least one agent with permission to create, update, and delete the product. There must also be an existing product schema for the product’s properties. See Prerequisites for more information.
-
Create a product definition file, in YAML format, that specifies the following information:
- Product namespace (such as GS1) that corresponds with the product schema
name (such as
gs1_product
). - Product ID (such as a GTIN)
- Owner (organization ID)
- Set of product properties (each with a name, data type, and value
that conforms to the data type)
- product_namespace: "GS1" product_id: "013600000929" owner: "013600" properties: product_name: "Truvia 80 ct." image_url: "https://target.scene7.com/is/image/Target/GUEST_b7a6e983-b391-40a5-ad89-2f906bce5743?fmt=png&wid=1400&qlt=80" brand_name: "Truvia" product_description: "Truvia Sugar 80CT" gpc: 30016951 net_content: "80CT" target_market: 840
Tip: Use a YAML linter to validate the new file is formatted correctly.
- Product namespace (such as GS1) that corresponds with the product schema
name (such as
-
Use
docker cp
to copy the file into thegridd-alpha
container.$ docker cp product.yaml gridd-alpha:/
-
Add the new product by using the
grid product create
command to specify the definition in theproduct.yaml
file.root@gridd-alpha:/# grid product create --file product.yaml
This command creates and submits a transaction to add the product data to the distributed ledger. If the transaction is successful, all other nodes in the circuit can view the product data.
Note: This command does not display any output. Instead, check the log messages on the console (or the terminal window where you started the Grid Docker environment) for the success or failure of this operation.
Display Product Information
-
List all existing products to verify that the new product has been added.
root@gridd-alpha:/# grid product list ID NAMESPACE OWNER 013600000929 GS1 013600
-
(Optional) You can connect to a different node and repeat the last two commands to verify that the product has been shared with all nodes on the circuit.
a. Open a new terminal and connect to the other node’s
gridd
container (such asgridd-beta
).$ docker exec -it gridd-beta bash
b. Set the
GRID_SERVICE_ID
environment variable to the full service ID for this node (such as01234-ABCDE::xyBB
).root@gridd-beta:/# export GRID_SERVICE_ID="01234-ABCDE::xyBB"
c. Display all products. The output should be the same as on the first node.
root@gridd-beta:/# grid product list Product namespace: "013600000929" Product Type: "GS1" Owner: "013600" Properties: Property Name: "product_name" Data Type: "String" Bytes Value: Some([]) Boolean Value: Some(false) Number Value: Some(0) String Value: Some("Truvia 80 ct.") Enum Value: Some(0) Struct Values: Some([]) Lat/Long Values: Some(LatLong { latitude: 0, longitude: 0 }) . . .
Update a Product
To update a product, you must be an agent for the product owner (the organization that is identified in the product definition).
-
Modify the definition in the product YAML file (such as
product.yaml
).You don’t have to use the same file that was used to create the product, but the file must specify the same information (product ID, type, and owner) and present the product properties in the same order.
-
Use the
update
subcommand forgrid product
to submit the changes to the distributed ledger.root@gridd-beta:/# grid product update --file product.yaml
Delete a Product
IMPORTANT: Deleting a product is a potentially hazardous operation that must be done with care. Before you delete a product, make sure that no member organizations on the circuit require the product data.
To delete a product, use the delete
subcommand with the product ID and
namespace (for example, ID 013600000929
and namespace GS1
).
root@gridd-beta:/# grid product delete 013600000929 --namespace GS1
Tip: Use grid product list
to display the product ID and namespace.