A fundamental concept in the EVRYTHNG Platform are actions. An action simply represents a discrete event or real-world actions performed by an app, user, or device within an brand-specific application, and usually created with a target product or a Thng to establish an association corresponding to the real world event. For example, an action created on a Thng could represent a 'shipped from warehouse' event when an item leaves a warehouse as part of its supply chain.
Each action has a type
associated, which allows categorisation of actions, similar to how Thngs can be categorised by their associated product. See the Action Types section for information on the built-in action types we provide, as well as how to create your own custom action types as required. These built-in action types cover some common scenarios including consumer scanning and factory commissioning.
In the real world, actions are usually created by an Application User within an application and a Thng, product, or collection ID is specified as the target. This identifies simultaneously what happened, who triggered it, for which purpose, and where it occurred, building a coherent picture of the item's journey through a supply chain.
In addition to specifying a resource in an action, it is also possible to create an action through the resource itself using aliased actions.
Action Context
When reading actions, the ?context=true
query parameter can be used to include the context
field in the response. This includes useful contextual information about the creation of the action. See the ActionContextDocument Data Model section for more information.
?context=true
query parameter can be used to include the context
field in the response. This includes useful contextual information about the creation of the action. See the ActionContextDocument Data Model section for more information.API Status
General Availability:
/actions/:type
/actions/:type/:actionId
/products/:productId/actions/:actionType
/thngs/:thngId/actions/:actionType
/collections/:collectionId/actions/:actionType
ActionDocument Data Model
.type (string, required)
The action type.
.id (string, read-only)
The ID of this resource.
.user (string, read-only)
The EVRYTHNG ID of the user who has performed this action.
.createdAt (integer, read-only)
Timestamp when the resource was created.
.createdByProject (string, read-only)
The EVRYTHNG ID of the project who has performed this
action.
.createdByApp (string, read-only)
The EVRYTHNG ID of the application who has performed this
action.
.thng (string)
The EVRYTHNG ID of the Thng this action was carried out on.
.product (string)
The EVRYTHNG product ID associated with the Thng this action
was carried out on.
.collection (string)
The EVRYTHNG ID of the collection this action was carried
out on. Custom action types only.
.timestamp (integer, read-only)
The timestamp when the action took place. Filled
automatically if unspecified.
.identifiers (IdentifiersDocument)
Various identifiers (EPC, GTIN, etc.) as a JSON object with
one or more key-value pairs.
.location (LocationDocument)
An object representing a location. Either 'position' or
'place' us required.
.locationSource (string, one of 'sensor', 'geoIp', 'unknown', 'place')
The method used to find the location where the action took
place, and requires `location` to also be set. If a GPS was
used (with user permission granted), `sensor` is specified.
Otherwise an estimate is made based on the apparent
location, which may not be the device itself.
.context (ActionContextDocument)
Object containing contextual data about the action creator.
.customFields (CustomFieldsDocument)
Object of case-sensititve key-value pairs of custom fields
associated with the resource.
.scopes (ScopesDocument)
Project and user scopes arrays.
.tags (array of string)
Array of string tags associated with this resource.
.reactions (array of ReactionDocument)
An array of Redirector reactions that occured from this
action.
.url (string)
The URL to the triggering scan, added in some cases.
.consumerId (string)
App-specific ID id to identify a user that has scanned a
given product.
See also: LocationDocument
, ScopesDocument
, ReactionDocument
, ActionContextDocument
Filterable Fields
This resource type can be filtered using the following fields and operators.
ActionContextDocument Data Model
ReactionDocument Data Model
Create an Action
Create a new action of the specified type
.
Notes
all
can be used astype
. In this case, the actiontype
must be supplied in the payload.\n\n* When using/actions/all
with a custom action type, the payload can contain only thetype
, and does not require a targetthng
,product
, orcollection
.
Read an Action
Application Users and Operators can read an action by its ID. Both the Application User and Operator API keys can be used. You can use all
as the action type to access the actions of unknown type.
Read all Actions of a Type
Read all actions of a given type
. For example: GET /actions/scans
for all the scans
actions. The result may be paginated if there are more than 30 items.
A special type all
can be used to get all actions regardless of their type.
See Action Types to see how to read and manage action types.
Read an Action with Context
The ?context=true
query parameter can be used to include the context
field in the action read.
Delete an Action
Delete a single action by ID.
Create Multiple Actions
It is possible to create multiple actions at the same time using the /actions/all
endpoint. Each action in the payload array must state the action type
. Different types can be used at the same time for different actions.
Aliased Actions
It is also possible to use alias endpoints to create or read actions performed on a specific Thng, product or collection using its ID. The available endpoints are:
/products/:productId/actions/:actionType
- Actions on a specific product/thngs/:thngId/actions/:actionType
- Actions on a specific Thng/collections/:collectionId/actions/:actionType
- Actions on a specific collection
Use the same payload as for /actions/:actionType
endpoint. The action's product
, thng
, or collection
property must match the ID that is specified in the URL, or in this special case may be omitted from the payload. The responses are of the same format as the Read all actions of a type operation.
NoteOnly custom action types can be used for aliased actions.
Create an Aliased Action
The examples below show aliased action creation on a product, but are also applicable for Thngs and collections in the same /:type/:id/actions/:actionType
pattern.