RPA.Robocorp.WorkItems library | Robocorp documentation

RPA.Robocorp.WorkItems

Add Work Item File

Add given file to work item.

Arguments

Argument	Type	Default value	Description
path		null	Path to file on disk
name		None	Destination name for file. If not given, current name of local file is used.

param path:	Path to file on disk
param name:	Destination name for file. If not given, current name of local file is used.

NOTE: Files are not uploaded before work item is saved

Examples

*** Tasks *** Example task Add work item file output.xls Save Work Item

Add Work Item Files

Add all files that match given pattern to work item.

Arguments

Argument	Type	Default value	Description
pattern		null	Path wildcard pattern

param pattern:	Path wildcard pattern

Examples

*** Tasks *** Example task Add work item files %{ROBOT_ROOT}/generated/*.csv Save Work Item

Clear Work Item

Remove all data and files in the current work item.

Examples

*** Tasks *** Clearing a work item Clear work item Save work item

from RPA.Robocorp.WorkItems import WorkItems wi = WorkItems() wi.get_input_work_item() wi.clear_work_item() wi.save_work_item()

Create Output Work Item

Create a new output work item with optional variables and files.

Arguments

Argument	Type	Default value	Description
variables	dict, None	None	Optional dictionary with variables to be set into the new output work item.
files	str, List[str], None	None	Optional list or comma separated paths to files to be included into the new output work item.
save	bool	False	Automatically call Save Work Item over the newly created output work item.

An output work item is always created as a child for an input item, therefore a non-released input is required to be loaded first. All changes to the work item are done locally and are sent to the output queue after the keyword Save Work Item is called only, except when save is True.

param variables:
	Optional dictionary with variables to be set into the new output work item.
param files:	Optional list or comma separated paths to files to be included into the new output work item.
param save:	Automatically call `Save Work Item` over the newly created output work item.
returns:	The newly created output work item object.

Examples

Robot Framework

*** Tasks *** Create output items with variables then save ${customers} = Load customer data FOR ${customer} IN @{customers} Create Output Work Item Set Work Item Variables id=${customer.id} ... name=${customer.name} Save Work Item END Create and save output items with variables and files in one go ${customers} = Load customer data FOR ${customer} IN @{customers} &{customer_vars} = Create Dictionary id=${customer.id} ... name=${customer.name} Create Output Work Item variables=${customer_vars} ... files=devdata${/}report.csv save=${True} END

Python

from RPA.Robocorp.WorkItems import WorkItems wi = WorkItems() wi.get_input_work_item() customers = wi.get_work_item_variable("customers") for customer in customers: wi.create_output_work_item(customer, save=True)

Delete Work Item Variables

Delete variable(s) from the current work item.

Arguments

Argument	Type	Default value	Description
names		null	Names of variables to remove
force		True	Ignore variables that don't exist in work item

param names:	Names of variables to remove
param force:	Ignore variables that don't exist in work item

Examples

*** Tasks *** Example task Delete work item variables username email Save Work Item

For Each Input Work Item

Run a keyword or function for each work item in the input queue.

Arguments

Argument	Type	Default value	Description
keyword_or_func	str, Callable	null	The RF keyword or Py function you want to map through all the work items
args		null	Variable list of arguments that go into the called keyword/function
items_limit	int	0	Limit the queue item retrieval to a certain amount, otherwise all the items are retrieved from the queue until depletion
return_results	bool	True	Collect and return a list of results given each keyword/function call if truthy
kwargs		null	Variable list of keyword arguments that go into the called keyword/function

Automatically collects and returns a list of results, switch return_results to False for avoiding this.

param keyword_or_func:
	The RF keyword or Py function you want to map through all the work items
param args:	Variable list of arguments that go into the called keyword/function
param kwargs:	Variable list of keyword arguments that go into the called keyword/function
param items_limit:
	Limit the queue item retrieval to a certain amount, otherwise all the items are retrieved from the queue until depletion
param return_results:
	Collect and return a list of results given each keyword/function call if truthy

Examples

*** Tasks *** Log Payloads @{lengths} = For Each Input Work Item Log Payload Log Payload lengths: @{lengths} *** Keywords *** Log Payload ${payload} = Get Work Item Payload Log To Console ${payload} ${len} = Get Length ${payload} [Return] ${len}

import logging from RPA.Robocorp.WorkItems import WorkItems library = WorkItems() def log_payload(): payload = library.get_work_item_payload() print(payload) return len(payload) def log_payloads(): library.get_input_work_item() lengths = library.for_each_input_work_item(log_payload) logging.info("Payload lengths: %s", lengths) log_payloads()

Get Current Work Item

Get the currently active work item.

The current work item is used as the target by other keywords in this library.

Keywords Get Input Work Item and Create Output Work Item set the active work item automatically, and return the created instance.

With this keyword the active work item can be retrieved manually.

Examples

*** Tasks *** Example task ${input} = Get Current Work Item ${output} = Create Output Work Item Set Current Work Item ${input}

Get Input Work Item

Load the next work item from the input queue, and set it as the active work item.

Arguments

Argument	Type	Default value	Description
_internal_call	bool	False

Each time this is called, the previous input work item is released (as DONE) prior to reserving the next one. If the library import argument autoload is truthy (default), this is called automatically when the Robot Framework suite starts.

Get Work Item File

Get attached file from work item to disk. Returns the absolute path to the created file.

Arguments

Argument	Type	Default value	Description
name		null	Name of attached file
path		None	Destination path of file. If not given, current working directory is used.

param name:	Name of attached file
param path:	Destination path of file. If not given, current working directory is used.

Examples

*** Tasks *** Example task ${path}= Get work item file input.xls Open workbook ${path}

Get Work Item Files

Get files attached to work item that match given pattern. Returns a list of absolute paths to the downloaded files.

Arguments

Argument	Type	Default value	Description
pattern		null	Filename wildcard pattern
dirname		None	Destination directory, if not given robot root is used

param pattern:	Filename wildcard pattern
param dirname:	Destination directory, if not given robot root is used

Examples

*** Tasks *** Example task ${paths}= Get work item files customer_*.xlsx FOR ${path} IN @{paths} Handle customer file ${path} END

Get Work Item Payload

Get the full JSON payload for a work item.

NOTE: Most use cases should prefer higher-level keywords.

Examples

*** Tasks *** Example task ${payload}= Get work item payload Log Entire payload as dictionary: ${payload}

Get Work Item Variable

Return a single variable value from the work item, or default value if defined and key does not exist.

Arguments

Argument	Type	Default value	Description
name		null	Name of variable
default			Default value if key does not exist

If key does not exist and default is not defined, raises KeyError.

param name:	Name of variable
param default:	Default value if key does not exist

Robot Framework Example:

*** Tasks *** Using a work item ${username}= Get work item variable username default=guest

Python Example:

from RPA.Robocorp.WorkItems import WorkItems wi = WorkItems() wi.get_input_work_item() customers = wi.get_work_item_variable("customers") print(customers)

Get Work Item Variables

Read all variables from the current work item and return their names and values as a dictionary.

Robot Framework Example:

*** Tasks *** Example task ${variables}= Get work item variables Log Username: ${variables}[username], Email: ${variables}[email]

Python Example:

from RPA.Robocorp.WorkItems import WorkItems wi = WorkItems() wi.get_input_work_item() input_wi = wi.get_work_item_variables() print(input_wi["username"]) print(input_wi["email"])

List Work Item Files

List the names of files attached to the current work item.

Examples

*** Tasks *** Example task ${names}= List work item files Log Work item has files with names: ${names}

List Work Item Variables

List the variable names for the current work item.

Examples

*** Tasks *** Example task ${variables}= List work item variables Log Available variables in work item: ${variables}

Release Input Work Item

Release the lastly retrieved input work item and set its state.

Arguments

Argument	Type	Default value	Description
state	State, str	null	The status on the last processed input work item
exception_type	Error, str, None	None	Error type (BUSINESS, APPLICATION). If this is not specified, then the cloud will assume UNSPECIFIED
code	str, None	None	Optional error code identifying the exception for future filtering, grouping and custom retrying behaviour in the cloud
message	str, None	None	Optional human-friendly error message supplying additional details regarding the sent exception
_auto_release	bool	False

This can be released with DONE or FAILED states. With the FAILED state, an additional exception can be sent to Control Room describing the problem that you encountered by specifying a type and optionally a code and/or message. After this has been called, no more output work items can be created unless a new input work item has been loaded again.

param exception_type:
param state:	The status on the last processed input work item
	Error type (BUSINESS, APPLICATION). If this is not specified, then the cloud will assume UNSPECIFIED
param code:	Optional error code identifying the exception for future filtering, grouping and custom retrying behaviour in the cloud
param message:	Optional human-friendly error message supplying additional details regarding the sent exception

Examples

*** Tasks *** Example task Login into portal ${user} = Get Work Item Variable user ${doc} = Get Work Item Variable doc TRY Login Keyword ${user} Upload Doc Keyword ${doc} EXCEPT Login Failed Release Input Work Item FAILED ... exception_type=APPLICATION ... code=LOGIN_PORTAL_DOWN ... message=Unable to login, retry again later. EXCEPT Format Error AS ${err} ${message} = Catenate ... Document format is not correct and cannot be uploaded. ... Correct the format in this work item and try again. ... Full error message received: ${err} Release Input Work Item FAILED ... exception_type=BUSINESS ... code=DOC_FORMAT_ERROR ... message=${message} END

from RPA.Robocorp.WorkItems import State, WorkItems library = WorkItems() def process_and_set_state(): library.get_input_work_item() library.release_input_work_item(State.DONE) print(library.current.state) # would print "State.DONE" process_and_set_state()

Remove Work Item File

Remove attached file from work item.

Arguments

Argument	Type	Default value	Description
name		null	Name of attached file
missing_ok		True	Do not raise exception if file doesn't exist

param missing_ok:
param name:	Name of attached file
	Do not raise exception if file doesn't exist

NOTE: Files are not deleted before work item is saved

Examples

*** Tasks *** Example task Remove work item file input.xls Save Work Item

Remove Work Item Files

Removes files attached to work item that match the given pattern.

Arguments

Argument	Type	Default value	Description
pattern		null	Filename wildcard pattern
missing_ok		True	Do not raise exception if file doesn't exist

param missing_ok:
param pattern:	Filename wildcard pattern
	Do not raise exception if file doesn't exist

Examples

*** Tasks *** Example task Remove work item files *.xlsx Save Work Item

Save Work Item

Save the current data and files in the work item. If not saved, all changes are discarded when the library goes out of scope.

Set Current Work Item

Set the currently active work item.

Arguments

Argument	Type	Default value	Description
item	WorkItem	null

The current work item is used as the target by other keywords in this library.

Keywords Get Input Work Item and Create Output Work Item set the active work item automatically, and return the created instance.

With this keyword the active work item can be set manually.

Robot Framework Example:

*** Tasks *** Creating outputs ${input}= Get Input Work Item ${output}= Create Output Work Item Set current work item ${input}

Python Example:

from RPA.Robocorp.WorkItems import WorkItems wi = WorkItems() parent_wi = wi.get_input_work_item() child_wi = wi.create_output_work_item() wi.set_current_work_item(parent_wi)

Set Task Variables From Work Item

Convert all variables in the current work item to Robot Framework task variables, see variable scopes.

Examples

*** Tasks *** Example task # Work item has variable INPUT_URL Set task variables from work item Log The variable is now available: ${INPUT_URL}

Set Work Item Payload

Set the full JSON payload for a work item.

Arguments

Argument	Type	Default value	Description
payload		null	Content of payload, must be JSON-serializable

param payload:	Content of payload, must be JSON-serializable

NOTE: Most use cases should prefer higher-level keywords. Using this keyword may cause errors when getting the payload via the normal Get work item variable and Get work item variables keywords if you do not set the payload to a dict.

Examples

*** Tasks *** Example task ${output}= Create dictionary url=example.com username=Mark Set work item payload ${output}

Set Work Item Variable

Set a single variable value in the current work item.

Arguments

Argument	Type	Default value	Description
name		null	Name of variable
value		null	Value of variable

param name:	Name of variable
param value:	Value of variable

Robot Framework Example:

*** Tasks *** Example task Set work item variable username MarkyMark Save Work Item

Python Example:

from RPA.Robocorp.WorkItems import WorkItems customers = [{"id": 1, "name": "Apple"}, {"id": 2, "name": "Microsoft"}] wi = WorkItems() wi.get_input_work_item() wi.set_work_item_variable("customers", customers)

Set Work Item Variables

Set multiple variables in the current work item.

Arguments

Argument	Type	Default value	Description
kwargs		null	Pairs of variable names and values

param kwargs:	Pairs of variable names and values

Examples

*** Tasks *** Example task Set work item variables username=MarkyMark email=mark@example.com Save Work Item