createWorkItem

The createWorkItem task creates an EWM work item. Store elements designate which attributes to set and the initial attribute value. It creates the specified work item, sets the work item attributes with the specified value, saves the work item, and returns the work item id in the specified property. All required values for the work item must be specified.

The following table describes createWorkItem 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

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.

Yes

property

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

No

typeId

Specifies whether the workItemType is an id. Specify true if the workItemType is an id. Specify false if the workItemType is a label. The default is false.

No

workItemId

The ID of the work item to update.

Yes

Store Elements

Store elements are specified in the createWorkItem element. Store elements designate which work item attributes to set and the attribute values. All store elements are optional. At lease one Store element is required. A name and value is required for each Store element. The name attribute specifies the name of an EWM work item attribute. The value attribute specifies the value of the EWM work item attribute. Some EWM work item attributes have options that are described below.

The following table describes the Name Attributes of Store Element.

Value

Description

Required attributes

Optional attributes

action Request a work flow action for the work item. Work item actions are defined in the process definition work flow for the work item. Specify an action label of an action id. Action labels are displayed in the eclipse client. For example, one of the action labels for a task in "New" state is "Start Working". An action id is the identifier for the action. Action IDs can be found in the process definition. For example, the id for the Task "Start Working " label is "com.ibm.team.workitem.taskWorkflow.action.startWorking". The action specified must be one of the valid actions for the current work item state. value

id

label

approval Adds an approval entry to the work item. Specify an approval name. The approval type is specified with the approval name. The approval type is specified with the approvalType attribute. An approval type is also required. Other approval information can be specified with the optional attributes: approvalDueDate for due date and approvalApprover for the userid of the approver.

value

approvalType

approvalApprover

approvalDueDate

include

remove

attachment Specify the full path tot he name of a local file to attach to the work item. For example, value="D:\rtc\Builds|PI37999.Regtest.Work Items included in build.html". Content encoding defaults to UTF8. Content type defaults to text. value

contentEncoding

contentType

category Specify the full path name to a category defined to project of the work item. Categories and sub-categories are separated by forward slashes: Category/Sub-category. value  
comments Specify comment text in the designated form. To specify links or text formatting use the xmlText option. value

plainText

xmlText

contextId Specify the corrected estimate in duration format. value

msecs

units

custom Specify a custom attribute id and value.

custom

value

All options applicable to the attribute type may be specified.
customBoolean Specify true or false.

custom

value

 
customCategory Specify a category.

custom

value

projectArea
customContributor Specify a userid.

custom

value

email

username

userid

customContributorList Specify a user ID.

custom

value

email

username

userid

include

remove

customDate Specify a date.

custom

value

date

dateTime

dateLong

customDecimal Specify a decimal value.

custom

value

 
CustomDeliverable Specify a deliverable name value.

custom

value

projectArea
CustomDuration Specify a duration value.

custom

value

mess

units

customEnumeration Specify the ID or label of a custom enumeration.

custom

value

id

label

projectArea

customEnumerationList Specify HTML formatted text.
Note: The HTML formatted text can be added with the value attribute or as free form text between start (<store...>) and end (</store>) tages. if free form text is specified, the value attribute is not required.

custom

value

 
customInteger Specify an integer value

custom

value

 
customItem Specify an item and type. An item can be removed by specifying value ="".

custom

value

itemCategory

itemComponent

itemContributor

itemDeliverable

itemIteration

item ProcessArea

itemProjectArea

itemTeamArea

iteamWorkItem

projectArea

customitemList Specify an item and type.

custom

value

itemCategory

itemComponent

itemContributor

itemDeliverable

itemIteration

iteamProcessArea

itemProjectArea

iteamTeamArea

itemWorkItem

include

remove

projectArea

customIteration Specify an iteration name.

custom

value

projectArea
customLong Specify a long integer value.

custom

value

 
customProcessArea Specify the name of a process area defined to EWM. A process area can be removed by specifying value="".

custom

value

 
customProcessAreaList Specify the name of a process area defined to EWM.

custom

value

include

remove

customProjectArea Specify the name of a project area defined to EWM. A project area can be removed by specifying value="".

custom

value

 
customProjectAreaList Specify the name of a projct area defined to EWM.

custom

value

include

remove

customString Specify a string value.

custom

value

 
customStringList Specify a string value.

custom

value

include

remove

customTags Specify a tag string. Multiple tags can be specified in the string by separating each with a comma, such as "tag1, tag2, tag3". Tags can be removed using the replace option. All tags can be removed by specifying ""and replace it with ="true".

custom

value

add

replace

customTeamArea Specify a team area name value.

custom

value

 
customTeamAreaList Specify a team area name value.

custom

value

include

remove

customTimestamp Specify a date.

custom

value

date

dateTime

dateLong

customWiki Specify wiki formatted text.
Note: The wiki formatted text can be added with the value attribute or as free form text between start (<store...>) and end (</store>) tags. if free form text is specified, the value attribute is not required.

custom

value

 
customWorkItem Specify a work item id value. A work item an be removed by specifying value="".

custom

value

 
customWorkItemList Specify a work item id value.

custom

value

include

remove

description Description text in the specified form. To specify links or text formatting options, use the xmlText option.

value

plaintText

xmlText

dueDate Specify the due date. value

date

dateTime

dateLong

duration Specify a duration estimate. value

msecs

unit

estimate Specify the full path name to a category defined to the project. Categories and sub-categories are separated by forward slashes:category/Sub-category. This is a synonym for the category attribute.

value

 
foundIn Specify a deliverable that is defined to the project. Deliverable are defined on the project area in the project area Releases tab.

value

 
link Specify the ID or UUID of the item to link and the type of link to create. A link type is required.

linkType

value

 
modified Specify the modify date. value

date

dateTime

dateLong

modifiedBy Specify the user ID of the modifier value

email

username

userid

modifiedDate Specify the modify date. This synonym for the modified attribute. value

date

dateTime

dateLong

owndedBy Specify the user ID of the owner. This is a synonym for the owner attribute. value

email

username

userid

plannedFor Specify the name of the target iteration. This ia synonym for the target attribute. value userid
priority specify the id or label of a priority enumeration. value

id

label

resolution Specify the work item resolution. Work item resolutions are defined in the process definition work flow for the work item. A resolution label is displayed in the eclipse client resolution drop down menu, which is next to the action frop down menu. For example, one of the resolution labels for a Defect is "Fixed". A resolution id is the identifier for the resolution. The id for the Defect 'Fixed" label is "r2", which must be specified as "2". Normally IDs are fully specified, such as com.ibm.team.rtc.workflow.action.resolution.r1". Only the two character primitive IDs need to be reduced to the number alone. A resolution can only be specified for a work item with resolution defined. The resolution specified must be one of the valid resolutions for the work item. value

id

label

resolutionDate Specify the resolution date. value

date

dateTime

dateLong

resolvedBy Specify the user ID of the resolver. This is a synonym for the resolver attribute. value

email

username

userid

resolver Specify the user ID of the resolver. value

email

username

userid

restrictedAccess Specify the name of an access group or project area to restrict access to the work item. This is a synonym for the contextId attribute. value  
severity Specify the ID or label of a severity enumeration. value

id

label

startDate Specify the start date for the work item. value

date

dateTime

dateLong

subscriber Specify the user ID of the subscriber. If is specified, the user ID will be added to the subscriber list. If remove="true" is specified, the user ID will be deleted from the subscriber list. value

email

username

userid

include

remove

summary Summary text in the specified form. value

plainText

xmlText

tags Specify tags for the work item. Multiple tags can be specified in the string, by separating each with a comma, such as "tag1, tag2, tag3". value

add

replace

target Specify the name of the target iteration. value  
timeSpent Specify the time spent working on the item. value

msecs

untis

type Specify the ID or label of a new work item type for the work item. value

id

label

The following table describes Required Attributes of State Elements.

Name Value Description
approvalType

APPROVAL

REVIEW

VERFICATION

Specify the type of approval to create.
custom attribute id as defined in the process definition for the EWM project. Specifies the id of the custom attribute.
linkType

CHANGE_SET

BLOCKS_WORK_ITEM

DUPLICATE_WORK_ITEM

PARENT_WORK_ITEM

RELATED_WORK_ITEM

RESOLVES_WORK_ITEM

AFFECTED_BY_DEFECT

AFFECTS_PLAN_ITEM

CONTRIBUTES_TO_WORK_ITEM

TRAC KS_WORK_ITEM

Alternate forms:

CHANGE or CHANGESET

BLOCKS

DUPLICATE

PARENT

RELATED

RESOLVES

AFFECTED or AFFECTEDBY or AFFECTED_BY

AFFECTS

CONTRIBUTES or CONTRIBUTESTO or CONTRIBUTES_TO

TRACKS

Specify the type of link to create.
value A value for the attribute See description under name attribute for more information.

The following table describes Optional Attributes of State Elements.

Name Value Description
add true/false Add tags to existing string of tags. if no tag exists, the new string is simply added.
approvalApprover userid Specifies the user ID of the approver. See email, userid, and username for supported formats.
approvalDueDate userid Specifies the due date for the approval. See date, dateLong, and dateTime for supported formats.
contentEncoding

us-ascii

UTF-8

UTF-16BE

UTF-16LE

Specifies the encoding of the file to be attached.
contentType

text/plain

application/unknown

application/xml

Specifies the content type of the of file to be attached.
date true/false Date is specified in the format: yyyy-MM-dd
dateLong true/false Date is specified in the format: yyyy-MM-dd hh:mm:ss.SSS
dateTime true/false Date is specified in the format:yyyyy-MM-dd hh:mm:ss
email true/false Userid is specified in email format - user@somehwere.com (mailto:user@somehwere.com)
id true/false Enumeration value is specified as an ID.
include true/false Include the specified information in the specified list.
itemCategory true/false The iten specified is the name of a category - a "Filed Against" value.
itemComponent true/false The item specified is the name of a SCM component.
itemContributor true/false The item specified is the user ID of a contributor.
itemDeliverable true/false The item specified is the name of a release - a "Found in" value.
itemIteration true/false The item specified is the name of an iteration.
itemProcessArea true/false The item specified is the name of an EWM process area.
itemProjectArea true/false The item specified is the name of an EWM project area.
itemTeamArea true/false The item specified is the name of an EWM team area.
itemWorkItem true/false The item specified is the id of a work item.
label true/false Enumeration value is specified as a label.
msecs true/false The duration is specified in milliseconds.
plainText true/false The value is specified in plain text format.
projectArea projectArea Specifies the name of a project area containing the item.
remove true/false Remove the specified information from the specified list.
replace true/false Replace tags with the specified string. If no tag exists, the new string is simply added. To clear the tag attribute, specify value = "" and replace = "true"
units true/false The duration is specified in duration format (1w 1d 1h 1m 1s).
userid true/false Userid is specified in EWM user ID format.
username true/false userid is specified in user name format.
xmlText true/false The value is specified in the XML text format.
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, yyyy-MM-dd hh:mm:ss, or yyyy-MM-dd hh:mm:ss.SSS.
  • A deliverable value is the name of a Release defined in teh project area Releases tab.
  • A duration value (long integer) is specified in microseconds.
  • An enumeration value is the label, or id, value or the choice.
  • A resolution value is the label, or id, of the resolution as specified in the process definition.
  • You must have access to the specified access group to work with a Restricted Access work item.
The following options work in sets. Only one option in the set should be specified at a time. If more than one is specified, the last will take precedence. If conflicting options are chosen, the default will be used. Default options are labeled with an asterisk (*).
  • Contributor options
    • email
    • username
    • userid*
  • Date options
    • date*
    • dateTime
    • dateLong
  • Duration options
    • msecs
    • units*
  • Enumeration options
    • id
    • label*
  • Item options
    • itemCategory*
    • itemComponent
    • itemContributor
    • ItemDeliverable
    • itemIteration
    • itemProcessArea
    • itemProjectArea
    • itemTeamArea
    • itemWorkItem
  • Subscribers/List options
    • include*
    • remove
  • Tags options
    • add*
    • replace
  • Text options
    • plainText*
    • xmlText

Example

Create a Task work item

<target name="task" if="run.task">
  <wi:createWorkItem
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    passwordFile="${passwordFile}"
    processAreaName="IMS_SB_IMS"
    property="taskId"
    workItemType="Task">
    <wi:store name="attachment"  value="D:\rtc\Builds\PI37999.Regtest.Work items included in build.html"/>
    <wi:store name="category"    value="IMS Release"/>
    <wi:store name="comments"    value="This is a &lt;b&gt;bold&lt;/b&gt; comment." xmlText="true"/>
    <wi:store name="description" value="This is the description of the task."/>
    <wi:store name="dueDate"     value="2015-05-29"/>
    <wi:store name="estimate"    value="86400000"/>
    <wi:store name="link"        value="181" linkType="RELATED"/>
    <wi:store name="ownedBy"     value="djreilly@us.ibm.com"/>
    <wi:store name="priority"    value="High"/>
    <wi:store name="severity"    value="2 - Major"/>
    <wi:store name="subscriber"  value="mra@us.ibm.com"/>
    <wi:store name="summary"     value="Adding a new task with createWorkItem"/>
    <wi:store name="tags"        value="tag1"/>
    <wi:store name="target"      value="Version 15"/>
  </wi:createWorkItem>
  <echo>${taskId}</echo>
</target>

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