Jazz Library Getting started with components in the RM and QM applications
Author name

clm,elm,requirements-management-doors-next,test-management,workflow-management,jazz-reporting-service,rational-doors-next-generation,rational-quality-manager,rational-team-concert

Thu, 28 Apr 2016
5 min read
0

Getting started with components in the RM and QM applications

Catherine Trinkwon, Persistent Systems Ltd.
Last updated: 16 August 2016
Build basis: Rational solution for Collaborative Lifecycle Management 6.0.3 M5

In Rational® DOORS® Next Generation (RM application) and Rational Quality Manager (QM application), in projects that are enabled for configuration management, you can now create components to manage versions of data at a finer granularity than whole project areas. You might see components referred to as “fine-grained components.” Instead of working with all the artifacts from the project in one stream (such as a physical piece called a Handheld Meter Reader), you can create a component to represent a smaller collection of artifacts (such as a smaller physical piece with software like a Sensor in the handheld meter reader).

Components are supported only in projects that have configuration management capabilities enabled.

Note: This feature is in technology preview and is not supported for use in a production environment. You should read and understand the key limitations that are listed in the Limitations sections of this article: for the RM application and for the QM application.

This article explains how to get started, first with the RM application and then with the QM application:

Before you begin

Enabling components in the RM and QM applications

After you enable components in the RM and QM applications, all configuration-enabled RM and QM projects can use them. You cannot enable components for individual projects. Enable components only if you want all your projects to use components.

Important: Do not disable the components feature after you enable it: the data that is created after you enable it cannot be used if you disable it. See scope of the component property when you enable components.

  1. Log in as a JazzAdmin user at: https://example.org:9443/application_context_root/admin
  2. In the left navigation, click Advanced Properties.
  3. Search for the following property, and set its value to true.
    • RM: Search for Enable Component Capabilities
    • QM: Search for Enable Fine-Grained Components
  4. At the top of the page, click Save.
  5. RM application only: Restart the server.
  6. Close any browser tabs that show pages from the server. If you do not complete this step, the web client does not reload correctly.
  7. To reload the web client, open a new browser window and repeat step 1.

Creating an RM project that contains a component

When you create your project, you specify the name of the initial component. You must have JazzProjectAdmins or JazzAdmins repository access.

  1. Open the All Projects view: https://example.com:9443/rm/web
  2. From the toolbar, click the Admin menu and click Create Project Area.
  3. Specify a project name.
  4. Select Enable configuration management for this project area. To read more about configuration management, see Enabling configuration management.
  5. Specify a component name and click Next.
  6. Optional: Select a template to base the project on.
  7. Click Finish. You can see the contents of the new component.
  8. Close any browser tabs that show data from the project area. If you do not close the tabs, the next time that you browse to this project area, the web client prompts you to enable configuration management.
  9. Open a new browser page and open the All Projects view: https://example.com:9443/rm/web

You can now use the component to represent a collection of versioned artifacts within the project area. For example, instead of working with all the artifacts from the project in one stream (such as a physical piece called a Handheld Meter Reader), you can use a component to represent a smaller collection of artifacts (such as a smaller physical piece like a Sensor in the handheld meter reader).

Working with components in the RM application

Managing components and their configurations

You must have permission to create and modify components.

From the All Projects view, click a project name. To view and create components and their configurations in that project, on the toolbar, click the Admin menu > Manage Components and Configurations. The editor for the current component opens to show the list of streams of the component.

Note: To see the baselines of a component, click a stream name; then, click the Baselines tab in the stream editor.

Creating another component in this project

Click the Component breadcrumb link near the top of the page, and then click Create Component near the upper right of the page. An initial stream is automatically created for the component.

     After you create the component, you can populate it by selecting a template.

  1. Switch to the component to work with: on the toolbar, from the Current Project Component menu, select the component.
  2. Click the Admin menu > Manage Component Properties.
  3. To add types, click New Type.

     Tip: You can also create components from the All Projects view. Go to https://example.com:9443/rm/web. Then, under a project name, click Manage Components > New Component and complete the steps in the wizard. To populate the component with an initial structure, you can select a template.

Exploring a component

     On the Components page, click the component name.

In the component editor, you can edit the component name and description, and manage configurations of the component.

  • Baselines are not shown on this page; to see them, click a stream name and in the stream editor, click the Baselines tab.
  • To create streams and baselines of the component, select the action from the Actions menu.
  • To return to the list of components in the project, click the Components breadcrumb link near the top of the page.

When you finish exploring, return to the project by selecting it from the Home menu.

Opening and switching between components

Important: In this version 6.0.3 milestone 5, do not open components from the Home menu and select a project area. Opening components this way might cause unexpected errors.

To open or switch components:

  • Open the All Projects view: https://example.com:9443/rm
    1. Under the project area name, click Manage Components to see the list of components. Click Manage Components again to hide the list.
    2. For the component you want to work with, click Show Artifacts or Show Modules.

  • On the toolbar, click Current Project Component, and choose the component to switch to, or follow the instructions in the Choose a component window.

To link to artifacts in other components:

  • You must add the appropriate streams or baselines of the component to a global configuration.
  • To link to artifacts that use custom link types, you must use the same RDF URI to define the link type in both components.
  • To view artifacts from multiple components at the same time, or to drag links from one component to another, open multiple browser tabs or windows and place them side-by-side on the screen.

Archiving and restoring components

You can archive components that you no longer use or that are obsolete. For example, you might archive those that were created by mistake, or whose artifacts were refactored to newer components. Archiving components hides them and simplifies the list of components that you see, and prevents team members from adding configurations (streams and baselines) of those components to global configurations.

Archiving a component does not delete it. You can restore it when you need it again.

When you archive a component, the system archives all of the configurations of that component. Archived configurations are shown only when they are referenced by an active configuration.

You cannot edit archived configurations or components, and you cannot add archived configurations to global configurations. Archived configurations and components are not displayed in search and query results. Report Builder reports do not include data from archived items.

Ask an RM application administrator to grant you permission to archive components.

To archive or restore components:

  1. Optional: If you are not already working in a component: Open the All Projects view at https://example.com:9443/rm
    2. , and click a project name.
  2. On the toolbar, click the Admin menu > Manage Components and Configurations.
  3. Click the Components breadcrumb link near the top of the page.
  4. To archive a component:
    1. Click the component to archive.
    2. Click Archive on the toolbar near the upper right of the page.

      3. Tip: To show archived components, click Show archived components above the table.

  5. To restore a component:
    1. Click Show archived components above the table.
    2. Click the component to restore, and click Unarchive.

To return to the list of components, click the Components breadcrumb link.

What’s supported in the RM application

Components are in technology preview, so enabling their use changes the behavior of the RM application. If you attempt operations that are not in the following list, you might see unexpected results or, in extreme cases, lose data. Remember that components are not supported in a production environment.

Version 6.0.3 milestone 5 supports the following actions:

  • Configuration management
    • Create streams and baselines
    • Create a global configuration and add a configuration of a component from the RM and QM applications
    • Work in the RM and QM applications in the context of a global configuration
    • Compare configurations
    • Create, work in, and deliver change sets, except automatic delivery with dominant attributes selected when change sets conflict with target configurations.
  • Linking
    • Link within an RM component
    • Link between RM components (same or different projects)
    • Link columns that show links within and across components
    • Link between RM and QM artifacts; between RM and Change and Configuration Management (CCM) artifacts; and between QM and CCM artifacts
    • Copy and link artifacts
  • Artifacts
    • Create, edit, and delete text artifacts
    • Create, edit, and delete modules and their contents
    • Bulk edit attributes on artifacts
  • Type system
    • View and update the component type system
    • Define and use link preferences and link constraints
    • Import a type system from one component to another
  • ReqIF
    • Export data as a ReqIF package
    • Import a ReqIF package
    • Roundtrip ReqIF packages (repeated import and export)
  • Commenting (except for reviews)
  • Client extensions API (for Javascript only, not the OSLC-based interfaces)

Limitations in the RM application

Consider the following key limitations. Because components are in technology preview, not all limitations are captured in this article.

  • Scope of the component property when you enable components
    • Enabling components enables them for all configuration-enabled projects, not individual projects.
    • Do not toggle components on and off:
      • After you enable components, you cannot use data that was created while they were disabled.
      • If you disable components later, you cannot use any data that you created while they were enabled.
  • Upgrade and migration
    • After you enable components, you cannot migrate or upgrade the data that is created by using them. If you adopt a later build, you will lose your data.
  • Component management
    • You cannot rename or delete components.
  • Dashboards
    • Dashboards do not load or display data successfully.
  • Linking
    • You cannot create links within a Text artifact. If you do this, the links are not created correctly, and the web client stops working as expected. You must then reload the browser page.
  • Locking
    • Locking is not supported in this milestone.
  • Reporting and printing
    • You cannot use CLM reporting tools to report on and print data in components.

Creating a QM project that contains an initial component

You must have JazzProjectAdmins or JazzAdmins repository permissions, and you must enable component capabilities.

  1. Open the All Projects view: https://example.com:9443/qm/web/console
    If QM has only one project area, you are redirected to the dashboard. Click the Admin menu > Manage Project Areas and go to step 3.
  2. In the upper right of the page, click Manage All Projects.
  3. Click Create Project Area and follow the instructions on the page.
  4. Click Save.
  5. In the left navigation, click Configuration Management; then, click Enable Configuration Management. For details, see Enabling configuration management.
  6. From the Home menu, select the new project.

The new project contains an initial component that has the same name as the project area. A stream is also created for this component, named component_name Initial Stream. The component configuration you are working in is shown on the toolbar.

You can now use the component to represent a collection of versioned artifacts within the project area. For example, instead of working with all the artifacts from the project in one stream (such as a physical piece called a Handheld Meter Reader), you can use a component to represent a smaller collection of artifacts (such as a smaller physical piece like a Sensor in the handheld meter reader).

Working with components in the QM application

Managing components and their configurations

To manage components and configurations, you must have the corresponding permission in the Save Components permission group for the project area.

You cannot use duplicate component names in a project area.

To show and manage components and their configurations, on the toolbar, click the Admin menu > Manage Components and Configurations.

Exploring configurations of components

Explore the configurations for the current project area.

  • View the details of a configuration by hovering over its name in the Name column, or by choosing Stream Properties from the Action menu beside the configuration name.
  • Edit the details of a configuration by clicking its name.
  • Create a stream or baseline of a component from the Action menu beside the component name.

Showing the components in the current project area

Click Components to see the list.

  • Create a component by clicking Create new component above the table. The system creates the component with the name that you specify, and an initial stream named component_name Initial Stream.
  • Edit the component name or description by selecting that action from the Action menu beside the component name.

When you finish exploring, return to the project by selecting it from the Home menu.

Working with a single component

Only one component is shown in the Selected Component menu on the toolbar (beside the project area name) if a project in the QM application contains only one configuration, and a global configuration contains only one configuration from that project.

Switching between components

After you add configurations (streams or baselines) of components to a global configuration, when you work in that global configuration context, you can switch to another component without changing your global configuration context.

To switch to another component that has a contribution in the global configuration context:

  1. On the toolbar, click the Selected Component menu, and then click Choose Another Component.
  2. Select All project areas within current global configuration or specify another project area in the Project Area field.
  3. To show all the components that have contributions in the global configuration context, type an asterisk (*). If you do not see the component that you expect, ask your configuration lead to add a configuration (stream or baseline) of that component to the global configuration.
  4. Click the component to switch to, and then click OK.

To switch to another component that does not have a contribution in the global configuration context and change the configuration context to the Quality Management configuration of that component:

  1. On the toolbar, click the Current Configuration menu, and then click Switch.
  2. Select Quality Management Configuration.
  3. Select the configuration type to search for (stream or baseline), and type an asterisk (*) to show all of them.
  4. Click the component to switch to, and then click OK.

To switch to another component that does not have a contribution in the global configuration context and change the configuration context to the global configuration with a contribution of that component:

  1. On the toolbar, click the Current Configuration menu, and then click Switch.
  2. Select Global Configuration.
  3. To show all the global configurations, type an asterisk (*).
  4. Click the global configuration switch to, and then click OK.

After you switch to the global configuration context, you can switch to another component that has a contribution in the global configuration context.

Working with the current component

You can see the name of the component that you’re working with in the following locations:

  • Component field in the Summary section of test artifact editors.
  • Component column of test artifact table views.
  • Component field in the Run Test Case window.
  • Component field in the Overview section of the Generate Test Case Execution Records window (page 1).
  • Component column in the test case execution record table view of the Generate Test Case Execution Records window (page 3).

For the following test artifacts, the Summary section shows the name of the component that you’re working with:

  • Test plan
  • Test case
  • Test data
  • Test script
  • Test suite
  • Test case execution record
  • Test suite execution record
  • Test case result
  • Test suite result
  • Test environment
  • Keyword

For other types of test artifacts, the component name is not shown, even though the artifacts are in a component.

An artifact can be associated with only one component.

Copying (cloning) artifacts from one component to another

Components enable you to group artifacts in a way that makes sense for your project. After you enable components, each project that you create contains an initial component. You can create other components to represent smaller logical or physical pieces of your project. Then, you can reorganize the artifacts from the initial component into the other components.

Before you begin, you must create a baseline of the component that contains the artifacts to copy. Your current configuration must be a stream of the component you want to clone the artifacts into.

When you clone a test artifact, a new version is added to the stream you work in, and that artifact now exists in two different configurations. These versions have the same concept URI. Important: Those 2 configurations should never be in the same global configuration.

To clone (copy) artifacts:

  1. On the toolbar, from the Current Configuration menu, select Clone from a Component.
  2. Select the baseline of the component that contains the artifacts you want to clone, and click OK.

When you clone artifacts, note these points:

  • All test artifacts that are linked from the artifact that you clone are also cloned. Consider an example where Test Plan A contains Test Case A, which is associated with Test Script A.
    When you clone Test Plan A, all three artifacts (Test Plan A, Test Case A, Test Script A) are cloned into the stream. Conversely, test artifacts that are linked to the artifact that you clone are not cloned. For example, when you clone Test Case A, only Test Case A and Test Script A are cloned into the stream.

  • Duplicated test artifacts in the source component are also cloned into the stream. Consider an example where Test Plan A has been duplicated to Copy of Test Plan A. When you clone Test Plan A, both artifacts are cloned into the stream.

What’s supported in the QM application

As a technology preview feature, enabling the use of components changes the behavior of the QM application. However, you should not experience any unexpected behavior when you work in a single configuration (stream or baseline) of a component.

Limitations in the QM application

Consider the following key limitations. When you try these operations, they might fail or you might see unexpected results. Because components are in technology preview, not all limitations are captured in this article.

  • Component management
    • Moving or copying artifacts between components
    • Creating multi-component views
    • Sorting and filtering the Component field in the test artifact table views
  • Configuration management
    • Completing configuration management tasks on components (for example, creating streams and baselines)
    • The Current Configuration menu and component selection window might have unexpected behavior
    • Contributing components to global configurations
    • Navigating to components from global configurations
    • Creating baselines of components in the Global Configuration Management application
  • Data management
    • CSV export
    • Bulk operations
    • Copying, comparing and merging across components
  • Linking
    • Linking across QM projects
    • Creating links (both directions) between QM, RM, and CCM artifacts
    • Using artifact pickers (OSLC-delegated UI)
    • Determining link validity
  • Reporting
    • TRS feeds including components
    • Reporting on components in Report Builder and Rational Publishing Engine
    • Dashboards: Accessing dashboards does not cause problems with the system, but the dashboards do not load or show data successfully.
    • Exporting test artifacts and test artifact table views to a PDF file
  • APIs
    • OSLC QM V2 API including all utilities and tools built on this API
    • RQM Reportable REST API including all utilities and tools built on this API
  • Upgrade and migration
    • After you enable components, you cannot migrate or upgrade the data that is created by using this feature. If you adopt a later build, you will lose your data.

© Copyright IBM Corporation 2016

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Thu, 28 Apr 2016