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:

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 manipulating the data directly.

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.