The 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.

Attributes

The task supports Team Build Attributes, Build Extensions Debugging Attributes, Build Extensions General Attributes, as well as, its own task specific attributes. Click on a link for more information on the common attributes.

The following table describes the task specific attributes for the task:

Task Specific Attributes
Attribute	Description	Required
ordered	Specifies whether or not to order the output. If `true`, result will be ordered. If `false` or not specified, result will be unordered.	No
processAreaName	Name of the project which contains the work item definitions.	Yes
property	Name of the Ant property in which to store the result.	Yes

Operator Elements

Operator elements are specified within the 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 may be specified, but both an AND and an OR may be specified on a single call. Operator elements have no attributes.

Query Elements

Query elements are specified within AND or OR elements and are used to control what work items are returned. The following table describes the valid Query Elements:

Name	Attributes				Description
Name	value	operator	custom	project	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					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 is a 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 group name	EQUALS* NOT_EQUALS			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	EQUALS* 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			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 whose value is equal/notequal to the specified team area value.
dueDate	date	EQUALS* NOT_EQUALS AFTER BEFORE			All work items due on, before, or after the specified date.
duration	duration	EQUALS* NOT_EQUALS GREATER GREATER_OR_EQUALS SMALLER SMALLER_OR_EQUALS			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_EQUALS		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.
ownedBy	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 a synonym for the resolver attribute.
resolver	contributor	EQUALS* 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. This 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_EQUALS 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 that 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 a synonym for the state attribute.
summary	string	EQUALS* NOT_EQUALS CONTAINS NOT_CONTAINS STARTSWITH ENDSWITH			All work items with the same summary text as specified.
tag	string				All work items with the specified tag.
target	iteration	EQUALS* 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 end on, before, or after the specified date.
targetStartDate	date	EQUALS* NOT_EQUALS AFTER BEFORE			All work items planned for any 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	EQUALS* 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			All work items with the specified work item id.

Query Element Notes

Blank cells signify that no value is required or allowed.
Default operator values 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 is specified as a person’s EWM userid, which is normally an email address.
A date value is specified in the form yyyy-MM-dd.
A duration value is specified in microseconds.
An enumeration value is specified with the literal value of the choice, not the ID value.
A deliverable value is specified as the name of a Release as defined in the project area Releases tab.
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 must have access to the specified group to run a query using the contextId attribute.

Notes

The task uses the default maximum query result set size to limit the number of items returned. The default is set in the CCM server "Advanced Properties - Administration - Engineering Workflow Management" page, under the "WorkItem Queries" section, with the "Maximum Query Result Set Size" property.

Examples

Defects

Find all Defects in project "Project One" that belong to "user1" and "user2" and put the work item IDs in property "my.property" in ascending order:

<target name="task" if="run.task">
  
  <xt:queryWorkItem
      repositoryAddress="${repositoryAddress}"
      userId="${userId}"
      passwordFile="${passwordFile}"
      property="my.property"
      processAreaName="Project One"
      ordered="true"
    >
    <xt:and>
      <xt:projectArea value="Project One"/>
      <xt:type value="defect"/>
    </xt:and>
    <xt:or>
      <xt:owner value="user1"/>
      <xt:owner value="user2"/>
    </xt:or>
  </xt:queryWorkItem>
  
</target>

APAR

Find an APAR work item whose APAR number is PI12345 and put the work item ID in property "my.property":

<target name="task" if="run.task">
  
  <xt:queryWorkItem
      repositoryAddress="${repositoryAddress}"
      userId="${userId}"
      passwordFile="${passwordFile}"
      property="my.property"
      processAreaName="Project One"
    >
    <xt:and>
      <xt:type value="com.ibm.sport.rtc.workItem.type.apar"/>
      <xt:customString value="PI12345" custom="com.ibm.sport.rtc.workItem.attribute.apar.aparNum"/>
    </xt:and>
  </xt:queryWorkItem>
  
</target>

getTaskNameHdr()