Action Types (legacy)

An account Operator or Trusted Application can define new custom action types within that account, which can be scoped to individual projects as required. When defining these action types, it's possible to add specific custom fields and tags to aid in filtering. An action type can be regarded as the class of an individual action, much in the same way that a product is used to model the class of individual serialised Thngs.

Action types that are created in a project scope can later be shared with other projects using the 'Add to another project' button in the Dashboard, or through the REST API. See Scoping for more information on sharing resources between projects.

📘
Note
Custom action types must always start with an underscore (_).

API Status
General Availability:
/actions
/actions/:type

Jump To ↓

ActionTypeDocument Data Model
Built-in Action Types
Action Type Customization
Create an Action Type
Read all Action Types
Update an Action Type
Delete an Action Type

ActionTypeDocument Data Model

.name (string, required)
    The name of the action type. Custom action types must begin 
    with an underscore.

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

.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 describing a custom action type.",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the action type. Custom action types must begin with an underscore."
    },
    "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."
    },
    "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": ["name"]
}

{
  "id": "UHwsppkh69tVhPRaaDEpdCbg",
  "createdAt": 1510914951694,
  "customFields": {
    "region_code": "en_sc"
  },
  "tags": [
    "example",
    "actionType"
  ],
  "updatedAt": 1510914951694,
  "name": "_Shipped",
  "description": "An item was shipped from a distribution center."
}

Filterable Fields

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

Field	Type	Operators
`name`	String	`=`

Built-in Action Types

In addition to custom action types there are a number of action types that are built-in to the Platform, which available to all accounts when they are created. These are listed below:

scans
implicitScans
invalidScans
shares
checkins
commissions
decommissions
encodings

Action Type Customization

When an action type is viewed in the Dashboard, it is displayed with some additional visual elements if the type's customFields includes any of the following optional items:

color - The hexadecimal color value, including #, used in the action table margin.
displayname - The friendly name of the action type, which does not require an underscore, unlike name.
icon - A Glyphicon code for an icon representing the meaning of this action type.

Create an Action Type

Submit a valid ActionTypeDocument to the /actions endpoint to create a custom action type.

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

ActionTypeDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/actions' \
  -d '{
    "name": "_Shipped",
    "description": "An item was shipped from a warehouse."
  }'

const payload = {
  name: '_Shipped',
  description: 'An item was shipped from a warehouse.',
};

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

ActionType actionType = new ActionType();
actionType.setName("_Shipped");
apiManager.actionService().actionTypeCreator(actionType).execute();

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

{
  "id": "Uh8cBH7dMnXd8NbmyxB7tdqk",
  "createdAt": 1474448083763,
  "updatedAt": 1474448083763,
  "name": "_Shipped",
  "description": "An item was shipped from a warehouse."
}

Read all Action Types

Action types can be retrieved by a GET on the /actions endpoint. The action types are returned with the built-in types coming first, followed by the custom types sorted by descending creation date. The result may be paginated if there are more than 30 items.

GET /actions
Authorization: $APPLICATION_USER_API_KEY

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

user.actionType().read()
  .then(console.log);

List<ActionType> types = apiManager.actionService().actionTypesReader().execute();
for(ActionType type : types) {
    System.out.println(type.getName());
}

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

[
  {
    "name": "checkins"
  },
  {
    "name": "commissions"
  },
  {
    "name": "decommissions"
  },
  {
    "name": "encodings"
  },
  {
    "name": "implicitScans"
  },
  {
    "name": "invalidScans"
  },
  {
    "name": "scans"
  },
  {
    "name": "shares"
  },
  {
    "id": "UGFqk8eCVXPRQKwwwgGcHmGh",
    "createdAt": 1502383685794,
    "tags": [
      "custom"
    ],
    "updatedAt": 1505491159408,
    "name": "_Shipped",
    "description": "An item was shipped from a warehouse"
  }
]

Update an Action Type

Update an action type by making a PUT request.

PUT /actions/:name
Content-Type: application/json
Authorization: $APPLICATION_USER_API_KEY

ActionTypeDocument (subset)

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

const actionType = '_Shipped';
const payload = { tags: ['shipping', 'receiving'] };

operator.actionType(actionType).update(payload)
  .then(console.log);

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

{
  "id": "Uk7WdgFAMQtehsRawgdwEkCn",
  "createdAt": 1490368131932,
  "tags": [
    "shipping",
    "receiving"
  ],
  "updatedAt": 1497450736023,
  "name": "_Shipped"
}

Delete an Action Type

You can delete an action type in a similar manner to creating one using the actionType.

📘
Note
The default action types cannot be deleted.

❗️
Note
Deleting an action type will result in the deletion of all actions created of that type as well.

DELETE /actions/:actionType
Authorization: $OPERATOR_API_KEY

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

const actionType = '_Shipped';

operator.actionType(actionType).delete();

String actionType = "_Shipped";

apiManager.actionService().actionTypeDeleter(actionType).execute();

HTTP/1.1 200 OK