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`

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

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.

FixedAmountTaskDocument Data Model

The request payload used to create a Fixed Amount Batch Populating Task.

See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument

FixedAmountInputParametersDocument Data Model

The input parameters that determine the behavior of the Fixed Amount Batch Populating Task.

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.

FileBasedTaskDocument Data Model

The request payload used to create a File Based Batch Populating Task.

See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument

FileBasedInputParametersDocument Data Model

The input parameters that determine the behavior of a File Based Batch Populating Task.

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.

ListBasedTaskDocument Data Model

The request payload used to create a List Based Batch Populating Task.

See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument

ListBasedInputParametersDocument Data Model

The input parameters that determine the behavior of the List Based Batch Populating Task

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, generateRedirections must always be false.

IdentifiersListBasedTaskDocument Data Model

The request payload used to create a Identifiers List Based Batch Populating Task.

See also: ScopesDocument, TaskResultDocument, OutputParametersDocument, TaskProgressDocument

IdentifiersListBasedInputParametersDocument Data Model

The input parameters that determine the behavior of the Identifiers List Based Batch Populating Task.

See also: ThngDocument

CustomIdentifierDocument Data Model

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

ShortIdGenerationTaskDocument Data Model

See also: ScopesDocument, TaskResultDocument

ShortIdGenerationInputParametersDocument

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>

Read All Tasks for a Given Batch

Read all tasks for the specified batch.

Read a Task By ID

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:

RedirectionResourceDocument Data Model

TaskResultDocument Data Model

OutputParametersDocument Data Model

TaskProgressDocument Data Model