A library for interacting with Control Room work items.

Work items are used for managing data that go through multiple steps and tasks inside a process. Each step of a process receives input work items from the previous step, and creates output work items for the next step.

Item structure

A work item's data payload is JSON and allows storing anything that is serializable. This library by default interacts with payloads that are a dictionary of key-value pairs, which it treats as individual variables. 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 Control Room. Adding and using files with work items requires no additional setup from the user.

Loading inputs

The library automatically loads the first input work item, if the library input argument autoload is truthy (default).

After an input has been loaded its payload and files can be accessed through corresponding keywords, and optionally these values can be modified.

Creating outputs

It's possible to create multiple new work items as an output from a task. With the keyword Create output work item a new empty item is created as a child for the currently loaded input.

All created output items are sent into the input queue of the next step in the process.

Active work item

Keywords that read or write from a work item always operate on the currently active work item. Usually that is the input item that has been automatically loaded when the execution started, but the currently active item is changed whenever the keywords Create output work item or Get input work item are called. It's also possible to change the active item manually with the keyword Set current work item.

Saving changes

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 keyword Save work item is called. This also applies to created output work items.

It is recommended to defer saves until all changes have been made to prevent leaving work items in a half-modified state in case of failures.

Development and mocking

While Control Room 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. The library has a built-in alternative adapter called FileAdapter for storing work items to disk.

The FileAdapter uses a local JSON file for input work items. It's a list of work items, each of which has a data payload and files.

An example of a local file with one work item:

        "payload": {
            "variable1": "a-string-value",
            "variable2": ["a", "list", "value"]
        "files": {
            "file1": "path/to/file.ext"

Output work items (if any) are saved to an adjacent file with the same name, but with the extension .output.json. You can specify through the "RPA_OUTPUT_WORKITEM_PATH" env var a different path and name for this file.


Robot Framework

In the following example a task creates an output work item, and attaches some variables to it.

*** Settings ***
Library    RPA.Robocorp.WorkItems

*** Tasks ***
Save variables to Control Room
    Create output work item
    Set work item variables    user=Dude    mail=address@company.com
    Save work item

In the next step of the process inside a different robot, we can use previously saved work item variables. Also note how the input work item is loaded implicitly when the suite starts.

*** Settings ***
Library    RPA.Robocorp.WorkItems

*** Tasks ***
Use variables from Control Room
    Set task variables from work item
    Log    Variables are now available: s${user}, ${mail}


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

import logging
from RPA.Robocorp.WorkItems import WorkItems

def list_variables(item_id):
    library = WorkItems()

    variables = library.get_work_item_variables()
    for variable, value in variables.items():
        logging.info("%s = %s", variable, value)