Python API

class RPA.Robocloud.Items.BaseAdapter(workspace_id, item_id)

Bases: abc.ABC

Abstract base class for work item adapters.

abstract add_file(name, content)

Attach file to work item.

abstract get_file(name)

Read file’s contents from work item.

abstract list_files()

List attached files in work item.

abstract load_data()

Load data payload from work item.

abstract remove_file(name)

Remove attached file from work item.

abstract save_data(data)

Save data payload to work item.

class RPA.Robocloud.Items.FileAdapter(*args, **kwargs)

Bases: RPA.Robocloud.Items.BaseAdapter

Adapter for saving/loading work items from disk.

Required environment variables:

  • RPA_WORKITEMS_PATH: Path to work items database file

add_file(name, content)

Write file to disk.

get_file(name)

Read file from disk.

list_files()

List files in the same folder as database.

load_data()

Load data payload from file.

read_database()

Read JSON database from disk.

remove_file(name)

Do not remove local files.

save_data(data)

Save data payload to file.

class RPA.Robocloud.Items.Items(load_env=True, default_adapter=<class 'RPA.Robocloud.Items.RobocorpAdapter'>)

Bases: object

A library for interacting with RPA work items.

Work items are used for managing data that go through multiple activities and tasks inside a process. Each execution of an activity receives a work item from the previous activity, and after the activity is finished, it is forwarded to the next one. During the execution, it can freely read and update the data contained in an item.

The default implementation uses Robocloud to store the data, but the library allows using custom adapters.

Default environment

The library automatically loads the work item defined by its runtime environment if the argument load_env is truthy (enabled by default). This functionality is controlled by the following environment variables:

  • RC_WORKSPACE_ID: The ID for the Robocloud workspace

  • RC_WORKITEM_ID: The ID for the Robocloud work item

These values are dynamic and should be set by Robocloud, but can be overriden manually while developing an activity.

Item structure

A work item’s data payload is JSON and allows storing anything that is serializable. This library creates an object with the key ‘variables’ that contains key-value pairs of a variable name and its contents. These variables can be exposed to the Robot Framework task to be used directly.

In addition to the data section, a work item can also contain files, which are stored by default in Robocorp’s cloud. Adding and using files with work items requires no additional setup from the user.

Workflow

While a work item is loaded automatically when a suite starts, changes are not automatically reflected back to the source. The work item will be modified locally and then saved when the corresponding keyword is explicitly called. It is recommended to defer all saves to the end of the task to prevent leaving work items in a half-modified state after failures.

Custom adapters

While Robocloud is the default implementation, it can also be replaced with a custom adapter. The selection is based on either the default_adapter argument for the library, or the RPA_WORKITEMS_ADAPTER environment variable. A custom implementation should inherit from the BaseAdapter class. The library has a built-in alternative adapter called FileAdapter for storing work items to disk.

Examples

Robot Framework

In the following example the work item is modified locally and then saved back to Robocloud. Also note how the work item is loaded implicitly when the suite starts.

*** Settings ***
Library    RPA.Robocloud.Items

*** Tasks ***
Save variables to Robocloud
    Add work item file    orders.xlsx
    Set work item variables    user=Dude    mail=address@company.com
    Save work item

Later in the process inside a different robot, we can use previously saved work item variables and files. The library also allows injecting the variables directly into the current task execution.

*** Settings ***
Library    RPA.Robocloud.Items

*** Tasks ***
Use variables from Robocloud
    Set task variables from work item
    Log    Variables are now available: ${user}, ${mail}
    ${path}=    Get work item file    orders.xlsx
    Log    Files are also stored to disk: ${path}

Python

The library can also be used through Python, but it does not implicitly load the work item for the current execution.

import logging
from RPA.Robocloud.Items import Items

def list_variables(item_id):
    library = Items()
    library.load_work_item_from_environment()

    for variable, value in library.get_work_item_variables().items():
        logging.info("%s = %s", variable, value)
ROBOT_LIBRARY_DOC_FORMAT = 'REST'
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
ROBOT_LISTENER_API_VERSION = 2
adapter = None

Adapter factory for new work items

add_work_item_file(path, name=None)

Add given file to work item.

Parameters
  • path – Path to file on disk

  • name – Destination name for file. If not given, current name of local file is used.

NOTE: Files are not uploaded before work item is saved

Example:

Add work item file    output.xls
Save work item
add_work_item_files(pattern)

Add all files that match given pattern to work item.

Parameters

pattern – Path wildcard pattern

Example:

Add work item files    %{ROBOT_ROOT}/generated/*.csv
Save work item
clear_work_item()

Remove all data in the current work item.

Example:

Clear work item
Save work item
current = None

The current active work item, set automatically to latest loaded item

delete_work_item_variables(*names, force=True)

Delete variable(s) from the current work item.

Parameters
  • names – Names of variables to remove

  • force – Ignore variables that don’t exist in work item

Example:

Delete work item variables    username    email
Save work item
get_work_item_file(name, path=None)

Get attached file from work item to disk. Returns the absolute path to the created file.

Parameters
  • name – Name of attached file

  • path – Destination path of file. If not given, current working directory is used.

Example:

${path}=    Get work item file    input.xls
Open workbook    ${path}
get_work_item_files(pattern, dirname=None)

Get files attached to work item that match given pattern. Returns a list of absolute paths to the downloaded files.

Parameters
  • pattern – Filename wildcard pattern

  • dirname – Destination directory, if not given robot root is used

Example:

${paths}=    Get work item files    customer_*.xlsx
FOR  ${path}  IN  @{paths}
    Handle customer file    ${path}
END
get_work_item_payload()

Get the full JSON payload for a work item.

NOTE: Most use cases should prefer higher-level keywords.

Example:

${payload}=    Get work item payload
Log    Entire payload as dictionary: ${payload}
get_work_item_variable(name, default=<object object>)

Return a single variable value from the work item, or default value if defined and key does not exist. If key does not exist and default is not defined, raises KeyError.

Parameters
  • key – Name of variable

  • default – Default value if key does not exist

Example:

${username}=    Get work item variable    username    default=guest
get_work_item_variables()

Read all variables from the current work item and return their names and values as a dictionary.

Example:

${variables}=    Get work item variables
Log    Username: ${variables}[username], Email: ${variables}[email]
list_work_item_files()

List the names of files attached to the current work item.

Example:

${names}=    List work item files
Log    Work item has files with names: ${names}
list_work_item_variables()

List the variable names for the current work item.

Example:

${variables}=    List work item variables
Log    Available variables in work item: ${variables}
load_work_item(workspace_id, item_id)

Load work item for reading/writing.

Parameters
  • workspace_id – Workspace ID which contains item

  • item_id – Workitem ID to load

NOTE: Currently only one work item per execution is supported

by Robocorp Cloud, which should be loaded automatically.

load_work_item_from_environment()

Load current work item defined by the runtime environment.

The corresponding environment variables are:

  • RC_WORKSPACE_ID

  • RC_WORKITEM_ID

remove_work_item_file(name, missing_ok=True)

Remove attached file from work item.

Parameters
  • name – Name of attached file

  • missing_ok – Do not raise exception if file doesn’t exist

NOTE: Files are not deleted before work item is saved

Example:

Remove work item file    input.xls
Save work item
remove_work_item_files(pattern, missing_ok=True)

Removes files attached to work item that match given pattern.

Parameters
  • pattern – Filename wildcard pattern

  • missing_ok – Do not raise exception if file doesn’t exist

Example:

Remove work item files    *.xlsx
Save work item
save_work_item()

Save the current data in the work item. If not saved, all changes are discarded when the library goes out of scope.

set_task_variables_from_work_item()

Convert all variables in the current work item to Robot Framework task variables.

Example:

# Work item has variable INPUT_URL
Set task variables from work item
Log    The variable is now available: ${INPUT_URL}
set_work_item_payload(payload)

Set the full JSON payload for a work item.

Parameters

payload – Content of payload, must be JSON-serializable

NOTE: Most use cases should prefer higher-level keywords.

Example:

${output}=    Create dictionary    url=example.com    username=Mark
Set work item payload    ${output}
set_work_item_variable(name, value)

Set a single variable value in the current work item.

Parameters
  • key – Name of variable

  • value – Value of variable

Example:

Set work item variable    username    MarkyMark
Save work item
set_work_item_variables(**kwargs)

Set multiple variables in the current work item.

Parameters

kwargs – Pairs of variable names and values

Example:

Set work item variables    username=MarkyMark    email=mark@example.com
Save work item
class RPA.Robocloud.Items.RobocorpAdapter(*args, **kwargs)

Bases: RPA.Robocloud.Items.BaseAdapter

Adapter for saving/loading work items from Robocorp Cloud.

Required environment variables:

  • RC_API_WORKITEM_HOST: Work item API hostname

  • RC_API_WORKITEM_TOKEN: Work item API access token

add_file(name, content)

Attach and upload file.

Parameters
  • name – Destination name

  • content – Content of file

file_id(name)

Convert filename to ID used by Robocorp API.

Parameters

name – Name of file

get_file(name)

Download attached file content.

Parameters

name – Name of file

handle_error(response)

Handle response, and raise errors with human-friendly messages.

Parameters

response – Response returned by HTTP request

property headers
list_files()

List names of attached files.

load_data()

Load data payload as JSON.

remove_file(name)

Remove attached file.

Parameters

name – Name of file

save_data(data)

Save data payload as JSON.

url(*parts)

Create full URL to Robocorp endpoint.

class RPA.Robocloud.Items.WorkItem(workspace_id, item_id, adapter)

Bases: object

Container for a single work item, with local caching.

Parameters
  • workspace_id – Workspace ID which contains item

  • item_id – Workitem ID

  • adapter – Adapter for storage backend

add_file(path, name=None)

Add file to current work item. Does not upload until save() is called.

Parameters
  • path – Path to file to upload

  • name – Name of file in work item. If not given, name of file on disk is used.

property data
property files

List of filenames, including local files pending upload and excluding files pending removal.

get_file(name, path=None)

Load an attached file and store it on the local filesystem.

Parameters
  • name – Name of attached file

  • path – Destination path. Default to current working directory.

Returns

Path to created file

property is_dirty

Check if work item has unsaved changes.

load()

Load data payload and list of files.

remove_file(name, missing_ok=True)

Remove file from current work item. Change is not applied until save() is called.

Parameters

name – Name of attached file

save()

Save data payload and attach/remove files.

RPA.Robocloud.Items.is_json_equal(left, right)

Deep-compare two output JSONs.

RPA.Robocloud.Items.json_dump_safe(data, **kwargs)

Convert data to JSON string, and skip invalid values.

RPA.Robocloud.Items.url_join(*parts)

Join parts of URL and handle missing/duplicate slashes.