Work Items

2 minute readReference
On this page


Retrieves waiting items for the current user or user specified with userName, subject to optionally supplied filters.

Arguments Descriptions


(Optional) A list of zero or more filter criteria definitions used to define work items to find. Each element of the filter list is a hash reference containing one filter criterion. You may specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the CloudBees CD/RO Perl API. For a sample filter, see Filters below. Two types of filters:

  • Property filters are used to select work items based on the value of the object’s intrinsic or custom property.

  • Boolean filters ("and", "or", "not") are used to combine one or more filters using Boolean logic.

Each property filter consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by CloudBees CD/RO or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property. Property filter operators are:

between (2 operands) contains (1) equals (1) greaterOrEqual (1) greaterThan (1) in (1) lessOrEqual (1) lessThan (1) like (1) notEqual (1) notLike (1) isNotNull (0) isNull (0)

A Boolean filter is a Boolean operator and an array of one or more filters that are operands. Each operand can be either a property filter or a Boolean filter. Boolean operators are:

not (1 operand) and (2 or more operands) or  (2 or more operands)

Argument type: Collection


(Optional) Get all waiting items for specified user. If not supplied, items for current user are returned.

Argument type: String

Positional arguments



There are different type of work items in the system that can wait for user interaction, including:

  • Approval gate rules and manual task gate rules (tasks with flowStateType = manual )

  • Manual tasks with `errorHandling ` = `retryOnError ` and `retryType ` = `manual `

  • Manual process steps ( processStepType ` = `manual ) waiting for manual retry job steps ( outcomeReasonCode ` = `WAIT_FOR_MANUAL_RETRY )

  • Manual transitions for workflow tasks—only for owner user if it’s not a project

Returns a set of all WorkItem objects for the current or specified user. If there are no items, NULL is returned.

=== Filters

Use one or more filters to return specific types of waiting items. For example, below is a filter to return all manual or waiting for manual retry `jobStep ` objects.

[ [ { "operation":"getWorkItems", "parameters":{ "filter":{ "operator":"and", "filter":[ { "operator":"equals", "propertyName":"waitingEntityType", "operand1":"flowRuntimeState" }, { "operator":"equals", "propertyName":"projectName", "operand1":"Default" }, { "operator":"or", "filter":[ { "operator":"equals", "propertyName":"gateType", "operand1":"PRE" }, { "operator":"equals", "propertyName":"gateType", "operand1":"POST" } ] } ] } }, "requestId":"321" } ], { } ]


syntax: $cmdr->getWorkItems({<optionals>});


$cmdr->getWorkItems({userName => "admin"});


syntax: ectool getWorkItems [optionals]


ectool getWorkItems --userName admin