Tasks

A task is responsible for performing all asynchronous workloads on the API, such as establishing a session with external services, and retrieving and processing data.

Tasks are most commonly created as part of the creation of a session resource or during the execution of a poll.

Any data returned from a task is described by any associated result resources.

Some tasks, mainly involved with system and organisation management, may not target a user, source or session, or be associated with a poll. Examples of this kind of task are the storage and webhook config test tasks.

Attributes

Source types

If the task is associated to a source, the type of the source will be denormalised onto the source_type task attribute. This helps simplify queries for tasks of a certain type.

Types

The task type is a short slug identifying the underlying task being executed within the API.

If the task relates to activity against a resource, such as testing a webhook config, it will be formatted like webhook_config.test.

If the task targets a specific source, then the source_type attribute will store the source related information, while the type attribute only stores the main action. For example, creating a session will trigger an session.init task to be created against a source of type icloud.account.

Target

This specifies the target of the underlying task, and is not always set. For example, the target of a webhook_config.test will be the ID of the webhook config to be tested. For a data task against an icloud.account type source, it will be the data type to be retrieved like messages.whatsapp.

State

• pending the task has been created but is currently waiting in queue.
• processing the task is being executed by an API worker.
• suspended the task is waiting for blocking tasks to complete before proceeding.
• succeeded the task completed without errors.
• failed the task encountered errors.

Errors

If the task runs into issues during processing this field will be set with the code of the error encountered.

Changelog

2020-02-20

• Major The results attribute of the task object is now a nested list object, rather than a simple list attribute.

2019-10-16

• The state attribute of the task object can now have the value suspended. This indicates that the API is awaiting completion of actions by the Reincubate Relay application, such as a file upload or metadata update, for it to resume and complete the task.

Retrieve GET /tasks/{task ID}

Using cURL

curl https://ricloud-api.reincubate.com/tasks/<task ID> \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

task = ricloud.Task.retrieve(<task ID>)

Sample response

{
  "id": "00000001-1234-1234-1234-9876543210",
  "resource": "task",
  "organisation": 1,
  "key": 1,
  "user": 1,
  "source": 1,
  "session": "00000002-1234-1234-1234-9876543210",
  "poll": "00000003-1234-1234-1234-9876543210",
  "source_type": "mocks.mock",
  "type": "info",
  "target": null,
  "results": {
    "data": [],
    "has_more": false,
    "total_count": 1,
    "url": "/tasks/00000001-1234-1234-1234-9876543210/results"
  },
  "state": "processing",
  "error": null,
  "date_created": "2020-02-20T11:59:15.110451Z",
  "date_started": "2020-02-20T11:59:15.207932Z",
  "date_completed": null
}

List GET /tasks

Parameters

Using cURL

curl https://ricloud-api.reincubate.com/tasks \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

tasks = ricloud.Task.list()