Tasks

Updated

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

name type description
id task ID Resource identifier.
resource string, always task Resource type specifier.
organisation organisation ID The organisation the resource belongs to.
key key ID The key associated with this task.
user optional, user ID The user associated with this task.
source optional, source ID The source targeted by this task.
session optional, session ID The session used by this task.
poll optional, poll ID The poll this task is associated to.
source_type optional, string The type of source this task is targetting.
type string The task type of the task.
target string The highest level argument to the task. For example, a data type task will have the data type it is retrieving as the target (i.e. messages.sms).
state string One of: pending, processing, suspended, succeeded, failed.
results list object containing result resources Any results published from the execution of the task.
error optional, string Populated with the error code, if one occurred.
date_created datetime When the resource was created.
date_started optional, datetime When task processing began.
date_completed optional, datetime When task precessing finished.

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

name type description
key key ID Filter by the associated organisation.
user user ID Filter by the associated user.
source source ID Filter by the associated source.
session session ID Filter by the associated session.
poll poll ID Filter by the owning poll.
source_type string Filter by the source type.
type string Filter by the task type.
state string Filter by the task state.
date_created datetime filter Filter by resource creation date.
date_started datetime filter Filter by when the task began processing.
date_completed datetime filter Filter by when the task completed processing.

Using cURL

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

Using ricloud-py

import ricloud

tasks = ricloud.Task.list()

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 6:20 AM GMT.

We aim to reply to all messages within one working day.

Our awesome support team

Can we improve this article?

We love hearing from users: why not drop us an email, leave a comment, or tweet @reincubate?

© 2008 - 2024 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® and Camo® are registered trademarks. Privacy policy & terms.