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.0.1.tar.gz (16.8 kB view details)

Uploaded Source

Built Distribution

robocorp_workitems-1.0.1-py3-none-any.whl (18.2 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for robocorp_workitems-1.0.1.tar.gz
Algorithm Hash digest
SHA256 457553da66d1a05b1af200313a237ae40742ec075a25af892e222ac743d3bd02
MD5 c603d536dffbc368e0b777302b77fa4b
BLAKE2b-256 61587df2cdfa1d9542d9cf6e8f6d1c3ce1a1ddffed8264d6155b5d5d3e6ecf9f

See more details on using hashes here.

Provenance

File details

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

File metadata

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

File hashes

Hashes for robocorp_workitems-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 75a2331cecd0aac86b9458799ad613b9694da957e717ab01f25af282fec3a237
MD5 7b9a715d051c8c3d29547bd4e51f6cc2
BLAKE2b-256 d8fd74be4b91d3f297b031f0127702391c2fc5f97c2259e890ce33cc7c3da246

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