Jobs

The Jobs API allows the Platform to execute asynchronous long running jobs, for example creating or updating many resources according to some predefined criteria.

The general concept of the Jobs API is that developers can submit multiple jobs in parallel. Each job will be then queued, executed, and the user will be notified once the job is completed. The user can query the job at any time to retrieve its current details and status (including any errors encountered during execution).

Each job has a different type which defines the output of the job. The URL and the input parameters is specific to the type, but the data models share some common fields.

📘
Available Job Types
Currently, the only supported job type is the creation of actions in bulk.

API Status
Stable:
/jobs/actions
/jobs/actions/:actionJobId
/jobs/actions/:actionJobId/logs

Jump To ↓

JobDocument Data Model
Action Jobs
ActionJobDocument Data Model
CreateActionJobDocument Data Model
Create an Action Creation Job
Read all Action Jobs
Read Action Jobs by ID
Read Action Jobs Logs

JobDocument Data Model

JobDocument = {
  "id": Ref,
  "createdAt": Timestamp,
  "updatedAt": Timestamp,
  "status": Enum,
  "history": [ JobStatusDocument, ... ],
  "progress": JobProgressDocument,
  "completedAt": Timestamp,
  "failedOperationsAmount": Integer
}

### Data Fields

id - Ref, Read-only
The unique identifier of this job. Automatically assigned by the Platform when the job is created.
createdAt - Timestamp, Read-only
When the job was created.
updatedAt - Timestamp, Read-only
When the job was last updated.
status - Enum, Read-only
The current status of the job. May be one of ENQUEUED, STARTING, EXECUTING, CANCELLING, COMPLETED, COMPLETED_WITH_FAILURES, CANCELLED, or FAILED.
history - JobStatusDocument array, Read-only
The status history of this job.
progress - JobProgressDocument, Read-only
The current progress of this job.
completedAt - Timestamp, Read-only
When this job was completed.
failedOperationsAmount - Integer, Read-only
The total count of failed operations.

JobStatusDocument Data Model

Every job has a current status, e.g. it has been queued for execution, it is currently being executed, or the execution has been completed with or without errors.

The status of any job is described in a status object with the following data model:

JobStatusDocument = {
  "status": Enum,
  "timestamp": Timestamp
}

### Data Fields

status - Enum, Read-only
The status of the Job. May be ENQUEUED, STARTING, EXECUTING, CANCELLING, COMPLETED, COMPLETED_WITH_FAILURES, CANCELLED, or FAILED.
timestamp - Timestamp, Read-only
The timestamp when this status was updated.

All job documents also have a history of the status changes, as an array of status documents.

JobProgressDocument Data Model

Every job also has a progress object that keep track of its current progress (in percentage and quantity). The progress object has the following model:

JobProgressDocument = {
  "percentage": Double,
  "amountRequested": Integer,
  "amountCompleted": Integer
}

### Data Fields

percentage - Double, Read-only
How much of the task has been currently completed (as a percentage).
amountRequested - Integer, Read-only
Total number of operations this job needs to execute.
amountCompleted - Integer, Read-only
How many operations have been executed so far.

Action Jobs

Actions jobs allow you to execute long operations involving actions. Currently, only the following action job types are supported:

ACTION_CREATION - allows to create the same Action on several Thngs with a single request.

ActionJobDocument Data Model

ActionJobDocument extends JobDocument = {
  "type": Enum
}

### Data Fields

type - Enum, Required
The type of this job (e.g., ACTION_CREATION).

InputDocument Data Model

There are various methods to specify which resources the actions will be created on. The IDs can be provided either directly in the payload of the request, or within an external file when you have a large quantity of resources (for example above 5,000 Thngs).

The InputDocument object is used to specify the source and format of how the resource IDs to create an action on will be provided. Depending on the type of job, there are multiple types of InputDocument, which are all detailed on this page.

CreateActionJobDocument Data Model

To create actions in bulk, you need to send an CreateActionJobDocument based on the following data model:

CreateActionJobDocument extends ActionJobDocument = {
  "payload": ActionDocument,
  "target": Enum,
  "input": CreateActionJobInputDocument,
  "options": [ CreateActionJobOptionDocument, ... ]
}

### Data Fields

payload - ActionDocument, Required
The ActionDocument template that all actions created will inherit. The Thng ID should not be provided here.
input - CreateActionJobInputDocument, Required
The input document that specifies the IDs on which to create the Actions (see below).
target - Enum, Required
On what resource types the actions will be created. Currently, only "THNGS" is supported.
options - CreateActionJobOptionDocument array
Array of CreateActionJobOptionDocument options.

CreateActionJobInputDocument Data Model

CreateActionJobInputDocument = {
  "type": Enum,
  "contentType": Enum,
  "shortDomain": String,
  "key": String
}

### Data Fields

type - Enum, Required
How the resources to create actions against are specified. Can be LIST (IDs are provided in the payload of the request) or FILE (IDs are provided in an external file).
contentType - Enum, Required
Specifies which type of IDs are passed as input. Can be EVRYTHNG_IDS when EVRYTHNG IDs are provided, EXTERNAL_IDS when using external identifiers (thng.identifiers), or SHORT_IDS when short IDs are provided.
shortDomain - String
The short domain used (only supported for SHORT_IDS content type).
key - String
The external identifier used, e.g. sapId (only supported for EXTERNAL_IDS content type).

CreateActionJobOptionDocument Data Model

CreateActionJobOptionDocument = {
  "type": Enum,
  "enabled": Boolean
}

### Data Fields

type - Enum, Required
The type of the option. Can be "SINGLE_RESOURCE_NOTIFICATION" to exclude push notifications for each action created by this job, or "SINGLE_RESOURCE_REACTIONS" to exclude reactions for each action created by this job.
enabled - Boolean, Required
If the option is enabled (true) or disabled (false).

List Input

The "LIST" input type is used to directly provide the IDs in the request payload. It should be used only when actions are created on a small quantity of Thngs (fewer than 5,000).

ListCreateActionJobInputDocument Data Model

ListCreateActionJobInputDocument implements CreateActionJobInputDocument = {
  "type": "LIST",
  "payload": [ String, ... ]
}

### Data Fields

payload - String array, Required
An array with the IDs on which the actions should be created.

File Input

The FILE input is used when IDs are provided in an external file (e.g. which was uploaded via the Files API). You must use the file mode when creating actions on a larger quantity of Thngs (above 5000).

Note: for security reasons, only files uploaded with our Files API will be accepted.

FileCreateActionJobInputDocument Data Model

FileCreateActionJobInputDocument implements CreateActionJobInputDocument = {
  "type": "FILE",
  "location": String,
  "format": Enum
}

### Data Fields

location - String, Required
Where the input file is located. It must be the contentUrl returned when the file is created with the Files API.
format - Enum, Required
Format of the input file. Can be CSV or ZIP (an archive of one or more CSV files).

Create an Action Creation Job

To create many actions in bulk, you simply send a POST request containing a CreateActionJobDocument JSON document to the /jobs/actions resource.

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

ActionJobDocument

curl -i -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST "https://api.evrythng.com/jobs/actions" \
  -d '{
    "type": "ACTION_CREATION",
    "input": {
      "contentType": "EVRYTHNG_IDS",
      "type": "LIST",
      "payload": [ "UGkBBn5wM3PYhMRRwDfSnrkf" ]
    },
    "payload": {
      "type": "scans"
    },
    "target": "THNGS",
    "options": [
      {
        "type": "SINGLE_RESOURCE_NOTIFICATION",
        "enabled": false
      },
      {
        "type": "SINGLE_RESOURCE_REACTIONS",
        "enabled": false
      }
    ]
  }'

const operatorApiKey = '$OPERATOR_API_KEY';

const job = {
  type: 'ACTION_CREATION',
  input: {
    contentType: 'EVRYTHNG_IDS',
    type: 'LIST',
    payload: [ 'UGkBBn5wM3PYhMRRwDfSnrkf' ]
  },
  payload: {
    type: 'scans'
  },
  target: 'THNGS',
  options: [
    {
      type: 'SINGLE_RESOURCE_NOTIFICATION',
      enabled: false
    },
    {
      type: 'SINGLE_RESOURCE_REACTIONS',
      enabled: false
    }
  ]
};

EVT.api({
  url: '/jobs/actions/',
  method: 'POST',
  authorization: operatorApiKey,
  data: job
}).then(console.log);

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.evrythng.com/jobs/actions/Ug3DYH2BscNTDM3Up7H3QCth

Read all Action Jobs

You can retrieve the list of all actions-related jobs, simply do a GET request on the /jobs/actions resource. The response can be paginated.

GET /jobs/actions
Authorization: $OPERATOR_API_KEY

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

const operatorApiKey = '$OPERATOR_API_KEY';

EVT.api({
  url: '/jobs/actions/',
  authorization: operatorApiKey
}).then(console.log);

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

[
  {
    "id": "UXmYq4gp8cNcg6KcDhhWbmHq",
    "createdAt": 1452788331722,
    "updatedAt": 1452788335395,
    "history": [
      {
        "status": "ENQUEUED",
        "timestamp": 1452788331717,
        "terminal": false
      },
      {
        "status": "STARTING",
        "timestamp": 1452788334966,
        "terminal": false
      },
      {
        "status": "EXECUTING",
        "timestamp": 1452788335048,
        "terminal": false
      },
      {
        "status": "COMPLETED",
        "timestamp": 1452788335391,
        "terminal": true
      }
    ],
    "progress": {
      "amountRequested": 1,
      "amountCompleted": 1
    },
    "completedAt": 1452788335391,
    "failedOperationsAmount": 0,
    "type": "ACTION_CREATION",
    "options": [
      {
        "type": "SINGLE_RESOURCE_NOTIFICATION",
        "enabled": false
      },
      {
        "type": "SINGLE_RESOURCE_REACTIONS",
        "enabled": false
      }
    ],
    "payload": {
      "type": "scans"
    },
    "target": "THNGS",
    "input": {
      "type": "LIST",
      "contentType": "EVRYTHNG_IDS",
      "payload": [ "UD3XhknYPcNTgMmdprn3tfqs" ]
    },
    "status": "COMPLETED"
  }
]

Read Action Jobs by ID

You can retrieve an action job document using its ID.

GET /jobs/actions/:actionJobId
Authorization: $OPERATOR_API_KEY

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

const operatorApiKey = '$OPERATOR_API_KEY';
const jobId = 'UGnGDsdqBXsaQ5wRwFRMAyce';

EVT.api({
  url: `/jobs/actions/${jobId}`,
  authorization: operatorApiKey
}).then(console.log);

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

{
  "id": "UXmYq4gp8cNcg6KcDhhWbmHq",
  "createdAt": 1452788331722,
  "updatedAt": 1452788335395,
  "history": [
    {
      "status": "ENQUEUED",
      "timestamp": 1452788331717,
      "terminal": false
    },
    {
      "status": "STARTING",
      "timestamp": 1452788334966,
      "terminal": false
    },
    {
      "status": "EXECUTING",
      "timestamp": 1452788335048,
      "terminal": false
    },
    {
      "status": "COMPLETED",
      "timestamp": 1452788335391,
      "terminal": true
    }
  ],
  "progress": {
    "amountRequested": 1,
    "amountCompleted": 1
  },
  "completedAt": 1452788335391,
  "failedOperationsAmount": 0,
  "type": "ACTION_CREATION",
  "options": [
    {
      "type": "SINGLE_RESOURCE_NOTIFICATION",
      "enabled": false
    },
    {
      "type": "SINGLE_RESOURCE_REACTIONS",
      "enabled": false
    }
  ],
  "payload": {
    "type": "scans"
  },
  "target": "THNGS",
  "input": {
    "type": "LIST",
    "contentType": "EVRYTHNG_IDS",
    "payload": [
      "UD3XhknYPcNTgMmdprn3tfqs"
    ]
  },
  "status": "COMPLETED"
}

Read Action Jobs Logs

When creating actions in bulk, there is a chance that some actions will not be created (e.g. when a Thng cannot be found).

Once a job has completed with errors, you can access the logs of that job to identify the problems that occurred. The logs for a job can be accessed as an array of entries (JobLogEntryDocument objects) as follows:

GET /jobs/actions/:actionJobId/logs
Authorization: $OPERATOR_API_KEY

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

const operatorApiKey = '$OPERATOR_API_KEY';
const jobId = 'UGnGDsdqBXsaQ5wRwFRMAyce';

EVT.api({
  url: `/jobs/actions/${jobId}/logs`,
  authorization: operatorApiKey
}).then(console.log);

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

[
  {
    "jobId": "UXGh7dyGsyNyDMKyDhYfbmMd",
    "payload": {
      "id": "123",
      "type": "EVRYTHNG_IDS"
    },
    "type": "ERROR"
  }
]

JobLogEntryDocument Data Model

Used to detail an error in a job's log.

JobLogEntryDocument = {
  "jobId": Ref,
  "payload": PayloadDocument,
  "type": Enum
}

### Data Fields

jobId - Ref, Read-only
The job ID that generated this entry.
payload - PayloadDocument, Read-only
Identifies which Thng an action could not be created against.
type - Enum, Read-only
The nature of this log. Currently, it can only be ERROR.

Filterable Fields

jobId, type

PayloadDocument Data Model

The PayloadDocument object indicates the Thng against which an action could not be created and can have the following forms, depending on the type:

EVRYTHNG IDs

EvrythngIdDocument implements PayloadDocument = {
  "type": "EVRYTHNG_IDS",
  "id": Ref
}

External IDs

ExternalIdDocument implements PayloadDocument = {
  "type": "EXTERNAL_IDS",
  "key": String,
  "value": Ref
}

Short IDs

ExternalIdDocument implements PayloadDocument = {
  "type": "SHORT_IDS",
  "shortDomain": String,
  "shortId": Ref
}

📘Available Job Types

JobDocument Data Model

JobStatusDocument Data Model

JobProgressDocument Data Model

Action Jobs

ActionJobDocument Data Model

InputDocument Data Model

CreateActionJobDocument Data Model

CreateActionJobInputDocument Data Model

CreateActionJobOptionDocument Data Model

List Input

ListCreateActionJobInputDocument Data Model

File Input

FileCreateActionJobInputDocument Data Model

Create an Action Creation Job

Read all Action Jobs

Read Action Jobs by ID

Read Action Jobs Logs

JobLogEntryDocument Data Model

Filterable Fields

PayloadDocument Data Model

📘
Available Job Types