Skip to main content

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

robocorp_workitems-1.1.0.tar.gz (17.0 kB view details)

Uploaded Source

Built Distribution

robocorp_workitems-1.1.0-py3-none-any.whl (18.3 kB view details)

Uploaded Python 3

File details

Details for the file robocorp_workitems-1.1.0.tar.gz.

File metadata

  • Download URL: robocorp_workitems-1.1.0.tar.gz
  • Upload date:
  • Size: 17.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.10.6 Linux/5.15.0-1039-azure

File hashes

Hashes for robocorp_workitems-1.1.0.tar.gz
Algorithm Hash digest
SHA256 8a439ab57eadd2668476298b4d7faeb7538f589a2a2576b50fa3736e6a2ba1eb
MD5 ce2f0af4e52dd1ed25ba02c84d59b0ba
BLAKE2b-256 df4db64262ae4268ab673a458e86d54d5b9713024c26481f13df3502f3d3718a

See more details on using hashes here.

Provenance

File details

Details for the file robocorp_workitems-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: robocorp_workitems-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 18.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.10.6 Linux/5.15.0-1039-azure

File hashes

Hashes for robocorp_workitems-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c6eff85720d38c14531fd9e143a8d931513fe035ea39d191b2813548669eb038
MD5 3bb02341999249d0ba5c42f1a88036a5
BLAKE2b-256 68be6b8d3443fa11e87fbfec5bd503be990257b500d00686a06578c806d3a836

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page