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. By default, Grid products consist of product data conforming to the GS1 GDSN 3.1 standard. Additionally, users may define a separate schema to include additional, non-GDSN product attributes.

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 XML 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.
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 ID 01234-ABCDE::gsAA.
Tip: Use splinter circuit list to display the circuit ID, then run splinter 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’s splinterd 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 by grid 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 Grid on Splinter or Running 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 on alpha-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 uses alpha-agent). This environment variable replaces the -k option on the grid 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 as http://localhost:8080. This environment variable replaces the -url option on the grid command line.
```
root@gridd-alpha:/# export GRID_DAEMON_ENDPOINT="http://localhost:8080"
```
Set GRID_SERVICE_ID to the fully qualified service ID (such as 01234-ABCDE::gsAA) for the scabbard service on the circuit. This environment variable replaces the --service_id option on the grid 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. An example file defining GDSN product information can be downloaded with this link: GDSN product data.

Use docker cp to copy your product data XML file into the gridd-alpha container.
```
$ docker cp product.xml gridd-alpha:/
```
Add the new product by using the grid product create command to specify the definition in the product.xml file.
```
root@gridd-alpha:/# grid product create \
--owner myorg \
--file product.xml
```
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
00013600000929 GS1       myorg

(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 as gridd-beta).
```
   $ docker exec -it gridd-beta bash
```
b. Set the GRID_SERVICE_ID environment variable to the full service ID for this node (such as 01234-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
   ID             NAMESPACE OWNER
   00013600000929 GS1       myorg
```

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 XML file (such as product.xml).

You don’t have to use the same file that was used to create the product, but the file must specify the same GTIN and present the product properties in the same order.
Use the update subcommand for grid product to submit the changes to the distributed ledger.
```
root@gridd-beta:/# grid product update \
   --file product.xml
```

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 00013600000929 and namespace GS1).

   root@gridd-beta:/# grid product delete 00013600000929 --namespace GS1

Tip: Use grid product list to display the product ID and namespace.

Defining additional attributes

The product definition provided by the GDSN 3.1 standard is quite robust and should account for most use cases. In the event that additional attributes are required, follow the procedure outlined here.