Polls

A poll resource contains information on a specific request for data. Once a poll is created, it will trigger the creation of one or more tasks in order to complete the request.

Attributes

Tasks

The most important role of the poll resource is to reflect the progress of its associated tasks and allow the end-user to start fetching results from these as soon as they become available. Therefore, the poll resource exposes task related attributes wherein associated tasks are categorised by their state.

Results

Any results published by tasks running within the poll are surfaced in the poll's results attribute.

States

The state of a poll reflects only whether the poll is awaiting initialisation (pending), is in progress (processing), or all tasks have finished execution (completed).

A poll does not reflect any error states other than through its associated tasks.

Payload

The poll payload indicates which types of information, data types, and files it should work to retrieve. The poll payload attribute schema is described below.

For example, the poll payload to retrieve all types of information on an iCloud account source would be:

{
  "info_types": ["*"]
}

To retrieved a variety of messaging data from an iCloud backup or Reincubate Relay source, but only from a certain date:

{
  "data_types": ["ios_messages.messages", "whatsapp.messages", "viber.messages"],
  "filters": {
    "since": "2019-09-15T22:04:12Z"
  }
}

To retrieve file data for images referenced in an iCloud Photo Library result:

{
  "files": ["icpl://xyz123", "icpl://abc321"]
}

The different attributes can also be used simultaneously:

{
  "info_types": ["*"],
  "data_types": ["ios_phone.calls"]
}

Changelog

2020-02-20

• Major: The results attribute of the poll object is now a nested list object, rather than a simple list attribute. This makes it possible to paginate results when a poll publishes a large number of results.

2019-10-16

• Adds the subscription attribute to the poll object to indicate whether the poll was triggered by a subscription.

2019-06-01

• The poll object payload attribute can now be composed of multiple operation types. This means a poll can be created with any or all of info-types, data-types and files in the payload.
• Major The type attribute on the poll object is deprecated in favour of composable poll payloads.

Create POST /polls

Create a poll for data against a specific session.

As a session resource is already directly tied to a specific source, you do not have to provide the source parameter. However, it can be provided to specify that the poll target a child source of the primary source the session is tied to. For example, on the iCloud service a session can only be created against iCloud account sources (the primary source of the iCloud service), but you can target data only from a specific iCloud backup (a child source of the iCloud account) by providing its ID.

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "<session ID>",
  "payload": {
    "info_types": ["*"]
  }
}'

Using ricloud-py

import ricloud

poll_payload = {
  'info_types': ['*'],
}

poll = ricloud.Poll.create(
  session='<session ID or ricloud.Session instance>',
  payload=poll_payload,
)

Sample response

{
  "id": "54554389-5f1a-4ccf-9bb8-024a031cf948",
  "resource": "poll",
  "organisation": 1,
  "key": 1,
  "user": 1,
  "source": 1,
  "session": "f5a7a7ef-ff21-47fe-9aa6-7ebd08123623",
  "subscription": null,
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_succeeded": [],
  "tasks_failed": [],
  "tasks_suspended": [],
  "results": {
      "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/results"
  },
  "state": "pending",
  "date_created": "2020-02-20T11:59:14.694337Z",
  "date_started": null,
  "date_completed": null
}

Retrieve GET /polls/{poll ID}

Using cURL

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

Using ricloud-py

import ricloud

poll = ricloud.Poll.retrieve(<poll ID>)

List GET /polls

Using cURL

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

Using ricloud-py

import ricloud

polls = ricloud.Poll.list()