Defining categories that work items can be filed against in the web client

Categories identify the various components or functional areas of your project. Each category is associated with a team area that includes members who are responsible for developing that component. The categories that you define are displayed as choices in the Filed Against field in the work item editor.

About this task

When you create a work item, you set its category attribute. The options that are available to you in the category field in a context are determined by the categories and associations that are defined for that context.


  1. In the administrative web interface, go to the project area. See Logging in for project administrators and team leads (web).
  2. In the project area, click the Categories tab.
  3. To create a category and add it to the project area, complete the next steps.
    1. To create a new category at the <Root Category> level, in the toolbar, click the Action Menu button in the Actions column. To create a new category under an existing category, click the Action Menu button in the Actions column next to the existing category. The Add Category dialog box opens.
    2. Enter a name for the category and click OK.
    The new category displays in the Categories column. By default, the new category is associated with the team area that is associated with the top-level category.
    Note: Some project area process templates specify initialization steps that create categories when you create a project area. When you create team areas, do not associate them with these default project area-level categories. Instead, associate the team areas with new categories that you define. Associating a team area with one of the project area-level categories prevents you from querying for work items that are assigned to your team area. Querying for work items associated with a project area-level category returns all work items in the project area.
  4. To associate a category with a team area, complete the next steps.
    1. Optional: Select a timeline. The default timeline is (any), meaning that the association applies to all timelines. If your process includes multiple timelines, you can specify a different association for each timeline. When a user creates a work item, it is assigned to a team area based on its category and the timeline of its Planned For iteration.
    2. Select the category.
    3. Click the corresponding cell in the Associated Project/Team Area column. The Associated Project/Team Area dialog box opens.
    4. Select the team area to associate with the category. Then, click Associate.

    If you specified different associations that are based on different timelines, the associations in the table of categories and associated team areas change when you select different timelines in the Timeline menu. The process that is defined for the associated team area is the process that users follow for processing work items.

  5. Optional: To limit visibility of a category to members of the team that is associated with the category, click the corresponding check box in the Restrict Category Visibility column. By default, categories are visible to all users. When you limit the visibility of a category, only members of the associated project or team area can see the category in the category list when they are assigning work items.
  6. Optional: To limit read and write access to work items that are associated with this category, click the corresponding check box in the Restrict Work Item Access column. When you limit work item access for a category, only members of the associated project or team area can view and modify work items that are assigned to that category.
  7. Optional: To set a category as the default for new items that are created in plans that are owned by the corresponding team or project area, click the associated check box in the Use As Default column. When new items are created in plans, the Filed Against value defaults to this category.
  8. To remove an old category from the table, select it, then click the Archive Selected button. To view archived categories, click Show Archived. Archived categories appear dimmed. To restore an archived category, select it and click the Unarchive Selected button.
  9. You can move a category from one spot in the hierarchy to another by using the move control in the Actions column to drag the category. A horizontal line indicates that you are moving the category between the categories above and below the line when you drop it. A highlighted category indicates that you are nesting the category under the highlighted category when you drop it.
  10. Click Save to save your work item category changes.

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki