Enterprise Feature
Note
Creating a task is currently only possible through the API. However, existing tasks can be viewed through the Dashboard.
A task is an asynchronous operation that can be performed on a batch to populate it. Possible task types include creating new Thngs or generating lists of Short IDs. The batch must be created first, followed by tasks operated on that batch to populate it with associated resources.
API Status
General Availability:
/batches/:batchId/tasks
/batches/:batchId/tasks/:taskId
Jump To ↓
Types of Task
Create a Fixed Amount Batch Populating Task
Create a File Based Batch Populating Task
Create a List Based Batch Populating Task
Create an Identifiers List Based Batch Populating Task
Create a Short ID Generation Task
Read All Tasks for a Given Batch
Read a Task by ID
Read Task Error Logs
Types of Task
There are currently two main types of tasks, both of which share common fields in their request payloads, but with key differences that are detailed on this page.
-
Batch Populating Task - used to create the Thngs and their redirections.
-
Short ID Generation Task - used to generate short IDs and allows the user to download a CSV file containing those short IDs.
Batch Populating Task
The Batch Populating Task type is used to create a large number of Thngs, with optional redirections, in one request. Each generated Thng conforms to a template provided in the task, with some scope for serialisation depending on the actual type of Batch Populating Task. The available types are:
-
Fixed Amount Batch Populating Task - Create a fixed number of Thngs and redirections.
-
File Based Batch Populating Task - Create Thngs using a remote file of short IDs.
-
List Based Batch Populating Task - Create Thngs using short IDs in the task itself.
-
Identifiers List Based Batch Populating Task - Create Thngs using short IDs in the task itself, and also a serialised list of
identifiersvalues.
Create a Fixed Amount Batch Populating Task
This type of Batch Populating Task generated a fixed integer number of Thngs as specified in the submitted task. Each is shaped according to the Thng template provided, and is allocated a short ID and redirection if also specified.
POST /batches/:batchId/tasks
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
FixedAmountTaskDocument
curl -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X POST 'https://api.evrythng.com/batches/UmNqmfDEBDswtpaaRDs6xHpn/tasks' \
-d '{
"type": "POPULATING",
"outputParameters": {
"type": "CSV",
"columns": [
"SHORT_ID",
"THNG"
]
},
"inputParameters": {
"type": "FIXED_AMOUNT",
"generateThngs": true,
"generateRedirections": true,
"defaultRedirectUrl": "https://google.com",
"thngTemplate": {
"name": "Fixed Amount Task Thng",
"tags": [ "Generated" ]
},
"shortDomain": "tn.gg",
"quantity": 1,
"shortIdTemplate": {
"type": "THNG_ID"
}
}
}'
const batchId = 'UHnXKFfneXsa9KawRFQGyHeq';
const payload = {
type: 'POPULATING',
inputParameters: {
type: 'FIXED_AMOUNT',
generateThngs: true,
generateRedirections: true,
defaultRedirectUrl: 'https://google.com',
thngTemplate: {
name: 'Fixed Amount Task Thng',
tags: ['Generated']
},
shortDomain: 'tn.gg',
quantity: 1,
shortIdTemplate: {
type: 'THNG_ID'
}
}
};
operator.batch(batchId).task()
.create(payload, { fullResponse: true })
.then(res => console.log(`Task created: ${res.headers.location}`));
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.evrythng.com/batches/:batchId/tasks/:taskId
FixedAmountTaskDocument Data Model
The request payload used to create a Fixed Amount Batch Populating Task.
.id (string, read-only)
The ID of this resource.
.type (string, required, one of 'POPULATING')
The type of task to perform.
.batch (string, read-only)
The ID of the batch of this task.
.createdAt (integer, read-only)
Timestamp when the resource was created.
.updatedAt (integer, read-only)
Timestamp when the resource was updated.
.completedAt (integer, read-only)
Time at which the task was completed.
.status (string, read-only, one of 'PENDING', 'EXECUTING', 'EXECUTED', 'CANCELLING', 'FAILED', 'EXECUTED_WITH_FAILURES')
The status of the task.
.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.
.result (TaskResultDocument)
Description of the result of a batch task.
.outputParameters (OutputParametersDocument)
The output format for the task.
.progress (TaskProgressDocument)
Description of the task progress in terms of individual
contributions.
.inputParameters (FixedAmountInputParametersDocument, required)
Specification of the task input parameters for the
`FIXED_AMOUNT` type.
{
"additionalProperties": false,
"type": "object",
"description": "A task for batch creation of Thngs with type `FIXED_AMOUNT`.",
"required": ["type", "inputParameters"],
"properties": {
"id": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of task to perform.",
"enum": ["POPULATING"]
},
"batch": {
"type": "string",
"description": "The ID of the batch of this task.",
"readOnly": true,
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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
},
"completedAt": {
"type": "integer",
"description": "Time at which the task was completed.",
"readOnly": true
},
"status": {
"type": "string",
"description": "The status of the task.",
"enum": ["PENDING", "EXECUTING", "EXECUTED", "CANCELLING", "FAILED", "EXECUTED_WITH_FAILURES"],
"readOnly": true
},
"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
}
}
}
},
"result": {
"additionalProperties": false,
"type": "object",
"description": "Description of the result of a batch task.",
"properties": {
"totalCount": {
"type": "integer",
"description": "The total count of generated resources.",
"readOnly": true
},
"totalThngsCreated": {
"type": "integer",
"description": "The total count of generated Thngs.",
"readOnly": true
},
"totalUrlBindingsCreated": {
"type": "integer",
"description": "The total count of generated redirections.",
"readOnly": true
},
"location": {
"type": "string",
"description": "The URL of the result file.",
"readOnly": true
},
"format": {
"type": "string",
"description": "The type of input or results file.",
"enum": ["CSV", "ZIP"]
},
"headers": {
"type": "object",
"description": "Key-value set of HTTP headers.",
"readOnly": true
},
"error": {
"type": "string",
"description": "The error message describing what went wrong.",
"readOnly": true
},
"failedOperationsAmount": {
"type": "integer",
"description": "Total number of failed operations.",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of result.",
"enum": ["SHORT_ID_GENERATION", "POPULATING", "ERROR"],
"readOnly": true
}
}
},
"outputParameters": {
"additionalProperties": false,
"type": "object",
"description": "The output format for the task.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The output format type.",
"enum": ["CSV"]
},
"columns": {
"type": "array",
"description": "The CSV columns to use. Valid values are 'SHORT_ID' and 'THNG'.",
"items": {
"type": "string",
"enum": ["SHORT_ID", "THNG"]
}
}
}
},
"progress": {
"additionalProperties": false,
"type": "object",
"description": "Description of the task progress in terms of individual contributions.",
"properties": {
"contributions": {
"type": "object",
"description": "Object of keys for each contribution group, with resource counts as the value.",
"readOnly": true
},
"totalAmount": {
"type": "integer",
"description": "The total amount of generated resources so far.",
"readOnly": true
}
}
},
"inputParameters": {
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `FIXED_AMOUNT` type.",
"required": ["type", "generateThngs", "generateRedirections", "defaultRedirectUrl", "thngTemplate", "shortDomain", "quantity", "shortIdTemplate"],
"properties": {
"type": {
"type": "string",
"description": "The FIXED_AMOUNT task type.",
"enum": ["FIXED_AMOUNT"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"defaultRedirectUrl": {
"type": "string",
"description": "The URL for the generated redirections. `{evrythngId}` can substitute the appropriate resource ID."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"shortDomain": {
"type": "string",
"description": "The short domain used for generated redirections."
},
"quantity": {
"type": "integer",
"description": "The number of resources."
},
"shortIdTemplate": {
"type": "object",
"description": "The template of the short ID format. Contains one field 'type' with only one permitted value 'THNG_ID'.",
"properties": {
"type": {
"type": "string",
"description": "The type of template. Can only be 'THNG_ID'",
"enum": ["THNG_ID"]
}
}
}
}
}
},
"x-filterable-fields": ["batch", "status", "type"]
}
{
"id": "UE9DddW7qnDA8rg4rHHxrsFn",
"createdAt": 1475752797109,
"updatedAt": 1475752798198,
"completedAt": 1475752798198,
"batch": "UEtdHPBbmgxypHxWhVKbBbCa",
"type": "POPULATING",
"status": "EXECUTED",
"result": {
"type": "POPULATING",
"failedOperationsAmount": 0,
"location": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/batch-UEtdHPBbmgxypHxWhVKbBbCa-task-UE9gAdf7mWeBKtbAxdkAhbMk452646197797282204~57f6335d2b888118.zip",
"format": "CSV",
"totalThngsCreated": 10,
"totalUrlBindingsCreated": 10,
"totalCount": 20
},
"inputParameters": {
"generateThngs": true,
"generateRedirections": true,
"shortDomain": "tn.gg",
"defaultRedirectUrl": "https://developers.evrythng.com",
"thngTemplate": {
"name": "Batch Thng",
"description": "A Thng born from a task on a batch"
},
"type": "FIXED_AMOUNT",
"quantity": 10,
"shortIdTemplate": {
"type": "THNG_ID"
}
},
"progress": {
"contributions": {
"Uh9XAAWN9nerWHAfC2x4Cbrg": {
"urlBindings": 10,
"thngs": 10,
"failedUrlBindings": 0,
"failedThngs": 0
}
},
"totalAmount": 20
}
}
See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument
FixedAmountInputParametersDocument Data Model
The input parameters that determine the behavior of the Fixed Amount Batch Populating Task.
.type (string, required, one of 'FIXED_AMOUNT')
The FIXED_AMOUNT task type.
.generateThngs (boolean, required)
Whether Thngs will be created as part of the task.
.generateRedirections (boolean, required)
Whether redirections will be created as part of the task.
.defaultRedirectUrl (string, required)
The URL for the generated redirections. `{evrythngId}` can
substitute the appropriate resource ID.
.thngTemplate (ThngDocument, required)
An object representing a Thng.
.shortDomain (string, required)
The short domain used for generated redirections.
.quantity (integer, required)
The number of resources.
.shortIdTemplate (ShortIdTemplateField, required)
The template of the short ID format. Contains one field
'type' with only one permitted value 'THNG_ID'.
{
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `FIXED_AMOUNT` type.",
"required": ["type", "generateThngs", "generateRedirections", "defaultRedirectUrl", "thngTemplate", "shortDomain", "quantity", "shortIdTemplate"],
"properties": {
"type": {
"type": "string",
"description": "The FIXED_AMOUNT task type.",
"enum": ["FIXED_AMOUNT"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"defaultRedirectUrl": {
"type": "string",
"description": "The URL for the generated redirections. `{evrythngId}` can substitute the appropriate resource ID."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"shortDomain": {
"type": "string",
"description": "The short domain used for generated redirections."
},
"quantity": {
"type": "integer",
"description": "The number of resources."
},
"shortIdTemplate": {
"type": "object",
"description": "The template of the short ID format. Contains one field 'type' with only one permitted value 'THNG_ID'.",
"properties": {
"type": {
"type": "string",
"description": "The type of template. Can only be 'THNG_ID'",
"enum": ["THNG_ID"]
}
}
}
}
}
See also: ThngDocument
Create a File Based Batch Populating Task
This type of task is used to create Thngs using an external file (a list of of short IDs) as the input. A Thng will be generated according to the thngTemplate provided for each ID line in the file.
POST /batches/:batchId/tasks
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
FileBasedTaskDocument
curl -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X POST 'https://api.evrythng.com/batches/UmNqmfDEBDswtpaaRDs6xHpn/tasks' \
-d '{
"type": "POPULATING",
"outputParameters": {
"type": "CSV",
"columns": [
"SHORT_ID",
"THNG"
]
},
"inputParameters": {
"type": "FILE_BASED",
"generateThngs": true,
"generateRedirections": true,
"defaultRedirectUrl": "https://google.com",
"thngTemplate": {
"name": "File Based Task Thng",
"tags": [
"Generated"
]
},
"shortDomain": "tn.gg",
"shortIdTemplate": {
"type": "THNG_ID"
},
"location": "https://evtcdn_02.s3.amazonaws.com/2/uf/UmFVekRaVXsa9pRwwYaRDmer/short_ids.csv",
"format": "CSV",
"headers": {
"Content-Type": "text/csv"
}
}
}'
const batchId = 'UHnXKFfneXsa9KawRFQGyHeq';
const payload = {
type: 'POPULATING',
inputParameters: {
type: 'FILE_BASED',
generateThngs: true,
generateRedirections: true,
defaultRedirectUrl: 'https://google.com',
thngTemplate: {
name: 'File Based Task Thng',
tags: ['Generated']
},
shortDomain: 'tn.gg',
shortIdTemplate: {
type: 'THNG_ID'
},
location: 'https://evtcdn_02.s3.amazonaws.com/2/uf/UmFVekRaVXsa9pRwwYaRDmer/short_ids.csv',
format: 'CSV',
headers: {
'Content-Type': 'text/csv'
}
}
};
operator.batch(batchId).task()
.create(payload, { fullResponse: true })
.then(res => console.log(`Task created: ${res.headers.location}`));
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.evrythng.com/batches/:batchId/tasks/:taskId
FileBasedTaskDocument Data Model
The request payload used to create a File Based Batch Populating Task.
.id (string, read-only)
The ID of this resource.
.type (string, required, one of 'POPULATING')
The type of task to perform.
.batch (string, read-only)
The ID of the batch of this task.
.createdAt (integer, read-only)
Timestamp when the resource was created.
.updatedAt (integer, read-only)
Timestamp when the resource was updated.
.completedAt (integer, read-only)
Time at which the task was completed.
.status (string, read-only, one of 'PENDING', 'EXECUTING', 'EXECUTED', 'CANCELLING', 'FAILED', 'EXECUTED_WITH_FAILURES')
The status of the task.
.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.
.result (TaskResultDocument)
Description of the result of a batch task.
.outputParameters (OutputParametersDocument)
The output format for the task.
.progress (TaskProgressDocument)
Description of the task progress in terms of individual
contributions.
.inputParameters (FileBasedInputParametersDocument, required)
Specification of the task input parameters for the
`FILE_BASED` type.
{
"additionalProperties": false,
"type": "object",
"description": "A task for batch creation of Thngs with type `FILE_BASED`.",
"required": ["type", "inputParameters"],
"properties": {
"id": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of task to perform.",
"enum": ["POPULATING"]
},
"batch": {
"type": "string",
"description": "The ID of the batch of this task.",
"readOnly": true,
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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
},
"completedAt": {
"type": "integer",
"description": "Time at which the task was completed.",
"readOnly": true
},
"status": {
"type": "string",
"description": "The status of the task.",
"enum": ["PENDING", "EXECUTING", "EXECUTED", "CANCELLING", "FAILED", "EXECUTED_WITH_FAILURES"],
"readOnly": true
},
"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
}
}
}
},
"result": {
"additionalProperties": false,
"type": "object",
"description": "Description of the result of a batch task.",
"properties": {
"totalCount": {
"type": "integer",
"description": "The total count of generated resources.",
"readOnly": true
},
"totalThngsCreated": {
"type": "integer",
"description": "The total count of generated Thngs.",
"readOnly": true
},
"totalUrlBindingsCreated": {
"type": "integer",
"description": "The total count of generated redirections.",
"readOnly": true
},
"location": {
"type": "string",
"description": "The URL of the result file.",
"readOnly": true
},
"format": {
"type": "string",
"description": "The type of input or results file.",
"enum": ["CSV", "ZIP"]
},
"headers": {
"type": "object",
"description": "Key-value set of HTTP headers.",
"readOnly": true
},
"error": {
"type": "string",
"description": "The error message describing what went wrong.",
"readOnly": true
},
"failedOperationsAmount": {
"type": "integer",
"description": "Total number of failed operations.",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of result.",
"enum": ["SHORT_ID_GENERATION", "POPULATING", "ERROR"],
"readOnly": true
}
}
},
"outputParameters": {
"additionalProperties": false,
"type": "object",
"description": "The output format for the task.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The output format type.",
"enum": ["CSV"]
},
"columns": {
"type": "array",
"description": "The CSV columns to use. Valid values are 'SHORT_ID' and 'THNG'.",
"items": {
"type": "string",
"enum": ["SHORT_ID", "THNG"]
}
}
}
},
"progress": {
"additionalProperties": false,
"type": "object",
"description": "Description of the task progress in terms of individual contributions.",
"properties": {
"contributions": {
"type": "object",
"description": "Object of keys for each contribution group, with resource counts as the value.",
"readOnly": true
},
"totalAmount": {
"type": "integer",
"description": "The total amount of generated resources so far.",
"readOnly": true
}
}
},
"inputParameters": {
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `FILE_BASED` type.",
"required": ["type", "generateThngs", "generateRedirections", "defaultRedirectUrl", "thngTemplate", "shortDomain", "location", "format"],
"properties": {
"type": {
"type": "string",
"description": "The FILE_BASED task type.",
"enum": ["FILE_BASED"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"defaultRedirectUrl": {
"type": "string",
"description": "The URL for the generated redirections. `{evrythngId}` can substitute the appropriate resource ID."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"shortDomain": {
"type": "string",
"description": "The short domain used for generated redirections."
},
"location": {
"type": "string",
"description": "The URL of the input file containing the list of short IDs. This must be a Files API uploaded URL."
},
"format": {
"type": "string",
"description": "The format of the input file referred to by `location`.",
"enum": ["CSV", "ZIP"]
},
"headers": {
"type": "object",
"description": "Key-value object of HTTP headers required when requesting the input file."
}
}
}
},
"x-filterable-fields": ["batch", "status", "type"]
}
{
"id": "UHRPQK8DNgab2awawFwgtkrs",
"createdAt": 1510931430808,
"updatedAt": 1510931434071,
"completedAt": 1510931434071,
"batch": "U3hYexgsfy9HQtRwRhTgHqpr",
"type": "POPULATING",
"status": "EXECUTED",
"result": {
"type": "POPULATING",
"failedOperationsAmount": 0,
"location": "https://engine-files.s3.amazonaws.com/UGYYcfmsCy9nQtRwwYcgnfKb/batch-U3hYexgsfy9HQtRwRhTgHqpr-task-Una8tKsXqGPhYqaaRE7PCaSg5607405604537977227~5a0efbe958f1e0f4.zip",
"format": "CSV",
"totalThngsCreated": 10,
"totalUrlBindingsCreated": 10,
"totalCount": 20
},
"inputParameters": {
"generateThngs": true,
"generateRedirections": true,
"shortDomain": "t.tn.gg",
"defaultRedirectUrl": "https://google.com?thng={evrythngId}",
"thngTemplate": {
"name": "Example Thng"
},
"type": "FILE_BASED",
"location": "https://engine-files.s3.amazonaws.com/UGYYcfmsCy9nQtRwwYcgnfKb/batch-U3hYexgsfy9HQtRwRhTgHqpr-task-UnwP9KWK7gwSkRaRakag8ypn1892543139253365199~5a0efb5d62ceba84.zip",
"format": "ZIP"
},
"progress": {
"contributions": {
"UHasQKs3MG8hhMwRwYrPCwbp": {
"urlBindings": 10,
"thngs": 10,
"failedUrlBindings": 0,
"failedThngs": 0
}
},
"totalAmount": 20
}
}
See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument
FileBasedInputParametersDocument Data Model
The input parameters that determine the behavior of a File Based Batch Populating Task.
.type (string, required, one of 'FILE_BASED')
The FILE_BASED task type.
.generateThngs (boolean, required)
Whether Thngs will be created as part of the task.
.generateRedirections (boolean, required)
Whether redirections will be created as part of the task.
.defaultRedirectUrl (string, required)
The URL for the generated redirections. `{evrythngId}` can
substitute the appropriate resource ID.
.thngTemplate (ThngDocument, required)
An object representing a Thng.
.shortDomain (string, required)
The short domain used for generated redirections.
.location (string, required)
The URL of the input file containing the list of short IDs.
This must be a Files API uploaded URL.
.format (string, required, one of 'CSV', 'ZIP')
The format of the input file referred to by `location`.
.headers (object)
Key-value object of HTTP headers required when requesting
the input file.
{
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `FILE_BASED` type.",
"required": ["type", "generateThngs", "generateRedirections", "defaultRedirectUrl", "thngTemplate", "shortDomain", "location", "format"],
"properties": {
"type": {
"type": "string",
"description": "The FILE_BASED task type.",
"enum": ["FILE_BASED"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"defaultRedirectUrl": {
"type": "string",
"description": "The URL for the generated redirections. `{evrythngId}` can substitute the appropriate resource ID."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"shortDomain": {
"type": "string",
"description": "The short domain used for generated redirections."
},
"location": {
"type": "string",
"description": "The URL of the input file containing the list of short IDs. This must be a Files API uploaded URL."
},
"format": {
"type": "string",
"description": "The format of the input file referred to by `location`.",
"enum": ["CSV", "ZIP"]
},
"headers": {
"type": "object",
"description": "Key-value object of HTTP headers required when requesting the input file."
}
}
}
See also: ThngDocument
Create a List Based Batch Populating Task
This type of task creates a Thng shaped by the thngTemplate specified for each shortId value included in the request inputData field.
POST /batches/:batchId/tasks
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
ListBasedTaskDocument
curl -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X POST 'https://api.evrythng.com/batches/UmNqmfDEBDswtpaaRDs6xHpn/tasks' \
-d '{
"type": "POPULATING",
"outputParameters": {
"type": "CSV",
"columns": [ "SHORT_ID", "THNG" ]
},
"inputParameters": {
"type": "LIST_BASED",
"generateThngs": true,
"generateRedirections": true,
"defaultRedirectUrl": "https://google.com",
"thngTemplate": {
"name": "List Based Task Thng",
"tags": [ "Generated" ]
},
"shortDomain": "tn.gg",
"shortIdTemplate": {
"type": "THNG_ID"
},
"inputData": [
{ "shortId": "IDF20170001" },
{ "shortId": "IDF20170002" },
{ "shortId": "IDF20170003" },
{ "shortId": "IDF20170004" },
{ "shortId": "IDF20170005" }
]
}
}'
const batchId = 'UHnXKFfneXsa9KawRFQGyHeq';
const payload = {
type: 'POPULATING',
inputParameters: {
type: 'LIST_BASED',
generateThngs: true,
generateRedirections: true,
defaultRedirectUrl: 'https://google.com',
thngTemplate: {
name: 'List Based Task Thng',
tags: ['Generated']
},
shortDomain: 'tn.gg',
shortIdTemplate: {
type: 'THNG_ID'
},
inputData: [
{ shortId: 'IDF20170001' },
{ shortId: 'IDF20170002' },
{ shortId: 'IDF20170003' },
{ shortId: 'IDF20170004' },
{ shortId: 'IDF20170005' },
// ...
]
}
};
operator.batch(batchId).task()
.create(payload, { fullResponse: true })
.then(res => console.log(`Task created: ${res.headers.location}`));
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.evrythng.com/batches/:batchId/tasks/:taskId
ListBasedTaskDocument Data Model
The request payload used to create a List Based Batch Populating Task.
.id (string, read-only)
The ID of this resource.
.type (string, required, one of 'POPULATING')
The type of task to perform.
.batch (string, read-only)
The ID of the batch of this task.
.createdAt (integer, read-only)
Timestamp when the resource was created.
.updatedAt (integer, read-only)
Timestamp when the resource was updated.
.completedAt (integer, read-only)
Time at which the task was completed.
.status (string, read-only, one of 'PENDING', 'EXECUTING', 'EXECUTED', 'CANCELLING', 'FAILED', 'EXECUTED_WITH_FAILURES')
The status of the task.
.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.
.result (TaskResultDocument)
Description of the result of a batch task.
.outputParameters (OutputParametersDocument)
The output format for the task.
.progress (TaskProgressDocument)
Description of the task progress in terms of individual
contributions.
.inputParameters (ListBasedInputParametersDocument, required)
Specification of the task input parameters for the
`LIST_BASED` type.
{
"additionalProperties": false,
"type": "object",
"description": "A task for batch creation of Thngs with type `LIST_BASED`.",
"required": ["type", "inputParameters"],
"properties": {
"id": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of task to perform.",
"enum": ["POPULATING"]
},
"batch": {
"type": "string",
"description": "The ID of the batch of this task.",
"readOnly": true,
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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
},
"completedAt": {
"type": "integer",
"description": "Time at which the task was completed.",
"readOnly": true
},
"status": {
"type": "string",
"description": "The status of the task.",
"enum": ["PENDING", "EXECUTING", "EXECUTED", "CANCELLING", "FAILED", "EXECUTED_WITH_FAILURES"],
"readOnly": true
},
"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
}
}
}
},
"result": {
"additionalProperties": false,
"type": "object",
"description": "Description of the result of a batch task.",
"properties": {
"totalCount": {
"type": "integer",
"description": "The total count of generated resources.",
"readOnly": true
},
"totalThngsCreated": {
"type": "integer",
"description": "The total count of generated Thngs.",
"readOnly": true
},
"totalUrlBindingsCreated": {
"type": "integer",
"description": "The total count of generated redirections.",
"readOnly": true
},
"location": {
"type": "string",
"description": "The URL of the result file.",
"readOnly": true
},
"format": {
"type": "string",
"description": "The type of input or results file.",
"enum": ["CSV", "ZIP"]
},
"headers": {
"type": "object",
"description": "Key-value set of HTTP headers.",
"readOnly": true
},
"error": {
"type": "string",
"description": "The error message describing what went wrong.",
"readOnly": true
},
"failedOperationsAmount": {
"type": "integer",
"description": "Total number of failed operations.",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of result.",
"enum": ["SHORT_ID_GENERATION", "POPULATING", "ERROR"],
"readOnly": true
}
}
},
"outputParameters": {
"additionalProperties": false,
"type": "object",
"description": "The output format for the task.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The output format type.",
"enum": ["CSV"]
},
"columns": {
"type": "array",
"description": "The CSV columns to use. Valid values are 'SHORT_ID' and 'THNG'.",
"items": {
"type": "string",
"enum": ["SHORT_ID", "THNG"]
}
}
}
},
"progress": {
"additionalProperties": false,
"type": "object",
"description": "Description of the task progress in terms of individual contributions.",
"properties": {
"contributions": {
"type": "object",
"description": "Object of keys for each contribution group, with resource counts as the value.",
"readOnly": true
},
"totalAmount": {
"type": "integer",
"description": "The total amount of generated resources so far.",
"readOnly": true
}
}
},
"inputParameters": {
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `LIST_BASED` type.",
"required": ["type", "generateThngs", "generateRedirections", "defaultRedirectUrl", "thngTemplate", "shortDomain", "inputData"],
"properties": {
"type": {
"type": "string",
"description": "The LIST_BASED task type.",
"enum": ["LIST_BASED"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"defaultRedirectUrl": {
"type": "string",
"description": "The URL for the generated redirections. `{evrythngId}` can substitute the appropriate resource ID."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"shortDomain": {
"type": "string",
"description": "The short domain used for generated redirections."
},
"inputData": {
"type": "array",
"description": "List of objects detailing the short IDs to use",
"items": {
"additionalProperties": false,
"type": "object",
"description": "Container for a task generation short ID.",
"properties": {
"shortId": {
"type": "string",
"description": "The short ID for the redirection."
}
}
},
"example": [
{ "shortId": "serial1" },
{ "shortId": "serial2" },
{ "shortId": "serial3" }
]
}
}
}
},
"x-filterable-fields": ["batch", "status", "type"]
}
{
"id": "UHaPtMHHBDPaQpawwhCtKcKf",
"createdAt": 1510931626606,
"updatedAt": 1510931627149,
"completedAt": 1510931627149,
"batch": "U4asNCTB6GPEYMaaRYCwwBmd",
"type": "POPULATING",
"status": "EXECUTED",
"result": {
"type": "POPULATING",
"failedOperationsAmount": 0,
"location": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/batch-U4asNCTB6GPEYMaaRYCwwBmd-task-Unas9q4n69teYPRwakCBwbRf503859743411498618~5a0efcaaec1bf15d.zip",
"format": "CSV",
"totalThngsCreated": 2,
"totalUrlBindingsCreated": 2,
"totalCount": 4
},
"inputParameters": {
"generateThngs": true,
"generateRedirections": true,
"shortDomain": "tn.gg",
"defaultRedirectUrl": "https://google.com?thng={evrythngId}",
"thngTemplate": {
"name": "Example Thng"
},
"type": "LIST_BASED",
"inputData": [
{
"shortId": "23kj3k2"
},
{
"shortId": "4j3k2h4"
}
]
},
"progress": {
"contributions": {
"UHas9MHHq9QBh8wawkWewbah": {
"urlBindings": 2,
"thngs": 2,
"failedUrlBindings": 0,
"failedThngs": 0
}
},
"totalAmount": 4
}
}
See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument
ListBasedInputParametersDocument Data Model
The input parameters that determine the behavior of the List Based Batch Populating Task
.type (string, required, one of 'LIST_BASED')
The LIST_BASED task type.
.generateThngs (boolean, required)
Whether Thngs will be created as part of the task.
.generateRedirections (boolean, required)
Whether redirections will be created as part of the task.
.defaultRedirectUrl (string, required)
The URL for the generated redirections. `{evrythngId}` can
substitute the appropriate resource ID.
.thngTemplate (ThngDocument, required)
An object representing a Thng.
.shortDomain (string, required)
The short domain used for generated redirections.
.inputData (array of RedirectionResourceDocument, required)
List of objects detailing the short IDs to use
{
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `LIST_BASED` type.",
"required": ["type", "generateThngs", "generateRedirections", "defaultRedirectUrl", "thngTemplate", "shortDomain", "inputData"],
"properties": {
"type": {
"type": "string",
"description": "The LIST_BASED task type.",
"enum": ["LIST_BASED"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"defaultRedirectUrl": {
"type": "string",
"description": "The URL for the generated redirections. `{evrythngId}` can substitute the appropriate resource ID."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"shortDomain": {
"type": "string",
"description": "The short domain used for generated redirections."
},
"inputData": {
"type": "array",
"description": "List of objects detailing the short IDs to use",
"items": {
"additionalProperties": false,
"type": "object",
"description": "Container for a task generation short ID.",
"properties": {
"shortId": {
"type": "string",
"description": "The short ID for the redirection."
}
}
},
"example": [
{ "shortId": "serial1" },
{ "shortId": "serial2" },
{ "shortId": "serial3" }
]
}
}
}
See also: ThngDocument, RedirectionResourceDocument
Create an Identifiers List Based Batch Populating Task
This type of task generated Thngs shaped by the thngTemplate similar to the List Based Batch Populating Task, but with one key difference - the developer may specify a list of key-value values for a single identifiers key.
Note
For this task type,
generateRedirectionsmust always befalse.
POST /batches/:batchId/tasks
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
IdentifiersListBasedTaskDocument
curl -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X POST 'https://api.evrythng.com/batches/UmNqmfDEBDswtpaaRDs6xHpn/tasks' \
-d '{
"type": "POPULATING",
"outputParameters": {
"type": "CSV",
"columns": [ "THNG" ]
},
"inputParameters": {
"type": "IDENTIFIERS_LIST_BASED",
"generateThngs": true,
"generateRedirections": false,
"thngTemplate": {
"name": "Identifiers List Based Task Thng",
"tags": [ "Generated" ]
},
"customIdentifier": {
"key": "CustomCounter",
"values": [ "1", "2", "3", "4", "5" ]
}
}
}'
const batchId = 'UHnXKFfneXsa9KawRFQGyHeq';
const payload = {
type: 'POPULATING',
inputParameters: {
type: 'IDENTIFIERS_LIST_BASED',
generateThngs: true,
generateRedirections: false,
thngTemplate: {
name: 'Identifiers List Based Task Thng',
tags: ['Generated']
},
customIdentifier: {
key: 'CustomCounter',
values: ['1', '2', '3', '4', '5']
}
}
};
operator.batch(batchId).task()
.create(payload, { fullResponse: true })
.then(res => console.log(`Task created: ${res.headers.location}`));
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.evrythng.com/batches/:batchId/tasks/:taskId
IdentifiersListBasedTaskDocument Data Model
The request payload used to create a Identifiers List Based Batch Populating Task.
.id (string, read-only)
The ID of this resource.
.type (string, required, one of 'POPULATING')
The type of task to perform.
.batch (string, read-only)
The ID of the batch of this task.
.createdAt (integer, read-only)
Timestamp when the resource was created.
.updatedAt (integer, read-only)
Timestamp when the resource was updated.
.completedAt (integer, read-only)
Time at which the task was completed.
.status (string, read-only, one of 'PENDING', 'EXECUTING', 'EXECUTED', 'CANCELLING', 'FAILED', 'EXECUTED_WITH_FAILURES')
The status of the task.
.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.
.result (TaskResultDocument)
Description of the result of a batch task.
.outputParameters (OutputParametersDocument)
The output format for the task.
.progress (TaskProgressDocument)
Description of the task progress in terms of individual
contributions.
.inputParameters (IdentifiersListBasedInputParametersDocument, required)
Specification of the task input parameters for the
`IDENTIFIERS_LIST_BASED` type.
{
"additionalProperties": false,
"type": "object",
"description": "A task for batch creation of Thngs with type `IDENTIFIERS_LIST_BASED`.",
"required": ["type", "inputParameters"],
"properties": {
"id": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of task to perform.",
"enum": ["POPULATING"]
},
"batch": {
"type": "string",
"description": "The ID of the batch of this task.",
"readOnly": true,
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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
},
"completedAt": {
"type": "integer",
"description": "Time at which the task was completed.",
"readOnly": true
},
"status": {
"type": "string",
"description": "The status of the task.",
"enum": ["PENDING", "EXECUTING", "EXECUTED", "CANCELLING", "FAILED", "EXECUTED_WITH_FAILURES"],
"readOnly": true
},
"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
}
}
}
},
"result": {
"additionalProperties": false,
"type": "object",
"description": "Description of the result of a batch task.",
"properties": {
"totalCount": {
"type": "integer",
"description": "The total count of generated resources.",
"readOnly": true
},
"totalThngsCreated": {
"type": "integer",
"description": "The total count of generated Thngs.",
"readOnly": true
},
"totalUrlBindingsCreated": {
"type": "integer",
"description": "The total count of generated redirections.",
"readOnly": true
},
"location": {
"type": "string",
"description": "The URL of the result file.",
"readOnly": true
},
"format": {
"type": "string",
"description": "The type of input or results file.",
"enum": ["CSV", "ZIP"]
},
"headers": {
"type": "object",
"description": "Key-value set of HTTP headers.",
"readOnly": true
},
"error": {
"type": "string",
"description": "The error message describing what went wrong.",
"readOnly": true
},
"failedOperationsAmount": {
"type": "integer",
"description": "Total number of failed operations.",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of result.",
"enum": ["SHORT_ID_GENERATION", "POPULATING", "ERROR"],
"readOnly": true
}
}
},
"outputParameters": {
"additionalProperties": false,
"type": "object",
"description": "The output format for the task.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The output format type.",
"enum": ["CSV"]
},
"columns": {
"type": "array",
"description": "The CSV columns to use. Valid values are 'SHORT_ID' and 'THNG'.",
"items": {
"type": "string",
"enum": ["SHORT_ID", "THNG"]
}
}
}
},
"progress": {
"additionalProperties": false,
"type": "object",
"description": "Description of the task progress in terms of individual contributions.",
"properties": {
"contributions": {
"type": "object",
"description": "Object of keys for each contribution group, with resource counts as the value.",
"readOnly": true
},
"totalAmount": {
"type": "integer",
"description": "The total amount of generated resources so far.",
"readOnly": true
}
}
},
"inputParameters": {
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `IDENTIFIERS_LIST_BASED` type.",
"required": ["type", "generateThngs", "generateRedirections", "thngTemplate", "customIdentifier"],
"properties": {
"type": {
"type": "string",
"description": "The IDENTIFIERS_LIST_BASED task type.",
"enum": ["IDENTIFIERS_LIST_BASED"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"customIdentifier": {
"additionalProperties": false,
"type": "object",
"description": "Object describing the custom identifier values for a single key.",
"properties": {
"key": {
"type": "string",
"description": "The custom identifier key."
},
"values": {
"type": "array",
"description": "The array of custom identifier values.",
"items": { "type": "string" }
}
}
}
}
}
},
"x-filterable-fields": ["batch", "status", "type"]
}
{
"id": "UHaP9NxgMG8hYqwaam9MttGe",
"createdAt": 1510931734392,
"updatedAt": 1510931734610,
"completedAt": 1510931734610,
"batch": "U4asNCTB6GPEYMaaRYCwwBmd",
"type": "POPULATING",
"status": "EXECUTED",
"result": {
"type": "POPULATING",
"failedOperationsAmount": 0,
"location": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/batch-U4asNCTB6GPEYMaaRYCwwBmd-task-UnRPQrSXq9teE8awwkHDCGrk1215713290742790514~5a0efd16fc68ec5a.zip",
"format": "CSV",
"totalThngsCreated": 5,
"totalUrlBindingsCreated": 0,
"totalCount": 5
},
"inputParameters": {
"generateThngs": true,
"generateRedirections": false,
"thngTemplate": {
"name": "Example Thng"
},
"type": "IDENTIFIERS_LIST_BASED",
"customIdentifier": {
"key": "counter",
"values": [
"1",
"2",
"3",
"4",
"5"
]
}
},
"progress": {
"contributions": {
"Unwst7xDMQQVEswaaFWeRbWa": {
"urlBindings": 0,
"thngs": 5,
"failedUrlBindings": 0,
"failedThngs": 0
}
},
"totalAmount": 5
}
}
See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument
IdentifiersListBasedInputParametersDocument Data Model
The input parameters that determine the behavior of the Identifiers List Based Batch Populating Task.
.type (string, required, one of 'IDENTIFIERS_LIST_BASED')
The IDENTIFIERS_LIST_BASED task type.
.generateThngs (boolean, required)
Whether Thngs will be created as part of the task.
.generateRedirections (boolean, required)
Whether redirections will be created as part of the task.
.thngTemplate (ThngDocument, required)
An object representing a Thng.
.customIdentifier (CustomIdentifierDocument, required)
Object describing the custom identifier values for a single
key.
{
"additionalProperties": false,
"type": "object",
"description": "Specification of the task input parameters for the `IDENTIFIERS_LIST_BASED` type.",
"required": ["type", "generateThngs", "generateRedirections", "thngTemplate", "customIdentifier"],
"properties": {
"type": {
"type": "string",
"description": "The IDENTIFIERS_LIST_BASED task type.",
"enum": ["IDENTIFIERS_LIST_BASED"]
},
"generateThngs": {
"type": "boolean",
"description": "Whether Thngs will be created as part of the task."
},
"generateRedirections": {
"type": "boolean",
"description": "Whether redirections will be created as part of the task."
},
"thngTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a Thng.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Friendly name of this resource."
},
"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
},
"activatedAt": {
"type": "integer",
"description": "Timestamp when the Thng was activated.",
"readOnly": true
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"customFields": {
"type": "object",
"description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
},
"product": {
"type": "string",
"description": "The Platform ID of a product this Thng is a class of.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"location": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a location. Either 'position' or 'place' us required.",
"properties": {
"position": {
"type": "object",
"description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
"required": ["type", "coordinates"],
"properties": {
"type": {
"type": "string",
"description": "The type of the point.",
"enum": ["Point"]
},
"coordinates": {
"type": "array",
"description": "The point coordinates",
"items": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"timestamp": {
"type": "integer",
"description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
"readOnly": true
},
"longitude": {
"type": "number",
"description": "The longitude."
},
"latitude": {
"type": "number",
"description": "The latitude."
},
"place": {
"type": "string",
"description": "The place ID.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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": ["timestamp"]
},
"properties": {
"type": "object",
"description": "A JSON object with key-value pairs describing properties of the Thng.",
"readOnly": true
},
"collections": {
"description": "An array of collection IDs of any collections this Thng belongs to.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
}
},
"createdByTask": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"batch": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"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": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
},
"customIdentifier": {
"additionalProperties": false,
"type": "object",
"description": "Object describing the custom identifier values for a single key.",
"properties": {
"key": {
"type": "string",
"description": "The custom identifier key."
},
"values": {
"type": "array",
"description": "The array of custom identifier values.",
"items": { "type": "string" }
}
}
}
}
}
See also: ThngDocument
CustomIdentifierDocument Data Model
.key (string, required)
The custom identifier key.
.values (array of string, required)
The array of custom identifier values.
{
"type": "object",
"description": "Object describing the custom identifier values for a single key.",
"properties": {
"key": {
"type": "string",
"description": "The custom identifier key."
},
"values": {
"type": "array",
"description": "The array of custom identifier values.",
"items": { "type": "string" }
}
}
}
Short ID Generation Task
A Short ID Generation Task is used to generate large lists of short IDs according to a template and enumeration schema. The output is a zipped CSV file containing all the generated IDs. Note that this process does not create any Thngs or redirections - only the IDs are generated for use later on.
There are two types of Short ID Generation Task, chosen with the type parameter:
-
PSEUDO_RANDOM- Generate IDs with a predefined prefix and suffix, but with a randomised section between. -
SEQUENTIAL- Generate IDs with a predefined prefix and suffix, but with a sequential set of combinations for the middle section.
Create a Short ID Generation Task
POST /batches/:batchId/tasks
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
ShortIdGenerationTaskDocument
curl -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X POST 'https://api.evrythng.com/batches/Um9nsBgqBDsRt5aaaEMtrcse/tasks' \
-d '{
"type": "SHORT_ID_GENERATION",
"inputParameters": {
"quantity": 10,
"shortIdTemplate": {
"type": "PSEUDO_RANDOM",
"length": 24,
"padding": "ZERO",
"prefix": "HF",
"suffix": "2113",
"separator": "_"
}
}
}'
const batchId = 'U2EBHMxdAh6MTrSh4t26NqUf';
const payload = {
type: 'SHORT_ID_GENERATION',
inputParameters: {
quantity: 10,
shortIdTemplate: {
type: 'PSEUDO_RANDOM',
length: 32,
prefix: 'HF',
suffix: '2113',
separator: '-',
}
}
};
operator.batch(batchId).task()
.create(payload, { fullResponse: true })
.then(res => console.log(`Task created: ${res.headers.location}`));
HTTP/1.1 202 Accepted
Content-Type: application/json,
Location: https://api.evrythng.com/batches/:batchId/tasks/:taskId
ShortIdGenerationTaskDocument Data Model
.id (string, read-only)
The ID of this resource.
.type (string, required, one of 'SHORT_ID_GENERATION')
The type of task to perform.
.batch (string, read-only)
The ID of the batch of this task.
.createdAt (integer, read-only)
Timestamp when the resource was created.
.updatedAt (integer, read-only)
Timestamp when the resource was updated.
.completedAt (integer, read-only)
Time at which the task was completed.
.status (string, read-only, one of 'PENDING', 'EXECUTING', 'EXECUTED', 'CANCELLING', 'FAILED', 'EXECUTED_WITH_FAILURES')
The status of the task.
.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.
.result (TaskResultDocument)
Description of the result of a batch task.
.inputParameters (ShortIdGenerationInputParametersDocument, required)
Input parameters for a Short ID Generation Task.
{
"additionalProperties": false,
"type": "object",
"description": "A task for batch creation of short IDs.",
"required": ["type", "inputParameters"],
"properties": {
"id": {
"type": "string",
"description": "The ID of this resource.",
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of task to perform.",
"enum": ["SHORT_ID_GENERATION"]
},
"batch": {
"type": "string",
"description": "The ID of the batch of this task.",
"readOnly": true,
"pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
},
"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
},
"completedAt": {
"type": "integer",
"description": "Time at which the task was completed.",
"readOnly": true
},
"status": {
"type": "string",
"description": "The status of the task.",
"enum": ["PENDING", "EXECUTING", "EXECUTED", "CANCELLING", "FAILED", "EXECUTED_WITH_FAILURES"],
"readOnly": true
},
"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
}
}
}
},
"result": {
"additionalProperties": false,
"type": "object",
"description": "Description of the result of a batch task.",
"properties": {
"totalCount": {
"type": "integer",
"description": "The total count of generated resources.",
"readOnly": true
},
"totalThngsCreated": {
"type": "integer",
"description": "The total count of generated Thngs.",
"readOnly": true
},
"totalUrlBindingsCreated": {
"type": "integer",
"description": "The total count of generated redirections.",
"readOnly": true
},
"location": {
"type": "string",
"description": "The URL of the result file.",
"readOnly": true
},
"format": {
"type": "string",
"description": "The type of input or results file.",
"enum": ["CSV", "ZIP"]
},
"headers": {
"type": "object",
"description": "Key-value set of HTTP headers.",
"readOnly": true
},
"error": {
"type": "string",
"description": "The error message describing what went wrong.",
"readOnly": true
},
"failedOperationsAmount": {
"type": "integer",
"description": "Total number of failed operations.",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of result.",
"enum": ["SHORT_ID_GENERATION", "POPULATING", "ERROR"],
"readOnly": true
}
}
},
"inputParameters": {
"additionalProperties": false,
"type": "object",
"description": "Input parameters for a Short ID Generation Task.",
"required": ["quantity", "shortIdTemplate"],
"properties": {
"quantity": {
"type": "integer",
"description": "Amount of short IDs to generate."
},
"shortIdTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a short ID generation task on a batch.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The type of ShortIdTemplateDocument.",
"enum": ["SEQUENTIAL", "PSEUDO_RANDOM"]
},
"length": {
"type": "integer",
"description": "Full length of the short ID. Including separators, prefix, and suffix."
},
"start": {
"type": "integer",
"description": "Value of the core of the first code generated."
},
"increment": {
"type": "integer",
"description": "Increment of the core for subsequent codes generated."
},
"padding": {
"type": "string",
"description": "How to pad the sequence, in order to keep a fixed length.",
"enum": ["ZERO", "CHAR"]
},
"paddingChar": {
"type": "string",
"description": "Single character used to pad, if `padding` is `CHAR`."
},
"prefix": {
"type": "string",
"description": "Prefix in the short ID pattern."
},
"suffix": {
"type": "string",
"description": "Suffix in the short ID pattern."
},
"separator": {
"type": "string",
"description": "Separator between prefix and core, and core and suffix in the short ID pattern."
}
}
}
}
}
},
"x-filterable-fields": ["batch", "status", "type"]
}
{
"id": "U4w8QNr3eDsa9KwRaEswppmg",
"createdAt": 1510931929512,
"updatedAt": 1510931931051,
"completedAt": 1510931931051,
"batch": "U4asNCTB6GPEYMaaRYCwwBmd",
"type": "SHORT_ID_GENERATION",
"status": "EXECUTED",
"result": {
"type": "SHORT_ID_GENERATION",
"failedOperationsAmount": 0,
"location": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/batch-U4asNCTB6GPEYMaaRYCwwBmd-task-U4w8QNr3eDsa9KwRaEswppmg3894583288787609508~5a0efdda53a60296.zip"
},
"inputParameters": {
"quantity": 5,
"shortIdTemplate": {
"type": "PSEUDO_RANDOM",
"length": 32,
"prefix": "CODE",
"suffix": "2017",
"separator": "_"
}
}
}
See also: ScopesDocument, TaskResultDocument
ShortIdGenerationInputParametersDocument
.quantity (integer, required)
Amount of short IDs to generate.
.shortIdTemplate (ShortIdTemplateDocument, required)
An object representing a short ID generation task on a
batch.
{
"additionalProperties": false,
"type": "object",
"description": "Input parameters for a Short ID Generation Task.",
"required": ["quantity", "shortIdTemplate"],
"properties": {
"quantity": {
"type": "integer",
"description": "Amount of short IDs to generate."
},
"shortIdTemplate": {
"additionalProperties": false,
"type": "object",
"description": "An object representing a short ID generation task on a batch.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The type of ShortIdTemplateDocument.",
"enum": ["SEQUENTIAL", "PSEUDO_RANDOM"]
},
"length": {
"type": "integer",
"description": "Full length of the short ID. Including separators, prefix, and suffix."
},
"start": {
"type": "integer",
"description": "Value of the core of the first code generated."
},
"increment": {
"type": "integer",
"description": "Increment of the core for subsequent codes generated."
},
"padding": {
"type": "string",
"description": "How to pad the sequence, in order to keep a fixed length.",
"enum": ["ZERO", "CHAR"]
},
"paddingChar": {
"type": "string",
"description": "Single character used to pad, if `padding` is `CHAR`."
},
"prefix": {
"type": "string",
"description": "Prefix in the short ID pattern."
},
"suffix": {
"type": "string",
"description": "Suffix in the short ID pattern."
},
"separator": {
"type": "string",
"description": "Separator between prefix and core, and core and suffix in the short ID pattern."
}
}
}
}
}
ShortIdTemplateDocument Data Model
The ShortIdTemplateDocument defines how to generate the short IDs, either using a sequence, or a pseudo random algorithm. The parameters define its length, a prefix, a suffix and a separator. The resulting short IDs string template is as follows:
<prefix><separator><core><separator><suffix>
.type (string, one of 'SEQUENTIAL', 'PSEUDO_RANDOM')
The type of ShortIdTemplateDocument.
.length (integer)
Full length of the short ID. Including separators, prefix,
and suffix.
.start (integer)
Value of the core of the first code generated.
.increment (integer)
Increment of the core for subsequent codes generated.
.padding (string, one of 'ZERO', 'CHAR')
How to pad the sequence, in order to keep a fixed length.
.paddingChar (string)
Single character used to pad, if `padding` is `CHAR`.
.prefix (string)
Prefix in the short ID pattern.
.suffix (string)
Suffix in the short ID pattern.
.separator (string)
Separator between prefix and core, and core and suffix in
the short ID pattern.
{
"type": "object",
"description": "An object representing a short ID generation task on a batch.",
"properties": {
"type": {
"type": "string",
"description": "The type of ShortIdTemplateDocument.",
"enum": [ "SEQUENTIAL", "PSEUDO_RANDOM" ]
},
"length": {
"type": "integer",
"description": "Full length of the short ID. Including separators, prefix, and suffix."
},
"start": {
"type": "integer",
"description": "Value of the core of the first code generated."
},
"increment": {
"type": "integer",
"description": "Increment of the core for subsequent codes generated."
},
"padding": {
"type": "string",
"description": "How to pad the sequence, in order to keep a fixed length.",
"enum": [ "ZERO", "CHAR" ]
},
"paddingChar": {
"type": "string",
"description": "Single character used to pad, if `padding` is `CHAR`."
},
"prefix": {
"type": "string",
"description": "Prefix in the short ID pattern."
},
"suffix": {
"type": "string",
"description": "Suffix in the short ID pattern."
},
"separator": {
"type": "string",
"description": "Separator between prefix and core, and core and suffix in the short ID pattern."
}
}
}
Read All Tasks for a Given Batch
Read all tasks for the specified batch.
GET /batches/:batchId/tasks
Authorization: $OPERATOR_API_KEY
curl -H "Authorization: $OPERATOR_API_KEY" \
-X GET 'https://api.evrythng.com/batches/U2EBHMxdAh6MTrSh4t26NqUf/tasks'
const batchId = 'U2EBHMxdAh6MTrSh4t26NqUf';
operator.batch(batchId).task()
.read()
.then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "UG92f3A2MmPEE6wRwhtErd9f",
"createdAt": 1509447992783,
"updatedAt": 1509447993852,
"completedAt": 1509447993852,
"batch": "UmNqmfDEBDswtpaaRDs6xHpn",
"type": "POPULATING",
"status": "EXECUTED",
"result": {
"type": "POPULATING",
"failedOperationsAmount": 0,
"location": "https://s3.amazonaws.com/evtcdn_02/2/uf/UmFVekRaVXsa9pRwwYaRDmer/batch-UmNqmfDEBDswtpaaRDs6xHpn-task-Um92fmAkBgswtpRwRXHMFDke3437439154428411976~59f8593963153ae0.zip",
"format": "CSV",
"totalThngsCreated": 5,
"totalUrlBindingsCreated": 5,
"totalCount": 10
},
"inputParameters": {
"generateThngs": true,
"generateRedirections": true,
"shortDomain": "tn.gg",
"defaultRedirectUrl": "https://google.com",
"thngTemplate": {
"tags": [ "Generated" ],
"name": "List Based Task Thng"
},
"type": "LIST_BASED",
"inputData": [
{ "shortId": "IDF20170001" },
{ "shortId": "IDF20170002" },
{ "shortId": "IDF20170003" },
{ "shortId": "IDF20170004" },
{ "shortId": "IDF20170005" }
]
},
"progress": {
"contributions": {
"U3QkWGUm6QteEsawwEAVht2b": {
"urlBindings": 5,
"thngs": 5,
"failedUrlBindings": 0,
"failedThngs": 0
}
},
"totalAmount": 10
}
}
]
Read a Task By ID
GET /batches/:batchId/tasks/:taskId
Authorization: $OPERATOR_API_KEY
curl -i -H "Authorization: $OPERATOR_API_KEY" \
-X GET 'https://api.evrythng.com/batches/:batchId/tasks/:taskId'
const batchId = 'Un74wEkMBDswQpawaEeCtecs';
const taskId = 'U4NnRYrgBg8wQKwwaFKsBetq';
operator.batch(batchId).task(taskId)
.read()
.then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "UG92f3A2MmPEE6wRwhtErd9f",
"createdAt": 1509447992783,
"updatedAt": 1509447993852,
"completedAt": 1509447993852,
"batch": "UmNqmfDEBDswtpaaRDs6xHpn",
"type": "POPULATING",
"status": "EXECUTED",
"result": {
"type": "POPULATING",
"failedOperationsAmount": 0,
"location": "https://s3.amazonaws.com/evtcdn_02/2/uf/UmFVekRaVXsa9pRwwYaRDmer/batch-UmNqmfDEBDswtpaaRDs6xHpn-task-Um92fmAkBgswtpRwRXHMFDke3437439154428411976~59f8593963153ae0.zip",
"format": "CSV",
"totalThngsCreated": 5,
"totalUrlBindingsCreated": 5,
"totalCount": 10
},
"inputParameters": {
"generateThngs": true,
"generateRedirections": true,
"shortDomain": "tn.gg",
"defaultRedirectUrl": "https://google.com",
"thngTemplate": {
"tags": [
"Generated"
],
"name": "List Based Task Thng"
},
"type": "LIST_BASED",
"inputData": [
{
"shortId": "IDF20170001"
},
{
"shortId": "IDF20170002"
},
{
"shortId": "IDF20170003"
},
{
"shortId": "IDF20170004"
},
{
"shortId": "IDF20170005"
}
]
},
"progress": {
"contributions": {
"U3QkWGUm6QteEsawwEAVht2b": {
"urlBindings": 5,
"thngs": 5,
"failedUrlBindings": 0,
"failedThngs": 0
}
},
"totalAmount": 10
}
}
Read Task Error Logs
When creating tasks, in some cases some resources may not be created (e.g. when input data is invalid). An example that can cause errors to be logged is attempting to re-use short IDs that have already been assigned to generated Thngs.
If a task has completed with errors (EXECUTED_WITH_FAILURES), you can access the logs of that task to identify the problems that occurred. The logs for a task can be accessed as an array of entries as follows:
GET /batches/:batchId/tasks/:taskId/logs
Authorization: $OPERATOR_API_KEY
curl -H "Authorization: $OPERATOR_API_KEY" \
-X GET "https://api.evrythng.com/batches/U2EBHMxdAh6MTrSh4t26NqUf/tasks/UFhe5yE5Bd5Hesyphxb8Fydk/logs"
const batchId = 'U2EBHMxdAh6MTrSh4t26NqUf';
const taskId = 'UFhe5yE5Bd5Hesyphxb8Fydk';
evrythng.api({
url: `/batches/${batchId}/tasks/${taskId}/logs`,
apiKey: operatorApiKey,
}).then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"jobId": "ULKr1eaYwzMmJpEqAxCvOjPw",
"payload": {
"thng": "UXGh7dyGsyNyDMKyDhYfbmMe",
"urlBinding": "UXGh7dyGsyNyDMKyDhYfbmMf",
"shortId": "yHk23po"
},
"type": "ERROR"
}
]
RedirectionResourceDocument Data Model
.shortId (string)
The short ID for the redirection.
{
"type": "object",
"description": "Container for a task generation short ID.",
"properties": {
"shortId": {
"type": "string",
"description": "The short ID for the redirection."
}
}
}
TaskResultDocument Data Model
.totalCount (integer, read-only)
The total count of generated resources.
.totalThngsCreated (integer, read-only)
The total count of generated Thngs.
.totalUrlBindingsCreated (integer, read-only)
The total count of generated redirections.
.location (string, read-only)
The URL of the result file.
.format (string, one of 'CSV', 'ZIP')
The type of input or results file.
.headers (object, read-only)
Key-value set of HTTP headers.
.error (string, read-only)
The error message describing what went wrong.
.failedOperationsAmount (integer, read-only)
Total number of failed operations.
.type (string, read-only, one of 'SHORT_ID_GENERATION', 'POPULATING', 'ERROR')
The type of result.
{
"type": "object",
"description": "Description of the result of a batch task.",
"properties": {
"totalCount": {
"type": "integer",
"description": "The total count of generated resources.",
"readOnly": true
},
"totalThngsCreated": {
"type": "integer",
"description": "The total count of generated Thngs.",
"readOnly": true
},
"totalUrlBindingsCreated": {
"type": "integer",
"description": "The total count of generated redirections.",
"readOnly": true
},
"location": {
"type": "string",
"description": "The URL of the result file.",
"readOnly": true
},
"format": {
"type": "string",
"description": "The type of input or results file.",
"enum": [ "CSV", "ZIP" ]
},
"headers": {
"type": "object",
"description": "Key-value set of HTTP headers.",
"readOnly": true
},
"error": {
"type": "string",
"description": "The error message describing what went wrong.",
"readOnly": true
},
"failedOperationsAmount": {
"type": "integer",
"description": "Total number of failed operations.",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of result.",
"enum": [ "SHORT_ID_GENERATION", "POPULATING", "ERROR" ],
"readOnly": true
}
}
}
OutputParametersDocument Data Model
.type (string, one of 'CSV')
The output format type.
.columns (array of string)
The CSV columns to use. Valid values are 'SHORT_ID' and
'THNG'.
{
"type": "object",
"description": "The output format for the task.",
"properties": {
"type": {
"type": "string",
"description": "The output format type.",
"enum": [ "CSV" ]
},
"columns": {
"type": "array",
"description": "The CSV columns to use. Valid values are 'SHORT_ID' and 'THNG'",
"items": {
"type": "string",
"enum": [ "SHORT_ID", "THNG" ]
}
}
}
}
TaskProgressDocument Data Model
.contributions (object, read-only)
Object of keys for each contribution group, with resource
counts as the value.
.totalAmount (integer, read-only)
The total amount of generated resources so far.
{
"type": "object",
"description": "Description of the task progress in terms of individual contributions.",
"properties": {
"contributions": {
"type": "object",
"description": "Object of keys for each contribution group, with resource counts as the value.",
"readOnly": true
},
"totalAmount": {
"type": "integer",
"description": "The total amount of generated resources so far.",
"readOnly": true
}
}
}