Batches

📘
Enterprise Feature

📘
Note
Creating a batch is currently only possible through the API. However, existing batches can be viewed through the Dashboard.

The Batch and Task APIs allows the generation of large quantities of Thngs quickly and easily. Creating large collections of Thngs works in the following manner:

The Batch API is used to create a placeholder for a specific batch resource and associated metadata (the data that all Thngs in batch share), but not the Thngs themselves. This represents some production batch or group of physical products to be manufactured, each of which will have a Thng generated using a Task on this batch resource.
Once you have created a batch object, you can populate it with Thngs using the Task API, where you can choose the parameters for the generation task such as the quantity of Thngs to generate, the product ID, common identifiers/custom fields, list of unique IDs, and so on.

This page describes operations on the metadata of batches. For operations you can do on a batch refer to the Tasks API page.

API Status
General Availability:
/batches
/batches/:batchId

Jump To ↓

BatchDocument Data Model
Create a Batch
Read all Batches
Read a Batch
Update a Batch
Delete a Batch

BatchDocument Data Model

.id (string, read-only)
    The ID of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.name (string, required)
    Friendly name of this resource.

.description (string)
    Friendly description of this resource.

.status (string, read-only, one of 'EMPTY', 'IN_PROGRESS', 'COMPLETE', 'SEALED')
    The status of the batch.

.resourceCountsByProduct (object, read-only)
    Count of resources, grouped by product ID. Those with no 
    product come under `NO_PRODUCT`.

.identifiers (IdentifiersDocument)
    Various identifiers (EPC, GTIN, etc.) as a JSON object with 
    one or more key-value pairs.

.tags (array of string)
    Array of string tags associated with this resource.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.scopes (ScopesDocument)
    Project and user scopes arrays.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object representing a Platform batch.",
  "required": ["name"],
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "status": {
      "type": "string",
      "description": "The status of the batch.",
      "enum": ["EMPTY", "IN_PROGRESS", "COMPLETE", "SEALED"],
      "readOnly": true
    },
    "resourceCountsByProduct": {
      "type": "object",
      "description": "Count of resources, grouped by product ID. Those with no product come under `NO_PRODUCT`.",
      "readOnly": true
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "required": ["users", "projects"],
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        }
      }
    }
  },
  "x-filterable-fields": ["createdAt", "identifiers.<key>", "name", "tags"]
}

{
  "id": "U4asNCTB6GPEYMaaRYCwwBmd",
  "createdAt": 1510921508928,
  "customFields": {
    "region": "eu"
  },
  "updatedAt": 1510921536082,
  "name": "Batch #5487",
  "description": "A batch of products created using raw materials.",
  "identifiers": {
    "gs1:10": "5487"
  },
  "status": "COMPLETE",
  "resourceCountsByProduct": {
    "UHR8MGsSCct4t9wwRgEKqrUr": {
      "thngs": 150,
      "urlBindings": 150
    }
  }
}

Filterable Fields

This resource type can be filtered using the following fields and operators.

Field	Type	Operators
`createdAt`	Number	`>`, `<`
`identifiers.<key>`	String	`=`
`name`	String	`=`
`tags`	List of string	`=`

Create a Batch

Batches are created by sending a POST request containing a JSON document to the /batches resource.

The Location header in the response returns the URL of the Batch resource that was created, which is always in the format /batches/:batchId, where batchId is the unique identifier of this batch assigned by the Platform.

POST /batches
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

BatchDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST "https://api.evrythng.com/batches" \
  -d '{
    "customFields": {
      "region": "eu"
    },
    "name": "Batch #5487",
    "description": "A batch of products created using raw materials.",
    "identifiers": {
      "gs1:10": "5487"
    }
  }'

const payload = {
  customFields: {
    region: 'eu'
  },
  name: 'Batch #5487',
  description: 'A batch of products created using raw materials.',
  identifiers: {
    'gs1:10': '5487'
  }
};

operator.batch().create(payload)
  .then(console.log);

Batch batch = new Batch();
batch.setName("Batch #R1-5");
apiManager.batchService().batchCreator(batch).execute();

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.evrythng.com/batches/504766a7c8f205a0744243d2

{
  "id": "UNREK4bCUSCdGpRwaKMfdPfs",
  "createdAt": 1560787477682,
  "customFields": {
    "region": "eu"
  },
  "updatedAt": 1560787477682,
  "name": "Batch #5487",
  "description": "A batch of products created using raw materials.",
  "identifiers": {
    "gs1:10": "5487"
  },
  "status": "EMPTY"
}

Read All Batches

To retrieve the list of all batches in your account or project, simply do a GET on the /batches resource. The result may be paginated if there are more than 30 items. You can also use ?filter or ?ids query params to restrict the returned resources.

To retrieve a subset of all the batches you have created, simply use a filter. Filterable fields are: name, tags, identifiers, createdAt, and products.

GET /batches
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/batches'

operator.batch().read()
  .then(console.log);

List<Batch> batches = apiManager.batchService().batchesReader().execute();
for(Batch batch : batches) {
    System.out.println("Batch " + batch.getId() + " - " + batch.getName());
}

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

[
  {
    "id": "UNREK4bCUSCdGpRwaKMfdPfs",
    "createdAt": 1560787477682,
    "customFields": {
      "region": "eu"
    },
    "updatedAt": 1560787477682,
    "name": "Batch #5487",
    "description": "A batch of products created using raw materials.",
    "identifiers": {
      "gs1:10": "5487"
    },
    "status": "EMPTY"
  }
]

Read a Batch

You can retrieve a batch document with a GET on the batch URL containing the batchId.

GET /batches/:batchId
Authorization: $OPERATOR_API_KEY

BatchDocument

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET "https://api.evrythng.com/batches/UFwm8bCUx7M2cpSdBQM8bfdn"

const batchId = 'UFwm8bCUx7M2cpSdBQM8bfdn';

operator.batch(batchId).read()
  .then(console.log);

String batchId = "UFwm8bCUx7M2cpSdBQM8bfdn";

Batch batch = apiManager.batchService().batchReader(batchId).execute();

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

{
  "id": "UNREK4bCUSCdGpRwaKMfdPfs",
  "createdAt": 1560787477682,
  "customFields": {
    "region": "eu"
  },
  "updatedAt": 1560787477682,
  "name": "Batch #5487",
  "description": "A batch of products created using raw materials.",
  "identifiers": {
    "gs1:10": "5487"
  },
  "status": "EMPTY"
}

Update a Batch

You can update the data of a batch using any subset of a valid BatchDocument model.

🚧
Attention
The fields are entirely overwritten by the new values, so to add a tag for example you must submit the entire updated array with the new and old tags.

PUT /batches/:batchId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

BatchDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/batches/UFwm8bCUx7M2cpSdBQM8bfdn' \
  -d '{
    "tags": ["updated"],
  }'

const batchId = 'UFwm8bCUx7M2cpSdBQM8bfdn';

const payload = { tags: ['updated'] };

operator.batch(batchId).update(payload)
  .then(console.log);

String batchId = "UFwm8bCUx7M2cpSdBQM8bfdn";

Batch batch = apiManager.batchService().batchReader(batchId).execute();
batch.setName("Batch #R1-5 | 03-2015");
apiManager.batchService().batchUpdater(batchId, batch).execute();

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

{
  "id": "UNREK4bCUSCdGpRwaKMfdPfs",
  "createdAt": 1560787477682,
  "customFields": {
    "region": "eu"
  },
  "tags": [
    "updated"
  ],
  "updatedAt": 1560787477682,
  "name": "Batch #5487",
  "description": "A batch of products created using raw materials.",
  "identifiers": {
    "gs1:10": "5487"
  },
  "status": "EMPTY"
}

Delete a Batch

To delete a batch, simply send a DELETE request to the batch's URL.

🚧
Note
Deleting the batch will not delete the tasks and resources (such as Thngs) that it created. These must be deleted manually.

DELETE /batches/:batchId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://api.evrythng.com/batches/UFwm8bCUx7M2cpSdBQM8bfdn'

const batchId = 'UFwm8bCUx7M2cpSdBQM8bfdn';

operator.batch(batchId)
  .delete()
  .then(() => console.log('Deleted!'));

String batchId = "UFwm8bCUx7M2cpSdBQM8bfdn";

apiManager.batchService().batchDeleter(batchId).execute();

HTTP/1.1 200 OK

Running Tasks on a Batch

On its own, a batch describes metadata about a group of Thngs it will contain. To learn how to populate the batch with Thngs, see Tasks.

Batches

📘
Enterprise Feature

📘
Note

BatchDocument Data Model

Filterable Fields

Create a Batch

Read All Batches

Read a Batch

Update a Batch

🚧
Attention

Delete a Batch

🚧
Note

Running Tasks on a Batch

📘Enterprise Feature

📘Note

BatchDocument Data Model

Filterable Fields

Create a Batch

Read All Batches

Read a Batch

Update a Batch

🚧Attention

Delete a Batch

🚧Note

Running Tasks on a Batch

📘
Enterprise Feature

📘
Note

🚧
Attention

🚧
Note