Customizing the work item editor in the web client
You can customize the structure of the work item editor by defining tabs, sections, and presentations. Sections are areas of related content on tabs. Presentations identify the work item attributes that appear on sections. The structure applies to both the IBM® Engineering Workflow Management Eclipse client and the web client.
About this task
You can reuse tabs and sections. If you reuse a tab or section that is shared with other editor presentations, any changes that you make to it are displayed in the other presentations. Instead of reusing a tab or section, you can create a duplicate tab or section. If you change a duplicate tab or section, the changes occur in the current editor presentation only.
In the work item customization pages of a project, open the Editor
Note: To avoid losing unsaved changes, do not use your browser's back and forward buttons to navigate the Work Items pages. If you leave the Editor Presentation page to edit elements on another page, click the Editor Presentation link in the Work Items page menu to continue editing.
- In the Choose the Editor Presentation to edit section, click Add, enter an ID for the presentation, then click OK.
Define the editor presentation in a hierarchical manner. If you are adding a header, define the
header first. Define tabs next. Then, define the sections that appear on each tab. Finally, define
the presentations that appear in each section. For details, complete the following substeps.
When you modify an editor presentation, any time that you reuse an editor presentation element that is used in another work item type, that element displays a warning () icon in the presentation editor. The warning icon indicates that the element is shared with other presentations.
For example, if you create a new work item type that is named Custom type, add a unique header and a unique overview tab, and then create a Custom Links tab that reuses an existing tab element, the editor presentation editor displays a warning icon.Note: Modifying shared elements can result in project-wide changes. Any time that you change a shared editor presentation element that is displaying a warning icon, the changes that you make to that element are adopted by all other presentations in the project that use the element.
Customize the header.
- Click Add Header.
- Select Create Section ID and enter an ID to create a new header section, or select Reuse Existing Section and select a section from the list (for example, com.ibm.team.workitem.header.default).
- You can configure the work item editor header by adding presentations to the Header Slot. The configured presentations are displayed in one row across the top of all tabs of the work item editor.
- Click OK to save the header definition.
- Click the Add Tab button, which is located below the header section.
- In the Title field, enter the name that you want to appear on the tab in the work item editor.
- Select one of the existing layouts. Predefined layouts are designed to help you get started quickly. You can edit the layout selection after you create the tab.
- Select Create Tab Id and enter an ID. Alternatively, to reuse an existing tab definition, select Reuse Existing Tab and select a tab ID from the list.
- Click OK to save the tab definition.
Customize the contents of a tab.
- Click Add Section to add a section to the tab that you defined.
- In the Title field, enter the name that you want to appear on the section in the work item editor.
- Select Create Section Id and enter an ID. Alternatively, to reuse an
existing section definition, select Reuse Existing Section and select a
section ID from the list. Remember: Existing elements are shared content. Any changes that you make to shared content are applied throughout the project.
- Click OK to save the section definition.
- To adjust the order of tabs in the editor presentation, open the tab menu and click Move Left or Move Right.
Customize the contents of a section.
- Click the Add Presentation () icon inside the section to add a presentation to the section that you
defined. You can define a presentation by using an attribute or a non-attribute. Note: If extended rich text is enabled for your application server, and you add an attribute presentation of Kind HTML, the full set of rich text toolbar icons appears in the work item field. For a list of rich text icons, see Creating work items in the web client. 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.Note: All presentations except the inline presentations group the tabs. The inline presentations group the work item types. While creating the inline presentations, name them as per the work item type. For example, com.ibm.team.workitem.web.inline contains com.ibm.team.workitem.web.inline.retrospective, com.ibm.team.workitem.web.inline.default, and more.
- Attributes: You can use the predefined attributes or custom attributes that you define on the
Types and Attributes page. Select Attribute-based
presentation and in the Attribute field, select an attribute to
define the presentation. Tip: The attribute list contains only the available attributes that are not already added to some part of this editor presentation. If you want to display all attributes, including the ones that are already added to the current editor presentation, click the Filters () icon and set Show already configured attributes.Important: If you modify the work item editor, existing work items of the work item type that is associated with that editor are updated with the new presentations. However, if you add or modify attributes by using the Types and Attributes page, work items are not updated with those changes. In this case, you must manually synchronize the work items.
- Non-attributes: You can also add a section that is not based on an attribute, such as Approvals,
Quick Information, or References. Select Non-Attribute-based presentation and
in the Kind field, select a non-attribute to add to define the presentation.
The following table describes the non-attributes.
Non-attribute Description Approvals An Add Approval button, which users can click to assign approvals to specific users. Attachments A Choose File button, which users can click to browse to a file to add as an attachment to the work item. Code Review Summary A set of fields added to the Approvals editor presentation to enable users to conduct reviews of change sets that are associated with the work item. The Code Review Summary includes links to change sets and a place where users can record issues that they discover during their reviews. Discussion A section where users can enter comments. History A section that shows the history of changes, in chronological order, to the work item. Line Separator A line that you can use to organize fields in the editor presentation. If you supply a label, the line appears adjacent to the label. Links An Add Related button, which users can click to create a link to another work item. Users can also select the link type, such as Blocks, Depends On, and Duplicated By. Planned Time The Planned Start Date and Planned End Date fields. These fields are for use only with the Formal Project Management process template. Quick Information A section that contains links to objects that are listed on the Links page, such as attachments, subscribers, and related work items. Quick Information (Time Tracking) A section that contains data from time sheets. This is for use only with the Formal Project Management process template. References A section that displays links. In the Engineering Workflow Management client for Eclipse IDE, select the link type that you want to display. The section includes Add and Remove buttons for adding and removing links. Risk Matrix A matrix that is used to calculate the risk probability and impact. This is for use only with the Formal Project Management process template. Separator A line that you can use to organize fields in the editor presentation. If you supply a label, the line appears under the label. Static Rich Text A text entry. You can use bold and italics to format the text. Static Text A plain text entry. Team and Project Area The team area and project area that are associated with the work item category that the work item is filed against. Time Sheet Table A table that shows time sheet data. This is for use only with the Formal Project Management process template. Work Progress A bar that shows the percentage of work completed for the work item. Workflow Resolution A choice menu with the available values for resolving work items, such as Fixed and Duplicate. Workflow State A choice menu with the available states, such as New and Started, for the work item.
- Attributes: You can use the predefined attributes or custom attributes that you define on the Types and Attributes page. Select Attribute-based presentation and in the Attribute field, select an attribute to define the presentation.
- If the presentation will be referenced from elsewhere, such as by a link from the Quick Information section, enter an ID for the presentation in the ID field.
- You can further configure some presentations by adding properties. For example, you can add the
As another example, for the Planned For presentation, you can customize or disable the warning message that is displayed when a user selects an iteration from a different timeline. The default editor presentation behavior for the Planned For presentation is that the iteration choices depend on the category that is selected for the Filed Against presentation. If a category is unassigned, the project area timeline is used. The editor presentation also allows users to select an iteration from a different timeline in the project area than the one that is associated with a category. If a user selects an iteration from a different timeline, a warning icon () and associated message are displayed. You can customize or disable the warning message by using the Planned For presentation editor.
- To the right of the Planned For presentation, click the Edit Presentation () icon. The Edit Presentation dialog box opens.
- In the Properties section, click Add. A new property row is displayed.
- To customize the warning message, in the Key column for the row, select the
warningMessage property and in the Value column, customize the warning
- To disable the warning message, in the Key column, select the disableWarningMessage property and in the Value column, select true.
- To customize the warning message, in the Key column for the row, select the warningMessage property and in the Value column, customize the warning message.
- Click OK to save the customizations. The Edit Presentation dialog box closes.
- Click the Add Presentation () icon inside the section to add a presentation to the section that you defined. You can define a presentation by using an attribute or a non-attribute.
After you define elements in a tab, such as sections and presentations, you can drag these
elements to rearrange the tab layout. You can move sections to different slots on the tab and you
can drag presentations to rearrange them in a section or to move them to a different section.
For example, moving a How Found presentation from its current location to a new location in the Details section would look similar to the following screen.
To add a Quick Information section, in the presentation definition, add a property that is
named quickinformationConfiguration and set the value to the name of the
Quick Information configuration. Use the Quick Information Configuration editor in the Eclipse
client to create a configuration.
For more information about customizing the Quick Information section, see Customizing the Quick Information section.
- Optional: Customize the header.
- Click Save at the top of the page to save your changes.