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 calledmessage
Set Work Item Variable myNewVariable Hello to you too!
sets a new variable and assigns it the provided valueSave 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
andRC_WORKITEM_ID
can be any arbitrary numeric value, but they need to match what you entered in youritems.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:
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, notvariables
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 robotframeworkCollections
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 thecustomData
property, we can use${PAYLOAD}[customData][message]
. - To add a new property inside
customData
dictionary, we can use theSet To Dictionary
keyword that we got from theCollections
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 theSave Work Item
keyword.
Once run, the robot will produce this log:
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:
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:
By clicking on each row, you can see more details about the finished work item, and you can download any files added to it.