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
/collections
/collections/:collectionId
/collections/:collectionId/thngs
/collections/:collectionId/collections
/collections/:collectionId/collections/:childCollectionId
CollectionDocument Data Model
See also: ScopesDocument
Filterable Fields
This resource type can be filtered using the following fields and operators.
__
Create a Collection
Create a new collection.
Read All Collections
Read all available collections. The result may be paginated if there are more than 30 items.
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.
NoteThere 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.
Delete a Collection
Delete a single collection by ID.
NoteIf 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.
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.
Read a Collection
Read a single collection by its ID.
Add Thngs to a Collection
Thngs can be added to a collection by PUT
ing an array with their respective thngId
s to the /thngs
.
NoteThe maximum number of Thngs that can be added to a collection is 10,000 per request.
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:
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.
NoteThere 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.
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.
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.
Add Collections to a Collection
Child collections can be added to a collection by POST
ing an array with their respective IDs to the /collections
endpoint.
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.
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.