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


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


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
}