Creating work items in the web client

Create a work item to submit a defect, task, or other type of work request.

About this task

You can customize the predefined layout of the work item editor for the work item types that are provided with your process template. For information about process templates, see Working with process templates.


  1. Click Work Items in the main menu, and, in the Create Work Items section, select the type of work item to create.
    Alternatively, use the shortcut on the Welcome to Work Items page. Click Create a work item, select the project area, and then select the work item type.
    Note: When you use this shortcut, a work item is created with the default work item type, which is determined by the project's process configuration. For information about setting the default work item type, see Setting the default work item type.

    When you click Work items, a drop-down list appears with the types of actions available, including a list of the types of work items available for you to create. The default number of work item types to display is 10; if your process definition has more work item types defined, then you can configure this drop-down to display more than the default 10 items.

    Learn more about changing the number of work items in the drop down list: You can change the default number of work item types that appear in the Work items drop-down box: Navigate to your project admin page (something like: https://<server_URL>:<port_number>/ccm/admin). Click Advanced Properties and locate$ConfigurationValueProvider. Find the Maximum number of work item types to show on the work item component menu, and click Edit. Type the number of work items types that you want to display, and click Save. Now when you click Work Items, a longer list of work item types appear in the drop-down list.

    If there are deprecated work item types in the Work items drop-down box, you can change the project settings for your project to filter out these deprecated work item types. Only active work item types is displayed.

    Learn more about filtering out deprecated work item types from the drop down list: You can select whether you want deprecated work items to be filtered out from the Work items drop-down list. In the Eclipse client, open your project. Open the Process Configuration Source tab and search for Search for the work item type that is deprecated and add the text archived="true". For example, this XML snippet would filter the ‘story’ work item type from the various locations in the user interface, where you can create work items.
    <configuration-data final="true" id="" xmlns="">
    <type category="" icon="processattachment:/workitemtype/story.gif" id="" ignoreNameInLinkDetection="false" name="Story" archived="true">
        <alias name="user story"/>
  2. On the Overview tab, enter or select values for the following fields. Asterisks in the user interface identify required fields.
    Field Description
    Summary A brief headline that identifies the work item.
    Type The type of work item. Commonly available types include Defect, Task, and Story. You can customize the project to include more types.
    Severity An indication of the impact of the work item, such as Minor, Normal, Major, or Critical.
    Found In The release that the work item refers to.
    Filed Against A category that identifies the component or functional area that the work item belongs to. For example, your project might have GUI, Build, and Documentation categories. Each category is associated with a team area; that team is responsible for responding to the work item. If you are unsure of the category, click Guess Category . This button suggests categories by using the text in the Summary and Description fields to search for similar work items.
    Description A detailed description of the work item. For example, the description for a defect might include a list of steps to follow to reproduce the defect. You cannot save a work item if the description is longer than 32 KB.
    Note: Uniform Naming Convention (UNC) path names are not supported in the Description field and the Comment fields in the Discussion section. UNC is a Windows format for specifying the location of resources.
    If extended rich text is enabled for your application server, the following icons are available to format text in the Description field. To enable extended rich text, set the Enable extended rich text presentation property to True on the Advanced Properties page. For details about setting advanced properties, see Configuring advanced properties. Alternatively, you can enable rich text by editing the server-installation-directory\server\conf\ccm\ file. Stop the server, then add the following line in the file: Save the updated file, then re-start the server.
    Toolbar icon Description
    Bold icon Bolds text.
    Italics icon Italicizes text.
    Strikethrough icon Places a line through text.
    Underscore icon Places a line under text.
    Remove Format icon Removes all formatting from the selected text.
    Numbered list icon Inserts a numbered list.
    Bulleted list icon Inserts an unordered list.
    Insert Horizontal Line icon Inserts a horizontal line across the entire length of the Description field.
    Font icon Applies a specific font to text. Select the desired font from the list.
    Size icon Sets text to a specific size. Select the desired size from the list.
    Text Color icon Sets the color of text. Select the desired color from the grid.
    Background Text Color icon Sets the background color of text. Select the desired background color from the grid.
    Decrease Indent icon Decreases the indentation of the selected text.
    Increase Indent icon Increases the indentation of the selected text.
    • In the Summary and Description fields and in a new Comment field in the Discussion section, you can use various shortcuts to connect to artifacts, refer to artifacts, and notify users.
      • To refer to other Jazz® artifacts, you can use short notations. When you save the work item, these notations become links to the artifacts.
        • Specify the type of artifact and its ID. For example, work item 123, defect 25, attachment 982.
        • Refer to artifacts in other work items. For example, task 50775, comment 4.
        You can also open a content assist dialog to select a work item by pressing Ctrl+Space twice. A list of recent work items is displayed. Either select a work item from the list, or select More work items to open the Select Work Items dialog. Press Ctrl+Space in the content assist dialog to toggle between displaying a list of subscriber user IDs and recent work items. To display only More work items in the content assist dialog, enter @ in the rich text editor.
        Note: For Chinese, Japanese (Linux®), and Korean (Linux), press Alt+/.
      • To write to a team member in the Description field or in a Comment field in the Discussion section, enter the @ symbol followed by the user ID of the team member. To find the ID of a user, you have several choices in the rich text editor:
        • Click Insert User Link icon, the Insert user link icon.
        • Open a content assist dialog by pressing Ctrl+Space. Then, select a user from the list, or click More users to open the Select User dialog.

        After you save the work item, the team member receives a notification in their email client as specified in their user profile. An event is also displayed in the Project and Team Events widget on the dashboard.

      • You can insert links to URLs in the Description field or in a Comment field in the Discussion section. In the rich text editor, click Insert/Edit External Link icon, the Insert/Edit External Link icon, and, in the Insert External Link dialog, enter the URL.
    • In the Discussion section, comments are displayed with the most recent one first.
  3. On the Links tab, add attachments, subscribers, and related work items.
    Note: Attachments are available to the entire project area and are not limited to the visibility of team area or work item.
    • To attach a file, either drag it from another application (for example, Windows Explore or the desktop) to the Attachments section, or click the Drag files to add them or click here to browse area to navigate to the file location and select the file.
      • To cancel the in-progress upload of an attachment, click Cancel.
      • To download an attachment, click Download button.
      • To delete an attachment, click Delete button.

      Thumbnails are displayed for image attachments. Preview support is available for PDF and video attachments by clicking the associated file attachment.

      The default size limit for attachments is 50 MB. If you are a member of the JazzAdmins group, you can change the size limit. Log in to the administrative web UI, click the Application tab, click Advanced Properties, scroll to the Work Item Component section, and edit the Maximum Attachment Size setting.

    • To add subscribers, in the Subscribers section, click Add to open the Select Users dialog. Enter part or all of a user's name; then, in the Matching users list, select the user and click OK. Subscribers receive email notification whenever someone modifies the work item. When you create a work item, you are added as a subscriber. To stop receiving notifications, remove yourself as a subscriber by clicking the delete icon beside your name.

      Be conservative when you add subscribers because they receive email notifications whenever the work item is changed.

    • To link the work item to another work item in the same repository, in the Links section, click the down arrow next to Add and select the type of relationship to establish. For example, you can establish a parent-child relationship between work items, mark a work item as a duplicate of another work item, or indicate that one work item is blocked by another work item. To link the work item to a child work item, click Add Children. To link the work item to a parent work item, click Set Parent.
    • To link the work item to a work item in a different repository, click the Add menu, select Related Change Request, select the remote project area, and find and add the work item. To link to work items in project areas on other Jazz Team Servers, cross-repository communication must be configured and the project areas must be linked. For more information, see Linking between AM artifacts and local work items.

    In the enhanced security model of the product, the access context of the attachment is the same as the access context of the work item. A user with read access to a work item can access attachments associated with that work item. Users without access to the work item do not have access to the attachment. A direct URL link to an attachment is denied access if the user does not have read access to the work item that the attachment is attached to.

    A new advanced server property, Enable Enhanced Security Model for Work Item Attachments, is available to enable this model. The new security model applies only to new attachments created after enabling this property; it does not change the access context of existing attachments. This property is disabled by default.

    Advanced server properties
  4. Use the Approvals tab to specify one or more users who are responsible to approve the resolution of a work item.
    1. Click the arrow next to the Add Approval button and select the type of approval (Add Approval, Add Review, Add Verification). You might want to create different approval types, perhaps with different due dates, for different users. For example, you might want to have a lead developer review the proposed resolution, and a test engineer validate the delivered fix.
      You can also use approvals to remind team members to perform a common task. For example, you might create a work item for developers to update the copyright year in their files.
    2. Specify the user or users who are responsible to approve the resolution by clicking Add Approver.
    3. Select a due date. Click calendar button to open a calendar dialog and select a date and time. Click OK.

    You can also use approvals to remind team members to perform a common task. For example, you might create a work item for developers to update the copyright year in their files.

  5. Optional: If you are working in a project that uses the Scrum process and you are creating a Story work item, you can specify the acceptance criteria. Click the Acceptance tab. In the Criteria of Acceptance field, enter the criteria for the test team to use to verify that the Story work item is complete.
  6. Click Save to save the work item.

What to do next

The work item is ready to be worked on. For information on working on and resolving work items, see Working on and resolving work items.