NoteCreating 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
/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
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
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
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.
NoteFor this task type,
generateRedirections
must always befalse
.
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: