Robocorp Work Items library
Project description
robocorp-workitems
Work items are used in Robocorp Control Room 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.
Installation
The library can be installed from pip:
pip install robocorp-workitems
Usage
The library exposes two objects, inputs
and outputs
, which are the main way
to interact with work item queues. The former deals with the reading input work
items, and the latter with creating output work items.
Iterating over inputs and creating outputs is easy:
from robocorp import workitems
def read_inputs_and_create_outputs():
for item in workitems.inputs:
print("Received payload:", item.payload)
workitems.outputs.create(payload={"key": "value"})
Work item structure
A work item's data payload is JSON and allows storing anything that is JSON serializable. By default the payload is a mapping of key-value pairs.
In addition to the payload section, a work item can also contain files, which are stored within Robocorp Control Room. Adding and using files with work items requires no additional setup from the user.
Reserving and releasing input items
When an execution in Control Room starts, the first input item is automatically reserved. This first item is also loaded by the library when the task execution starts.
After an item has been handled, it should be released as either passed or failed. There can only be one reserved input item at a time.
Reserving can be done explicitly by calling the reserve method, which also acts as a context manager:
with workitems.inputs.reserve() as item:
print("Handling item!")
Another option is to loop through all inputs, which implicitly reserves and releases the corresponding items:
for item in workitems.inputs:
print("Handling item!")
Releasing can also be done explicitly to set specific errors, or to mark items as done before exiting the block:
for item in workitems.inputs:
order_id = item.payload["order_id"]
if not is_valid_id(order_id):
item.fail(code="INVALID_ID", message=f"Invalid order id: {order_id}")
...
item.done()
Creating outputs
For each input work item, you can create any amount of output work items. These will be forwarded to the next step of a process, or set as the final result if there are no further steps.
In most cases, it's enough to create an output item directly using
the outputs
object:
workitems.outputs.create(
payload={"key": "value"},
files=["path/to/file.txt"],
)
Internally, Control Room keeps a relationship between the parent and child work items. The above example always uses the currently reserved item as the parent, but it's also possible to create an output explicitly from the input item:
with workitems.inputs.reserve() as input_item:
input_item.create_output(payload={"key": "value"})
In some cases, it's also useful to create an output item and then modify it before saving:
item = workitems.outputs.create(save=False)
for index, path in enumerate(directory.glob("*.pdf")):
item.add_file(path, name=f"document-{index}")
item.save()
Email triggering
Since a process can be started in Control Room by sending an email, the payload
and files can contain the email metadata, text, and possible attached files.
This requires the Parse email
configuration option to be enabled.
The input work item in this library has a helper method email()
, which can
be used to parse it into a typed container:
item = workitems.inputs.current
email = item.email()
print("Email sent by:", email.from_.address)
print("Email subject:", email.subject)
payload = json.loads(email.text)
print("Received JSON payload:", payload)
To learn more about email triggering, see the docs page.
Local development
Using the VSCode extension
If you are developing in VSCode with the Robocorp Code extension, you can utilize the built in local development features described in the Developing with work items locally section of the Using work items development guide.
This allows you to develop and test your work items before deploying to Control Room.
Using a custom editor
It's also possible to develop locally with a custom editor, but it requires some configuration.
To enable the development mode for the library, you should set the environment
variable RC_WORKITEM_ADAPTER
with the value FileAdapter
. This tells the
library to use local files for simulating input and output queues for work
items, in the form of JSON files.
The environment variables RC_WORKITEM_INPUT_PATH
and RC_WORKITEM_OUTPUT_PATH
are also required, and should contain the paths to the input and output JSON
files. The output file will be created by the library, but the input file
should be created manually.
An example of an input file with one work item:
[
{
"payload": {
"variable1": "a-string-value",
"variable2": ["a", "list", "value"]
},
"files": {
"file1": "path/to/file.ext"
}
}
]
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for robocorp_workitems-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c6eff85720d38c14531fd9e143a8d931513fe035ea39d191b2813548669eb038 |
|
MD5 | 3bb02341999249d0ba5c42f1a88036a5 |
|
BLAKE2b-256 | 68be6b8d3443fa11e87fbfec5bd503be990257b500d00686a06578c806d3a836 |