Using the Robocloud.Items library

What is the Work Item?

Steps in the same process can share data during their execution, thanks to the concept of Work Item. Each step execution receives a work item from the previous step and passes it forward to the next one. During the execution, each step can freely read and update the data contained in the item. It is also possible to configure a step to accept an initial work item and pass the desired contents when triggering the process that contains the step via an API call.

A simple example: Reading and setting a variable

Program your robot to read and write from the work item

Create a new robot in Robocorp Lab. Edit the tasks.robot file like this:

*** Settings ***
Documentation     A simple Robot to demonstrate the use of the Work Item.
Library           RPA.Robocloud.Items

*** Tasks ***
Demonstrate how to read and write variables in the work item
    ${MESSAGE}=    Get Work Item Variable    message
    Log    ${MESSAGE}
    Set Work Item Variable    myNewVariable    Hello to you too!
    Save Work Item

In this example, we are adding the RPA.Robocloud.Items library, and using these keywords:

Get Work Item Variable gets the value of a work item variable, in our case, a variable called message
Set Work Item Variable myNewVariable Hello to you too! sets a new variable and assigns it the provided value
Save Work Item is necessary to make the changes to the work item permanent.

The RPA.Robocloud.Items library automatically loads the work item defined by its runtime environment.

Configure the work item library to work locally

When executing a robot in a cloud environment like Robocorp Cloud, the RPA.Robocloud.Items library will store the work item in the cloud environment, sharing its contents between steps defined in the same process, without any configuration needed.

However, when developing our robot and running it locally, we want the library to store the data in a JSON file, and provide the required parameters to simulate the cloud environment.

Create a new file called items.json on your file system, for example, at /Users/<username>/items.json.

Paste this content into your items.json file:

{
  "1": {
    "1": {
      "variables": {
        "message": "Hello World!"
      }
    }
  }
}

Create a devdata/env.json file in your robot structure and paste in the following configuration:

{
  "RPA_WORKITEMS_ADAPTER": "RPA.Robocloud.Items.FileAdapter",
  "RPA_WORKITEMS_PATH": "/Users/<username>/items.json",
  "RC_WORKSPACE_ID": 1,
  "RC_WORKITEM_ID": 1
}

RC_WORKSPACE_ID and RC_WORKITEM_ID can be any arbitrary numeric value, but they need to match what you entered in your items.json file.

Edit the RPA_WORKITEMS_PATH variable to point to the items.json file on your filesystem. On macOS / Linux, use normal file paths, for example, /Users/<username>/items.json. On Windows 10, you need to escape the path, for example, C:\\Users\\User\\items.json.

Running the robot locally

Run the robot. It will produce this log:

Work item example logs

And your items.json file will now contain a new variable myNewVariable:

{
  "1": {
    "1": {
      "variables": {
        "message": "Hello World!",
        "myNewVariable": "Hello to you too!"
      }
    }
  }
}

Running the robot in Robocorp Cloud

This simple robot expects to receive a work item that contains a variable called message.

You can accomplish this in two ways:

triggering a process containing this step via an API call, passing the work item content, as described in Triggering processes in Robocorp Cloud via the Process API article
adding this step to a process where another step in the same process sets the message work item step before it, like in the PDF Invites printer robot available on this site.

Manipulating the whole item payload

As we have seen, the Get Work Item Variable and Set Work Item Variable keywords allow you to conveniently manipulate the data in the variables JSON property of your work item.

There are cases, for example, when receiving a webhook from an external system, when you might want or have to structure the data differently. In these cases, you can take advantage of the Get Work Item Payload and Set Work Item Payload keywords to work with the whole item payload.

Assuming you have a work item structured like this:

{
  "1": {
    "1": {
      "customData": {
        "message": "Hello World!"
      }
    }
  }
}

Note how the item now has customData as the containing element, not variables anymore.

Because you do not have a variables element, the Get Work Item Variable, Set Work Item Variable, and Get Work Item Variables keywords are not helpful in this case. Instead, you will need to access the full payload item and then target the data elements you need by directly manipulating the data.

Edit the tasks.robot file like this:

*** Settings ***
Documentation     A simple robot to demonstrate manipulating the item payload directly.
Library           RPA.Robocloud.Items
Library           Collections

*** Tasks ***
Demonstrate how to read and write the full payload in the work item
    ${PAYLOAD}=    Get Work Item Payload
    Log    ${PAYLOAD}[customData][message]
    Set To Dictionary    ${PAYLOAD}[customData]    myNewMessage    Hello to you too!
    Set Work Item Payload    ${PAYLOAD}
    Log    ${PAYLOAD}
    Save Work Item

In the *** Settings *** section, we have added the standard robotframework Collections library, which allows us to manipulate data structures like lists and dictionaries.
We are using the Get Work Item Payload keyword to get the whole payload into a variable that we call ${PAYLOAD}.
We can access the data within the payload using square brackets. For example, to get to the message property within the customData property, we can use ${PAYLOAD}[customData][message].
To add a new property inside customData dictionary, we can use the Set To Dictionary keyword that we got from the Collections library, passing the desired key and value.
We can then set the work item payload using the Set Work Item Payload, and finally make the change permanent using the Save Work Item keyword.

Once run, the robot will produce this log:

Work item example logs

Using this method, you can work on payloads with arbitrary structures at the price of adding a bit of complexity: for this reason, if you can create your payload using the default structure, we recommend you do so.

Working with files in the work item

In addition to structured data, the work item can also be used to store and share files. The RPA.Robocloud.Items library provides keywords to add, retrieve, list, and delete work item files. Just like all other data stored in the work item, the files will be available to all robot steps added to the same process. Files added to the work item are stored by Robocorp Cloud, and can be inspected using its user interface.

Robocorp Cloud enforces a size limit of 50 MB per file added to the work item.

Configure the work item library to work locally with files

The same setup we detailed in the simple example applies here. The library will use the directory where the item.json resides to operate on files. All the files in the directory will be considered work item files. When new files are added to the work item, they will be copied to the directory.

Example: Two-step robot using files in the work item

This two-step robot shares a file via the work item. The first step downloads a remote Excel file and adds it to the work item. The second step retrieves the file from the work item and opens it.

First step: Download the remote file and add it to the work item

File: task1.robot

*** Settings ***
Documentation     Downloading a remote file and adding it to the work item.
Library           RPA.Robocloud.Items
Library           RPA.HTTP

*** Tasks ***
Download A Remote Excel File And Add It To The Work Item
    Download    https://robotsparebinindustries.com/SalesData.xlsx    overwrite=True
    Add Work Item File    SalesData.xlsx
    Save Work Item

Note: It is always necessary to use the Save Work Item keyword to persist any changes to the work item, including when adding or removing files.

Second step: Get the file from the work item and open it

File: task2.robot

*** Settings ***
Documentation     Getting a file from the work item and opening it.
Library           RPA.Robocloud.Items
Library           RPA.Excel.Files

*** Tasks ***
Get an Excel file stored in the work item and open it
    ${path}=    Get Work Item File    SalesData.xlsx
    Open Workbook    ${path}

robot.yaml

The robot.yaml for our two step robot looks like this:

tasks:
  save file to work item:
    command:
      - python
      - -m
      - robot
      - --report
      - NONE
      - --outputdir
      - output
      - --logtitle
      - Task log
      - task1.robot
  retrieve file from work item:
    command:
      - python
      - -m
      - robot
      - --report
      - NONE
      - --outputdir
      - output
      - --logtitle
      - Task log
      - task2.robot

condaConfigFile: conda.yaml
artifactsDir: output
PATH:
  - .
PYTHONPATH:
  - .
ignoreFiles:
  - .gitignore

Running in Robocorp Cloud

The two tasks in our robot can be added as steps to a single process in Robocorp Cloud:

Two step process in Robocorp Cloud

Once the process has been executed, you can inspect the work item contents for the run in the Finished work items panel on the process page:

Finished work items listing

By clicking on each row, you can see more details about the finished work item, and you can download any files added to it.

Work Item Details