Polls

Updated
Cover image for: 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

name type description
id poll ID Resource identifier.
resource string, always poll Resource type specifier.
organisation organisation ID The organisation associated with this resource.
key key ID The key associated with this resource.
user user ID The user associated with this resource.
source source ID The source the poll is targeting. This can be a child source of the session's source.
session session ID The session the poll is using.
subscription optional subscription ID The associated subscription object ID, if applicable.
tasks_pending list of task IDs The tasks associated with the poll that are awaiting processing.
tasks_processing list of task IDs The tasks associated with the poll that are being processed.
tasks_succeeded list of task IDs The tasks associated with the poll that have succeeded.
tasks_failed list of task IDs The tasks associated with the poll that have failed.
tasks_suspended list of task IDs The tasks associated with the poll that are suspended.
results list object containing result objects List of result objects generated by the poll's tasks.
errors list object containing error objects List of error objects generated by the poll's tasks.
state string One of: pending, processing, completed.
date_created datetime When the resource was created.
date_started optional datetime When processing of the poll began.
date_completed optional datetime When processing of the poll finished.

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. This allows for consumption of results before the poll has completed.

Errors

Any errors raised by tasks running within the poll will appear in the poll's errors 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.

name type description
info_types list of info_type objects Specifies which info types should be retrieved. Supports wildcard *.
data_types list of data_type objects Specifies which data types should be retrieved.
files list of file IDs. Specifies which files to retrieve.
filters nested filters object Specifies which filters to apply to retrieved data.

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"]
}

Create POST /polls

Create a poll for data against a specific session.

The source parameter should only be used when targeting a child source of the session's primary source. For example, if retrieving data from a rirelay.source the source parameter should be the ID of that source.

name type description
key optional, key ID Optionally override the key used for this poll. This is useful when letting users trial new functionality.
source optional, source ID Optionally target a child source of the session-linked source.
session session ID The session to be used to authenticate data retrieval.
subscription subscription ID The subscription to use to perform the poll. If this is provided, source and session can be omitted.
payload nested poll payload The poll payload used to specify poll

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"
  },
  "errors": {
    "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/errors"
  },
  "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

name type description
key key ID Filter by associated key. This is the key used by the user at the time.
user user ID Filter by associated user.
source source ID Filter by the target source.
session session ID Filter by the target session.
subscription subscription ID Filter by the associated subscription.
state string Filter by session state.
date_created datetime filter Filter by when the resource was created.
date_started datetime filter Filter by when the poll started.
date_completed datetime filter Filter by when the poll was finished.

Using cURL

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

Using ricloud-py

import ricloud

polls = ricloud.Poll.list()

Changelog

2020-05-05

  • The errors attribute was added to the poll object. This is a nested list object containing error objects associated with the poll.

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.

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 3:26 PM GMT.

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

Go to support section › Contact the enterprise team ›
Our awesome support team

© 2008 - 2020 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy policy & terms. We recommend 2FA. Built with in London.