queryWorkItem

The queryWorkItem task finds and returns EWM work item IDs. The process to find the work items uses the standard query interface. The configuration of the query is handled by Operator Elements and Query Elements. Operator elements control the logic of the query; grouping query elements to be and'ed or or'ed. Query elements control work item filtering. The IDs of the work items found by the query are returned in a comma separated list in the specified ant property.

The following table describes queryWorkItem attributes.

Attribute Description Required

repositoryAddress

Address of the team repository to use. The value of this attribute is typically ${repositoryAddress} because that property is built-in when using the Jazz™ Build Engine.

Yes

userId

User ID for authentication to the repository. Requires password or passwordFile to be set.

Yes

certificateFile

The path to the file that contains the user's login certificate for authentication. Requires password or passwordFile to be set. You can specify certificateFile or repositoriesFile, but not both.

No

password

Password for the user ID for authentication to the repository. Either password or passwordFile can be provided, but not both.

No

passwordFile

The password file to use for authentication to the connection. You can create a suitable password file by invoking the Jazz Build Engine with the -createPasswordFile argument. You can only specify one password file. Either password or passwordFile can be provided, but not both.

No

smartCard

Whether to use the connected smart card for authentication (true or false). Requires userId to be set. For more information about smart card authentication, see Connecting to repositories and project areas.

No

failOnError

If true (the default), the task fails if it encounters an error. If false, some errors are ignored and the task is completed.

No

verbose

Specifies more message output. The default is false.

No

ordered

Specified whether to order the output. If the value is true, result will be ordered. If false, or not specified, result will be unordered.

No

processAreaName

The name of the EWM process area where the build is defined. The process area name can be a combination of elements. For example, if a process area is a team area, the process area name is the concatenation of three elements: the process area, a backslash (/) and the team area.

No

property

The name of the ant property in which to return the workspace name.

Yes

Operator Elements

Operator elements are specified in the queryWorkItem element. The <and> element supports and'ed query elements. The <or> element supports or'ed query elements. One operator element is required. Only one <and> or <or> can be specified, but both an <and> and an <or> can be specified on a single call. Operator elements have no attributes.

Query Elements

Query elements are specified in <and> or <or> elements and are used to control what work items are returned.

The following table describes the the valid Query Elements.

Name

value operator custom projectArea

Description

approvalsApproved         All work items with an approval approved.
approvalsApprovedBy contributor       All work items with an approval approved by the specified user.
approvalsPending         All work items with an approval pending.
approvalsPendingBy contributor       All work items with an approval pending for the specified user.
approvalsRejected contributor       All work items with an approval rejected.
approvalsRejectedBy contributor       All work items with an approval rejected by the specified user.
approver contributor       All work items with an approval defined for the specified user. This includes approved, pending, and rejected items.
archived         All work items that have been archived. This is included for compatibility purposes, since there is no real archived state for work items.
authoredBy contributor       All work items that have a comment authored by the specified user. This ia synonym for the comments attribute.
category category

EQUALS*

NOT_EQUALS

    All work items filed against the specified category.
comments contributor       All work items that have a comment authored by the specified user.
contextId

access

groupname

EQUALS*

NOT_EUQALS

    All work items assigned to the specified access group.
correctedEstimate duration

EQUALS*

NOT_EQUALS

GREATER

GREATER_OR_EQUALS

SMALLER

SMALLER_OR_EQUALS

    All work items that match the corrected estimate value and operator.
createdBy contributor

EUQALS*

NOT_EQUALS

    All work items created by the specified user. This is a synonym for the creator attribute.
creationDate date

EQUALS*

NOT-EQUALS

AFTER

BEFORE

    All work items created on, before, or after the specified date.
creator contributor

EQUALS*

NOT_EQUALS

required   All work items created by the specified user.
customBoolean boolean

EQUALS*

NOT_EQUALS

required   All work items that have the custom attribute defined and whose value is equal/notequal to the specified Boolean (true/false) value.
customContributor contributor

EQUALS*

NOT_EQUALS

required   All work items that have the custom attribute defined and whose value is equal/notequal to the specified user.
customDate date

EQUALS*

NOT_EQUALS

AFTER

BEFORE

required   All work items that have the custom attribute defined and whose value is on, before, or after the specified date.
customEnumeration

custom

enumeration

literal

EQUALS*

NOT_EQUALS

required   All work items that have the custom attribute defined and whose value is equal/notequal to the specified literal.
customInteger integer

EQUALS*

NOT_EQUALS

GREATER

GREATER_OR_EQUALS

SMALLER

SMALLER_OR_EQUALS

required   All work items that have the custom attribute defined and whose value is equal/notequal to the specified integer value.
customLong long

EQUALS*

NOT_EQUALS

GREATER

GREATER_OR_EQUALS

SMALLER

SMALLER_OR_EQUALS

required   All work items that have the custom attribute defined and whose value is equal/notequal to the specified long value.
customProjectArea

project

name

EQUALS*

NOT_EQUALS

required   All work items that have the custom attribute defined and whose value is equal/notequal to the specified project area value.
customString string

EQUALS*

NOT_EQUALS

CONTAINS

NOT_CONTAINS

STARTS_WITH

ENDS_WITH

required   All work items that have the custom attribute defined and whose value is equal/notequal to the specified string.
customTeamArea

team area

name

EQUALS*

NOT_EQUALS

required   All work items that have the custom attribute defined and shose value is equal/notequal to the specified team area value.
dueDate date

EUQALS*

NOT_EQUALS

AFTER

BEFORE

    All work items due on , before, or after the specified date.
duration duration

EUQALS*

NOTE_EQUALS

GREATER

GREATER_OR_EQUALS

SMALLER

SMALLER_OR_EUQALS

    All work items that match the duration value and operator.
estimate duration

EQUALS*

NOT_EQUALS

GREATER

GREATER_OR_EQUALS

SMALLER

SMALLER_OR_EQUALS

    All work items that match the duration value and operator. This is a synonym for the duration attribute.
foundIn deliverable

EQUALS*

NOT_EUQALS

  optional All work items that match the deliverable value specified.
modified date

EQUALS*

NOT_EQUALS

AFTER

BEFORE

    All work items modified on, before, or after the specified date.
modifiedBy contributor

EQUALS*

NOT_EQUALS

    All work items modified by the specified user.
owndedBy contributor

EQUALS*

NOT_EQUALS

    All work items owned by the specified user.
owner contributor

EQUALS*

NOT_EQUALS

    All work items owned by the specified user.
plannedFor iteration

EQUALS*

NOT_EQUALS

  optional All work items planned for the specified iteration. This is a synonym for the target attribute.
plannedForEndDate date

EQUALS*

NOT_EQUALS

AFTER

BEFORE

    All work items planned for any iteration end on , before, or after the specified date.
plannedForStartDate date

EQUALS*

NOT_EQUALS

AFTER

BEFORE

    All work items planned for any iteration started on, before, or after the specified date.
priority

priority

enumeration

literal

EQUALS*

NOT_EQUALS

    All work items with the specified priority setting.
projectArea

project

name

EQUALS*

NOT_EQUALS

    All work items in the specified project area.
resolution resolution id

EQUALS*

NOT_EQUALS

    All work items with the specified resolution ID. For example, the following is the id of the Action item "Follow-on" resolution: com.ibm.team.rtc.workflow.action.resolution.r7.
resolutionDate date

EQUALS*

NOT_EQUALS

AFTER

BEFORE

    All work items resolved on, before, or after the specified date.
resolvedBy contributor

EQUALS*

NOT_EQUALS

    All work items resolved by the specified user. This is synonym for the resolver attribute.
resolver contributor

EUQALS*

NOT_EQUALS

    All work items resolved by the specified user.
restrictedAccess

access

group name

EQUALS*

NOT_EQUALS

    All work items assigned to the specified access group. Thi is a synonym for the contextid attribute.
severity

severity

enumeration

literal

EQUALS*

NOT_EQUALS

    All work items with the specified severity setting.
startDate date

EQUALS*

NOT_EUQALS

AFTER

BEFORE

    All work items started on, before, or after the specified date.
state state id

EQUALS

NOT_EQUALS

    All work items with the specified state id.
Note: The primary work items (defect, task) use only the number of the state, i.e. 2 instead of s2 for In-progress.
status state id

EQUALS*

NOT_EQUALS

    All work items with the specified state id. This is asynonym for the state attribute.
summary string

EQUALS *

NOT_EQUALS

CONTAINS

NOT_CONTAINS

STARTS_WITH

ENDS_WITH

    All work item with the same summary text as specified.
tags string       All work items with the specified tag.
target iteration

EUQALS*

NOT_EQUALS

  optional All work items planned for the specified iteration.
targetEndDate date

EQUALS*

NOT_EQUALS

AFTER

BEFORE

    All work items planned for any iteration ended on, before, or after the specified date.
targetStartDate date

EQUALS8

NOT_EQUALS

AFTER

BEFORE

    All work items planned for nay iteration started on, before, or after the specified date.
teamArea

team area

name

EQUALS*

NOT_EQUALS

  optional All work items found in the specified team area.
timeSpent duration

EUQALS*

NOT_EQUALS

GREATER

GREATER_OR_EQUALS

SMALLER

SMALLER_OR_EQUALS

    All work items that match the time spent value and operator.
type work item id

EQUALS*

NOT_EQUALS

    k item type for the work item.
Note:
  • Blank cells signify that no value is required.
  • Default options are labeled with an asterisk (*).
  • A category is the name of a Filed Against category defined in the project area Work Items Categories tab.
  • A contributor value is specified as a person's EWM userid, which is normally an intranet id or email address.
  • A date value is specified in the form yyyy-MM-dd.
  • A deliverable value is specified as the name of a Release as defined in the project area Release tab.
  • A duration value is specified in microseconds.
  • An enumeration value is specified with the literal value of the choice, not the ID value.
  • A resolution ID value is specified as the ID of the resolution value as specified in the process definition.
  • All projectArea attributes are optional. If not specified, the projectArea specified on the getWorkitemById element will be used.
  • You need to have access to the specified access group to run a query using the contextId attribute.

Example

  • Fina all Defects in project "Project One" that belong to user1 and user2 and put the work item IDs in property "my.property" in an ascending order
    <wi:queryWorkItem
    	repositoryAddress="${repositoryAddress}"
    	userID="${userId}"
    	passwordFile="${passwordFile}"
    	property="my.property"
    	processAreaName="Project One"
    	ordered="true">
    	<wi:and>
    		<wi:projectArea value="Project One"/>
    		<wi:type value="defect"/>
    	</wi:and>
    	<wi:or>
    		<wi:owner value="user1@us.ibm.com"/ (mailto:djreilly@us.ibm.com"/}>
    		<wi:owner value="user2@us.ibm.com"/ (mailto:tlk@us.ibm.com"/}>
    	</wi:or>
    </wi:queryWorkItem>
  • Find an APAR work item whose APAR number is PI12345 and put the work item ID in property "my.property"
    <wi:queryWorkItem
    	repositoryAddress="${repositoryAddress}"
    	userId="${userId}"
    	passwordFile="${passwordFile}"
    	property="my.property"
    	processAreaName="Project One">
    	<wi:and>
    		<wi:type value="com.ibm.sport.rtc.workItem.type.apar"/>
    		<wi:customString value="PI12345" custom="com.ibm.sport.rtc.workItem.attribute.apar.aparNum"/>
    	</wi:and>
    </wi:queryWorkItem>

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki