Collections

A collection resource allows you to group a set of Thngs under some common grouping criteria. For example, a collection can be used to represent a production batch of some product, where the Thngs in the collection are the individual manufactured items from that batch. This can make it easier for Application Users to manage all the Thngs they created while using an application. This works by assigning a reference to the collection to each Thng, and listing the Thngs that reside in each collection. Collections can be added as children to other collections (such as a pallet within a container), and so on.

Collections have a similar data model to other resources in the Platform (a name and description, tags, and customFields etc.) and are created in a similar manner. Once a collection has been created, users can add or remove Thngs to or from that collection. See below for examples.

In addition to specifying a collection in an action, it is also possible to create an action through the collection itself using aliased actions.

API Status
General Availability:
/collections
/collections/:collectionId
/collections/:collectionId/thngs
/collections/:collectionId/collections
/collections/:collectionId/collections/:childCollectionId

Jump To ↓

CollectionDocument Data Model
Create a Collection
Read all Collections
Update a Collection
Delete a Collection
Read All Thngs in a Collection
Read a Collection
Add Thngs to a Collection
Remove a Thng from a Collection
Remove All Thngs from a Collection
Read All Collections in a Collection
Add Collections to a Collection
Remove a Collection from a Collection
Remove all Collections from a Collection

CollectionDocument Data Model

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

.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.

.description (string)
    Friendly description of this resource.

.type (string)
    Type of this resource. Can be unset with an empty string.

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

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

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

.collections (array of string, read-only)
    An array of collection IDs of any collections this 
    collection belongs to.

.scopes (ScopesDocument)
    Project and user scopes arrays.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object representing a Platform collection, which can contain groups of Thngs.",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "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
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "type": {
      "type": "string",
      "description": "Type of this resource. Can be unset with an empty string.",
      "maxLength": 256
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "collections": {
      "description": "An array of collection IDs of any collections this collection belongs to.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
      },
      "readOnly": true
    },
    "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": ["collections", "identifiers", "name", "tags"]
}

{
  "id": "UHa8qAMtVgPRQKaawEf5hfQm",
  "createdAt": 1510917071603,
  "tags": [
    "example",
    "collection"
  ],
  "updatedAt": 1510917071603,
  "name": "Batch #36754",
  "description": "An example batch collection resource.",
  "type": "pallet",
  "identifiers": {
    "ean_8": "32833232"
  }
}

Filterable Fields

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

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

Create a Collection

Create a new collection.

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

CollectionDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/collections' \
  -d '{
    "name": "Office-322",
    "description": "The collection of all thngs in office 322",
    "customFields": {
      "insured": "true"
    },
    "tags": [ "Office", "Zurich", "322", "EVRYTHNG" ],
    "identifiers": {
      "collectionCode": "OZ322",
      "collectionReferenceNumber": "12345"
    }
  }'

const payload = {
  name: 'Batch #36754',
  description: 'An example batch collection resource',
  tags: ['shipped', 'europe],
  identifiers: {
    ean_8: '32833232',
  },
};

user.collection().create(payload)
  .then(console.log);

Collection collection = new Collection();
collection.setName("Batch #36754");
apiManager.collectionService().collectionCreator(collection).execute();

HTTP/1.1 201 Created
Location: https://api.evrythng.com/collections/UmSyPf5RBg8RtpRaag9F9s3b
Content-Type: application/json

{
  "id": "UmSyPf5RBg8RtpRaag9F9s3b",
  "createdAt": 1346865441719,
  "updatedAt": 1346865441719,
  "tags": ["example", "europe"],
  "name": "Batch #36754",
  "description": "An example batch collection resource."
}

Read All Collections

Read all available collections. The result may be paginated if there are more than 30 items.

GET /collections
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/collections'

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

List<Collection> collections = apiManager.collectionService().collectionsReader().execute();
for(Collection collection : collections) {
    System.out.println(collection.getId());
}

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

[
  {
    "id": "UmSc8WnPeXswtKRwwgkqBqHh",
    "createdAt": 1494410670561,
    "updatedAt": 1494836856606,
    "name": "Batch #36754",
    "description": "An example batch collection resource",
    "tags": [
      "example",
      "europe"
    ],
    "collections": [
      "UmSyPf5RBg8RtpRaag9F9s3b"
    ]
  }
]

Update a Collection

Update a collection's fields with new data. Nested fields such as tags are replaced entirely with the value in the payload. The response payload is the complete updated collection document.

📘
Note
There is a limit of 10,000 Thngs updated per API call on collections. If your collection contains more than 10,000 elements you should consider an iterative solution.

PUT /collections/:collectionId
Authorization: $OPERATOR_API_KEY

CollectionDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/collections/U2a4AsGtqerbcWD6qhYGfb5d' \
  -d '{
    "name": "New Collection Name",
    "description": "New Collection Description",
  }'

const collectionId = 'UhQMMnGQbxnteaSDp7G8Fynn';
const payload = {
  name: 'New Collection Name',
  description: 'New Collection Description'
};

// in a single request
user.collection(collectionId).update(payload)
  .then(console.log);

String collectionId = "U2a4AsGtqerbcWD6qhYGfb5d";

Collection collection = new Collection();
collection.setName("New Collection Name");
collection.setDescription("Updated collection description");
collection = apiManager.collectionService().collectionUpdater(collectionId, collection).execute();

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

{
  "id": "U2a4AsGtqerbcWD6qhYGfb5d",
  "createdAt": 1474984969259,
  "updatedAt": 1474984989915,
  "name": "New Collection Name",
  "description": "New Collection Description",
  "tags": [
    "example",
    "europe"
  ]
}

Delete a Collection

Delete a single collection by ID.

📘
Note
If the collection contains more than 500 Thngs, these will need to be removed from the collection (but not deleted themselves) before the collection may be deleted itself.

DELETE /collections/:collectionId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/collections/U2a4AsGtqerbcWD6qhYGfb5d'

const collectionId = 'U2a4AsGtqerbcWD6qhYGfb5d';

operator.collection(collectionId).delete();

String collectionId = "U2a4AsGtqerbcWD6qhYGfb5d";

apiManager.collectionService().collectionDeleter(collectionId).execute();

HTTP/1.1 200 OK

Read All Thngs in a Collection

Get the list of all the thngs in a collection can be retrieved via a GET on the /thngs resource of a collection. The result may be paginated if there are more than 30 items.

GET /collections/:collectionId/thngs
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/collections/U2wGPSspbrqFcKxdVtM8yhgt/thngs'

const collectionId = 'U2wGPSspbrqFcKxdVtM8yhgt';

user.collection(collectionId).thng()
  .read()
  .then(console.log);

String collectionId = "U2wGPSspbrqFcKxdVtM8yhgt";

List<Thng> thngs = apiManager.collectionService().thngsReader(collectionId).execute();
for (Thng t : thngs) {
    System.out.println(t.toString());
}

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

[
  {
    "id": "U2wGPSspbrqFcKxdVtM8yhgt",
    "createdAt": 1492606257456,
    "updatedAt": 1496752159725,
    "name": "Item #3487",
    "product": "UFKE9nHBBg8atKaawgVrKKbs",
    "collections": [
      "U2wGPSspbrqFcKxdVtM8yhgt"
    ]
  }
]

Read a Collection

Read a single collection by its ID.

GET /collections/:collectionId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/collections/U2wGPSspbrqFcKxdVtM8yhgt'

const collectionId = 'U2wGPSspbrqFcKxdVtM8yhgt';

operator.collection(collectionId).read()
  .then(console.log);

String collectionId = "U2wGPSspbrqFcKxdVtM8yhgt";

Collection collection = apiManager.collectionService().collectionReader(collectionId).execute();

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

{
  "id":"U2wGPSspbrqFcKxdVtM8yhgt",
  "createdAt":1346865128086,
  "updatedAt":1347024162647,
  "name": "Batch #36754",
  "description": "An example batch collection resource.",
  "tags": ["example", "europe"]
}

Add Thngs to a Collection

Thngs can be added to a collection by PUTing an array with their respective thngIds to the /thngs.

📘
Note
The maximum number of Thngs that can be added to a collection is 10,000 per request.

PUT /collections/:collectionId/thngs
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

[ ThngID, ... ]

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/collections/UhQMMnGQbxnteaSDp7G8Fynn/thngs' \
  -d '[
    "UBMpmseRseKRBaDYKg5ychya", 
    "UemSgmdP8BpwT4N9sHbAUd5q"
  ]'

const collectionId = 'UhQMMnGQbxnteaSDp7G8Fynn';

// List of Thng IDs
const payload = [
  'UBMpmseRseKRBaDYKg5ychya',
  'UemSgmdP8BpwT4N9sHbAUd5q'
];

user.collection(collectionId).thng()
  .update(payload)
  .then(console.log);

String collectionId = "UhQMMnGQbxnteaSDp7G8Fynn";

apiManager.collectionService().thngsAdder(collectionId, thngIdList).execute();

HTTP/1.1 200 OK

You can also add Thngs to collections as they are created, by including an array of IDs of collections the Thng should be added to in the creation request:

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

{
  "name": "Item #38746",
  "collections": [
    "UHNfNCpMeD8RQKRwwE96aedk"
  ]
}

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

{
  "id": "U4rWsCfnBg8RQKwRak2hUtrq",
  "createdAt": 1523967322548,
  "updatedAt": 1523967322548,
  "name": "Item #38746",
  "collections": [
    "UHNfNCpMeD8RQKRwwE96aedk"
  ]
}

Remove a Thng from a Collection

Thngs can be removed from within a collection, by sending a DELETE to their ID within the :collectionID/thngs sub-resource of a collection.

📘
Note
There is a limit of 500 Thngs deleted per API call on collections. If your collection contains more than 500 elements you should consider an iterative solution.

DELETE /collections/:collectionId/thngs/:thngId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/collections/UhQMMnGQbxnteaSDp7G8Fynn/thngs/UF6qwDbaVDPwQKRwagmnqyqs'

const collectionId = 'UhQMMnGQbxnteaSDp7G8Fynn';
const thngId = 'UF6qwDbaVDPwQKRwagmnqyqs';

operator.collection(collectionId).thng(thngId)
  .delete();

String collectionId = "UhQMMnGQbxnteaSDp7G8Fynn";
String thngId = "UF6qwDbaVDPwQKRwagmnqyqs";

apiManager.collectionService().thngRemover(collectionId, thngId).execute();

HTTP/1.1 200 OK

Remove All Thngs from a Collection

All Thngs within a collection can be removed by sending a DELETE to the /thngs resource of a collection.

DELETE /collections/:collectionId/thngs
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/collections/U2a4AsGtqerbcWD6qhYGfb5d/thngs'

const collectionId = 'U2a4AsGtqerbcWD6qhYGfb5d';

operator.collection(collectionId).thng()
  .delete();

String collectionId = "U2a4AsGtqerbcWD6qhYGfb5d";

apiManager.collectionService().thngsRemover(collectionId).execute();

HTTP/1.1 200 OK

Read All Collections in a Collection

The list of all the collections in a collection can be retrieved via a GET on the /collections sub-resource of a collection. The result may be paginated if there are more than 30 items.

GET /collections/:collectionId/collections
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/collections/U2a4AsGtqerbcWD6qhYGfb5d/collections'

const collectionId = 'U2a4AsGtqerbcWD6qhYGfb5d';

operator.collection(collectionId).collection()
  .read()
  .then(console.log);

String collectionId = "U2a4AsGtqerbcWD6qhYGfb5d";

List<Collection> collections = apiManager.collectionService().childrenCollectionsReader(collectionId).execute();
for(Collection child : collections) {
    System.out.println(child.toString());
}

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

[
  {
    "id": "UmSyPf5RBg8RtpRaag9F9s3b",
    "createdAt": 1494410672569,
    "updatedAt": 1494836852529,
    "name": "Case #38497",
    "description": "A case within a batch",
    "collections": [
      "U2a4AsGtqerbcWD6qhYGfb5d"
    ]
  }
]

Add Collections to a Collection

Child collections can be added to a collection by POSTing an array with their respective IDs to the /collections endpoint.

POST /collections/:collectionId/collections
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

[ CollectionID, ... ]

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/collections/U2amsb7M7a2bD4xD9mEVDdWf/collections' \
  -d '[
    "UFwG8xsAb7qkcKbdeQMscDer", 
    "U2a4AsGtqerbcWD6qhYGfb5d"
  ]'

const collectionId = 'U2amsb7M7a2bD4xD9mEVDdWf';

// The child collections to add to collection
const payload = [ 
  'UFwG8xsAb7qkcKbdeQMscDer', 
  'U2a4AsGtqerbcWD6qhYGfb5d' 
];

operator.collection(collectionId).collection()
  .create(payload)
  .then(console.log);

String collectionId = "U2amsb7M7a2bD4xD9mEVDdWf";

HashSet<String> childCollectionSet = new HashSet<String>();
childCollectionSet.add("UFwG8xsAb7qkcKbdeQMscDer");
childCollectionSet.add("U2a4AsGtqerbcWD6qhYGfb5d");

apiManager.collectionService().childrenCollectionsAdder(collection1Id, childCollectionSet).execute();

HTTP/1.1 200 OK

Remove a Collection from a Collection

Collections can be removed from within a collection, by sending a DELETE to their ID within the :collectionId/collections sub-resource of a collection.

DELETE /collections/:collectionId/collections/:childCollectionId
Authorization: $OPERATOR_API_KEY

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/collections/UhQMMnGQbxnteaSDp7G8Fynn/collections/U2amsb7M7a2bD4xD9mEVDdWf'

const parentId = 'UhQMMnGQbxnteaSDp7G8Fynn';
const childId = 'U2amsb7M7a2bD4xD9mEVDdWf';

operator.collection(childId).collection(parentId)
  .delete();

String parentCollectionId = "UhQMMnGQbxnteaSDp7G8Fynn";
String childCollectionId = "U2amsb7M7a2bD4xD9mEVDdWf";

apiManager.collectionService().childCollectionRemover(parentCollectionId, childCollectionId).execute();

HTTP/1.1 200 OK

Remove all Collections from a Collection

All collections within a collection can be removed by sending a DELETE to the /collections resource of a collection.

DELETE /collections/:collectionId/collections
Authorization: $OPERATOR_API_KEY

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/collections/UhQMMnGQbxnteaSDp7G8Fynn/collections'

const parentId = 'UhQMMnGQbxnteaSDp7G8Fynn';

operator.collection(parentId).collection()
  .delete();

String parentCollectionId = "UhQMMnGQbxnteaSDp7G8Fynn";

apiManager.collectionService().childrenCollectionsRemover(parentCollectionId).execute();

HTTP/1.1 200 OK