ActivateAuthenticateAmplify
DashboardSupportDeveloper Blog

Mass-scale ADI Generation

Suggest Edits

The EVRYTHNG Platform is built for the purpose of creating, managing, and enhancing resources at a very large scale. The main kind of resource or ADI (Active Digital Identity) that typically exists in a large quantity are Thngs. Thngs represent unique instances of a given product SKU, and so the ratio between Thng resources and their products is quite high.

Thngs can be created in a number of ways. For testing purposes and simple projects, they are created one by one through the Dashboard or via the API. However, to create thousands or tens of thousands of Thngs in either of these ways would take a very long time, and be very labor intensive.

To make the process of mass creation of Thngs faster and easier, the EVRYTHNG Platform includes the ADI Orders API. ADI orders themselves can be thought of as a single instruction to create a large amount of Thngs to a strict specification, such as "create 10 Thngs for the 'Blue T-shirt' product, each containing the 'shipped' and 'boxed' tags". These Thngs are also given a serialised identifier and an optional redirection, and can be linked to a purchase order.

Both the ADI order and the Thngs created can include additional tags, identifiers and customFields to suit the use-case.

This walkthrough will demonstrate how to use ADI orders for some of the most common use-cases:

  • Generate Thngs from a list of supplied IDs.
  • Generate Thngs using IDs in a provided CSV file.
  • Generate Thngs that use the GS1 Digital Link feature.

Thngs from a list of IDs

The most common use-case when generating large amounts of Thngs is to create them using a list of existing IDs or serial numbers, likely from some other source or part of the organisation responsible for item serial numbers.

The example described earlier expressed as an ADI order resource would look like the following. Note the metadata field that corresponds to specification posited above, as well as the list of ids used for each Thng. 

{
  "metadata": {
    "identifierKey": "serial_id",
    "product": "pid:38497",
    "tags": [
      "shipped",
      "boxed"
    ],
    "shortDomain": "tn.gg",
    "defaultRedirectUrl": "https://evrythng.com?id={shortId}"
  },
  "purchaseOrder": "893456798",
  "ids": [
    "3829645",
    "3829646",
    "3829647",
    "3829648",
    "3829649",
    "3829650",
    "3829651",
    "3829652",
    "3829653",
    "3829654"
  ],
  "tags": [
    "example"
  ]
}

Some other things to note:

  • The metadata specifies that the ID should be added to each Thng using the serial_id identifier name, as well as other static data to be included in each Thng.
  • Each Thng is linked to the product 'Blue T-shirt' with identifier pid with value 38497. This must correspond to the identifiers of a product in the same account.
  • The purchase order is also included to link the Thngs created to the order for their creation.

Note that in this case all the Thngs have the same redirection URL, but the templating of the shortId allows the destination application to present a different experience for each unique Thng by reading the query string.

First, ensure the product exists and has the correct pid identifier. Note that any client-specific identifier name can be used - this is just an example:

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.com/products \
  -d '{
  "name": "Blue T-shirt",
  "identifiers": {
    "pid": "38497"
  }
}'

evrythng products create '{
  "name": "Blue T-shirt",
  "identifiers": {
    "pid": "38497"
  }
}'

Next, create the ADI order using the product's identifier, the purchase order ID, and the list of IDs for each Thng. As for the product identifier, the Thng's serialising identifier key can be any valid string.

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.com/adis/orders \
  -d '{
  "metadata": {
    "identifierKey": "serial_id",
    "product": "pid:38497",
    "tags": [
      "shipped",
      "boxed"
    ],
    "shortDomain": "tn.gg",
    "defaultRedirectUrl": "https://evrythng.com?id={shortId}"
  },
  "purchaseOrder": "893456798",
  "ids": [
    "3829645",
    "3829646",
    "3829647",
    "3829648",
    "3829649",
    "3829650",
    "3829651",
    "3829652",
    "3829653",
    "3829654"
  ],
  "tags": [
    "example"
  ]
}'

evrythng adi-orders create '{
  "metadata": {
    "identifierKey": "serial_id",
    "product": "pid:38497",
    "tags": [
      "shipped",
      "boxed"
    ],
    "shortDomain": "tn.gg",
    "defaultRedirectUrl": "https://evrythng.com?id={shortId}"
  },
  "purchaseOrder": "893456798",
  "ids": [
    "3829645",
    "3829646",
    "3829647",
    "3829648",
    "3829649",
    "3829650",
    "3829651",
    "3829652",
    "3829653",
    "3829654"
  ],
  "tags": [
    "example"
  ]
}'

The response confirms the details of the order, and includes an id for the ADI order (to enable reads), and also the status of the order. The latter allows you to check back on progress of large orders.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UNhRqnhkVM87trwRwhQKbaKr",
  "status": {
    "state": "pending",
    "requested": 10,
    "adis": {
      "created": 0,
      "pending": 0,
      "errorsCount": 0
    }
  },
  "metadata": {
    "identifierKey": "serial_id",
    "product": "pid:38497",
    "tags": [
      "shipped",
      "boxed"
    ],
    "shortDomain": "tn.gg",
    "defaultRedirectUrl": "https://evrythng.com?id={shortId}"
  },
  "purchaseOrder": "893456798",
  "tags": [
    "example"
  ]
}

Thngs with IDs from a CSV File

A common scenario is that IDs of individual product items to be imported to the EVRYTHNG Platform are provided in a CSV file, such as one ID per line. This is especially common if the IDs are sourced from an external system or partner. An example is shown below:

id,name,destination,pid,color
6587565785,Blue T-shirt,ES,38497,red
7875675860,Blue T-shirt,ES,38497,red
8687567547,Blue T-shirt,ES,38497,red
6758675779,Blue T-shirt,ES,38497,red
7765463764,Blue T-shirt,ES,38497,red
7887566786,Blue T-shirt,ES,38497,red

The solution to this case is to prepare the list of IDs separately in JSON format. This works well with using the evrythng.js SDK to create the order, as demonstrated below in a Node.js script:

const evrythng = require('evrythng');
const fs = require('fs');
const neatCsv = require('neat-csv');

const [csvPath] = process.argv.slice(2);
const { OPERATOR_API_KEY } = process.env;

/**
 * The main function. Reads the CSV file and creates an ADI order
 */
const main = async () => {
  // Read the CSV file
  const records = await neatCsv(fs.readFileSync(csvPath, 'utf8'));

  // Assemble the order using the IDs column mapped to list
  const payload = {
    metadata: {
      product: 'gs1:01:00789968000023',
      identifierKey: 'gs1:21',
      tags: ['example'],
      shortDomain: 'tn.gg',
      defaultRedirectUrl: 'https://evrythng.com?id={shortId}'
    },
    ids: records.map(p => p.id),
    purchaseOrder: '893456798',
    tags: ['example'],
  };

  // Create the ADI order and show the ID
  const operator = new evrythng.Operator(OPERATOR_API_KEY);
  const res = await operator.adiOrder().create(payload);
  console.log(`Created ADI order: ${res.id}`);
};

main();

Then run such a script on the example file ids.csv:

# Dependencies
npm i --save evrythng neat-csv

# Order the IDs using an ADI order
node orderIds.js ./ids.csv

Created ADI order: UNYa7edqeMs7tNwwwhH8En4k

As before, this ID can be used to retrieve the status of the order and track its progress:

curl -i -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.com/adis/orders/UNYa7edqeMs7tNwwwhH8En4k

evrythng adi-orders UNYa7edqeMs7tNwwwhH8En4k read

After a small amount of time, the order is complete, and the response reflects this:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UNYa7edqeMs7tNwwwhH8En4k",
  "status": {
    "state": "completed",
    "requested": 10,
    "adis": {
      "created": 10,
      "pending": 0,
      "errorsCount": 0
    }
  },
  "metadata": {
    "identifierKey": "serial_id",
    "product": "pid:38497",
    "tags": [
      "example"
    ],
    "shortDomain": "tn.gg",
    "defaultRedirectUrl": "https://evrythng.com?id={shortId}"
  },
  "purchaseOrder": "893456798",
  "tags": [
    "example"
  ]
}

Generate Thngs with a GS1 Digital Link

Thngs and products can be associated with a GS1 Digital Link, which includes their GS1 standard GTIN and Serial numbers, for example. Therefore, a common use-case of the ADI Orders API is to generate Thngs and automatically include this information in one step. By including the redirection short domain and URL template, this enables the GS1 Digital Link integration for the generated Thngs in one step.

To recap the GS1 Digital Link integration documentation:

  • The product identifiers should include gs1:01 for the GTIN.
  • The Thng identifiers should include gs1:21 for the serial number.
  • The Thng should refer to the product as its product property, thus representing unique instances of the product SKU.
  • The Thng must have a redirection set up, to provide a destination for users.

Once these are all in place, it is possible to refer to the Thng and product through a GS1 Digital Link URL. In this scenario, the GTIN shall be the 14 character string 00789968000023, and the Thng serial numbers will increase from 5009645 through 5009654 for 10 Thngs in total (though in reality this will be often many times larger).

The first step is to create (or update) the product, and ensure the GTIN is set in identifiers:

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.com/products \
  -d '{
  "name": "Blue T-shirt",
  "identifiers": {
    "gs1:01": "00789968000023"
  }
}'

evrythng products create '{
  "name": "Blue T-shirt",
  "identifiers": {
    "gs1:01": "00789968000023"
  }
}'

The next step is to create the Thngs with the ADI Orders API. This will create each Thng using the metadata as the template, referring to the product with the GTIN identifier, and specifying the IDs with an identifierKey of gs1:21 and individual IDs between 5009645 and 5009654:

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.com/adis/orders \
  -d '{
  "metadata": {
    "identifierKey": "gs1:21",
    "product": "gs1:01:00789968000023",
    "tags": [
      "example"
    ],
    "shortDomain": "tn.gg",
    "defaultRedirectUrl": "https://evrythng.com?id={shortId}"
  },
  "purchaseOrder": "893456798",
  "ids": [
    "5009645",
    "5009646",
    "5009647",
    "5009648",
    "5009649",
    "5009650",
    "5009651",
    "5009652",
    "5009653",
    "5009654"
  ],
  "tags": [
    "example"
  ]
}'

# Create with payload string
evrythng adi-orders create '{
  "metadata": {
    "identifierKey": "gs1:21",
    "product": "gs1:01:00789968000023",
    "tags": [
      "example"
    ],
    "shortDomain": "tn.gg",
    "defaultRedirectUrl": "https://evrythng.com?id={shortId}"
  },
  "purchaseOrder": "893456798",
  "ids": [
    "5009645",
    "5009646",
    "5009647",
    "5009648",
    "5009649",
    "5009650",
    "5009651",
    "5009652",
    "5009653",
    "5009654"
  ],
  "tags": [
    "example"
  ]
}'

Once this process has completed, you should be able to obtain a redirected experience from any of the Thngs created via their GS1 Digital Link. For example, for a Thng with a identifiers.gs1:21 of 5009646 associated with a product with a identifiers.gs1:01 of 00789968000023 will have the following GS1 Digital Link made available by the EVRYTHNG Platform:

https://abcde.tn.gg/01/00789968000023/21/5009646

Where abcde is the GS1 domain for the account concerned.

A simple way to test this is with the curl command:

curl -i https://abcde.tn.gg/01/00789968000023/21/5009646

The result should contain the desired redirection URL set as the location header:

HTTP/1.1 307 Temporary Redirect
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Link, Location, X-Result-Count, X-Calculation-Date
date: Tue, 13 Nov 2018 15:31:42 GMT
link: <https://id.gs1.org/01/00789968000023/21/5009646>; rel="canonical"
location: https://evrythng.com?id=fyzqDStf
Strict-Transport-Security: max-age=15552000; includeSubDomains
Content-Length: 0
Connection: keep-alive

This indicates that the GS1 Digital Link for the Thng is in good working order. You can obtain a QR code of this link from the EVRYTHNG Dashboard, or encode the full URL into a QR code using your own preferred generator.

Conclusion

You have now seen three of the most common scenarios for using the ADI Orders API, but there are more that can be catered for - the metadata for the Thngs and the orders themselves include the ability to extend with additional identifiers and customFields.

Read the ADI Orders API Reference page for all the detailed information on ADI order creation and the different options available.

Updated over 2 years ago