robocorp-workitems

module robocorp.workitems

Variables

  • inputs
  • outputs

Functions

Class Input

Container for an input work item.

An input work item can contain arbitrary JSON data in the payload section, and optionally attached files that are stored in Control Room.

Each step run of a process in Control Room has at least one input work item associated with it, but the step's input queue can have multiple input items in it.

There can only be one input work item reserved at a time. To reserve the next item, the current item needs to be released as either passed or failed.

__init__

Link to source

__init__(adapter: BaseAdapter, item_id: str)

Properties

  • exception

Current work item exception if any.

  • files

Names of attached files.

  • id

Current ID for work item.

  • outputs

Child output work items.

  • parent_id

Current parent work item ID (output only).

  • payload

Current JSON payload.

  • released

Is the current item released.

  • saved

Is the current item saved.

  • state

Current release state.

Methods

add_file

Attach a file from the local machine to the work item.

Note: Files are not uploaded until the item is saved.

Args:

  • path: Path to attached file
  • name: Custom name for file in work item

Returns: Resolved path to added file

Link to source

add_file(path: Union[Path, str], name: Optional[str] = None) → Path

add_files

Attach files from the local machine to the work item that match the given pattern.

Note: Files are not uploaded until the item is saved.

Args:

  • pattern: Glob pattern for attached file paths

Returns: List of added paths

Link to source

add_files(pattern: Union[Path, str]) → list[Path]

create_output

Create an output work item that is a child of this item.

Link to source

create_output() → Output

done

Mark this work item as done, and release it.

Link to source

done()

email

Parse an email attachment from the work item.

Args:

  • html: Parse the HTML content into the html attribute
  • encoding: Text encoding of the email
  • ignore_errors: Ignore possible parsing errors from Control Room

Returns: An email container with metadata and content

Raises:

  • ValueError: No email attached or content is malformed

Link to source

email(html=True, encoding='utf-8', ignore_errors=False) → Optional[Email]

fail

Mark this work item as failed, and release it.

Args:

  • exception_type: Type of failure (APPLICATION or BUSINESS)
  • code: Custom error code for the failure
  • message: Human-readable error message

Link to source

fail( exception_type: Union[ExceptionType, str] = <ExceptionType.APPLICATION: 'APPLICATION'>, code: Optional[str] = None, message: Optional[str] = None )

get_file

Download file with given name.

If a path is not defined, uses the Robot root or current working directory.

Args:

  • name: Name of file
  • path: Path to created file

Returns: Path to created file

Link to source

get_file(name: str, path: Optional[Path, str] = None) → Path

get_files

Download all files attached to this work item that match the given pattern.

If a path is not defined, uses the Robot root or current working directory.

Args:

  • pattern: Glob pattern for file names
  • path: Directory to store files in

Returns: List of created file paths

Link to source

get_files(pattern: str, path: Optional[Path, str] = None) → list[Path]

load

Load work item payload and file listing from Control Room.

Link to source

load() → None

remove_file

Remove attached file with given name.

Note: Files are not removed from Control Room until the item is saved.

Args:

  • name: Name of file
  • missing_ok: Do nothing if given file does not exist

Link to source

remove_file(name: str, missing_ok: bool = False)

remove_files

Remove attached files that match the given pattern.

Note: Files are not removed from Control Room until the item is saved.

Args:

  • pattern: Glob pattern for file names

Returns: List of matched names

Link to source

remove_files(pattern: str) → list[str]

save

Save the current input work item.

Updates the work item payload and adds/removes all pending files.

Note: Modifying input work items is not recommended, as it will make traceability after execution difficult, and potentially makethe process behave in unexpected ways.

Link to source

save()

Class Inputs

Inputs represents the input queue of work items.

It can be used to reserve and release items from the queue, and iterate over them.

Properties

  • current

The current reserved input item.

  • released

A list of inputs reserved and released during the lifetime of the library.

Methods

reserve

Reserve a new input work item.

There can only be one item reserved at a time.

Returns: Input work item

Raises:

  • RuntimeError: An input work item is already reservedworkitems.EmptyQueue: There are no further items in the queue

Link to source

reserve() → Input

Class Output

Container for an output work item.

Created output items are added to an output queue, and released to the next step of a process when the current run ends.

Note: An output item always has an input item as a parent, which is used for traceability in a work item's history.

__init__

Link to source

__init__(adapter: BaseAdapter, parent_id: str)

Properties

  • files

Names of attached files.

  • id

Current ID for work item.

  • parent_id

Current parent work item ID (output only).

  • payload

Current JSON payload.

  • saved

Is the current item saved.

Methods

add_file

Attach a file from the local machine to the work item.

Note: Files are not uploaded until the item is saved.

Args:

  • path: Path to attached file
  • name: Custom name for file in work item

Returns: Resolved path to added file

Link to source

add_file(path: Union[Path, str], name: Optional[str] = None) → Path

add_files

Attach files from the local machine to the work item that match the given pattern.

Note: Files are not uploaded until the item is saved.

Args:

  • pattern: Glob pattern for attached file paths

Returns: List of added paths

Link to source

add_files(pattern: Union[Path, str]) → list[Path]

load

Load work item payload and file listing from Control Room.

Link to source

load() → None

remove_file

Remove attached file with given name.

Note: Files are not removed from Control Room until the item is saved.

Args:

  • name: Name of file
  • missing_ok: Do nothing if given file does not exist

Link to source

remove_file(name: str, missing_ok: bool = False)

remove_files

Remove attached files that match the given pattern.

Note: Files are not removed from Control Room until the item is saved.

Args:

  • pattern: Glob pattern for file names

Returns: List of matched names

Link to source

remove_files(pattern: str) → list[str]

save

Save the current work item.

Updates the work item payload and adds/removes all pending files.

Link to source

save()

Class Outputs

Outputs represents the output queue of work items.

It can be used to create outputs and inspect the items created during the execution.

Properties

  • last

The most recently created output work item, or None.

Methods

create

Create a new output work item, which can have both a JSON payload and attached files.

Creating an output item requires an input to be currently reserved.

Args:

  • payload: JSON serializable data (dict, list, scalar, etc.)
  • files: List of paths to files or glob pattern
  • save: Immediately save item after creation

Raises:

  • RuntimeError: No input work item reserved

Link to source

create( payload: Optional[dict[str, Any], list[Any], str, int, float, bool] = None, files: Optional[Path, str, list[Union[Path, str]]] = None, save: bool = True ) → Output

Exceptions

ApplicationException

An exception that can be raised to release an input work item with an APPLICATION exception type.

__init__

Link to source

__init__(message: Optional[str] = None, code: Optional[str] = None)

BusinessException

An exception that can be raised to release an input work item with a BUSINESS exception type.

__init__

Link to source

__init__(message: Optional[str] = None, code: Optional[str] = None)

EmptyQueue

Raised when trying to load an input item and none available.

Enums

ExceptionType

Failed work item error type.

Values

  • BUSINESS = BUSINESS
  • APPLICATION = APPLICATION

State

Work item state, after release.

Values

  • DONE = COMPLETED
  • FAILED = FAILED