RegisterLog In to Jazz.net dW

Configuring Rational DOORS and Rational Team Concert to integrate with one another

Overview

You can configure Rational® DOORS® and Rational Team Concert™ (RTC) to integrate with one another by using Open Services for Lifecycle Collaboration (OSLC), an open standard that IBM is developing in co-operation with business partners and customers.

You use Rational DOORS to manage your requirements, and RTC to put your requirements under change control, preventing uncontrolled changes to your requirement set. Strict control of requirements is mandatory under many quality systems, and is needed if you are to keep track of the state of your requirements at any point in your product lifecycle.

The change control can be as strict or as loose as you like. After you have set up the two applications to communicate with one another, you can set up workflows in RTC and configuration templates in Rational DOORS with as much flexibility as you want. In this example, you will define a Requirements Change Request workflow that is based on the Simple Team process in RTC. You will then define a work item type, and map the work item type to a Change Management type in Rational DOORS. Finally, you will define a configuration template in Rational DOORS and set up module configuration.

As with many configuration tasks in Rational DOORS and RTC, it is essential that you plan your integration. You cannot set up a change control system "as you go". You must know in advance what types of work items you will want to use, whether you want to have more than one workflow, how you want to control your change requests, and so on.

This procedure contains example values for you to enter as you follow the instructions. If you already have values of your own, you can use them.

Though the generic change management integration included in Rational DOORS works with Rational Change, Rational ClearQuest®, and RTC, this document focuses on RTC.

Finally, this document assumes you have an intermediate knowledge of both RTC and Rational DOORS, and it is organized sequentially to allow a single user to follow the procedure.


Supported software

The information in this document is based on Rational DOORS 9.3.0.6, Rational DOORS Web Access 1.4.0.5, and Rational Team Concert RTC 3.0.1 running on Windows. It is compatible with Rational DOORS 9.3.0.2, 9.3.0.3, 9.3.0.4, and 9.3.0.5, Rational DOORS Web Access 1.4.0.2, 1.4.0.3, and 1.4.0.4, and Rational Team Concert RTC 3.0.

RTC can be used with a number of browsers. The integration is supported only with Internet Explorer and Firefox, and to make it run on Firefox you need to use the IETab2 plug-in to emulate Internet Explorer. This is because the Rational DOORS Web Access Change Details view needs ActiveX and the Change Details window cannot be rendered fully in Firefox without the plug-in.


Procedure

The outline of the procedure is as follows:

  1. Configure Rational DOORS Web Access and Rational DOORS
  2. Define the Requirement Change Request workflow in RTC
  3. Define a work item type called Requirement Change Request
  4. Define the mapping between the change management type and work item type
  5. Configure RTC and Rational DOORS to communicate with one another
  6. Define a configuration template in Rational DOORS
  7. Set up the module configuration in Rational DOORS

1. Configure Rational DOORS Web Access and Rational DOORS

To enable Rational DOORS to integrate with RTC, you must install and configure Rational DOORS Web Access, and configure the Rational DOORS database server by running the dbadmin command with additional parameters.

Before you begin

You must have database manager powers or custom user powers to manage the database in Rational DOORS.

Procedure

Installing Rational DOORS Web Access is almost completely automated; configuring is a manual procedure. You must update two configuration files - the festival.xml file and the doorsRedirector.properties file. If you are using a secure connection, you must also set up Rational DOORS Web Access to use SSL.

As part of the configuration procedure, you also configure the Rational DOORS database server by running the dbadmin command with additional parameters.

Install and configure Rational DOORS Web Access

To configure Rational DOORS Web Access and Rational DOORS, follow the instructions in the topics in these sections of the Rational DOORS information center:

When you have completed all of the configuration tasks, you are ready to start Rational DOORS Web Access.

Start Rational DOORS Web Access

Follow the instructions in Starting Rational DOORS Web Access on Windows systems.

Rational DOORS and Rational DOORS Web Access are now ready for the next step of the integration.


2. Define the Requirement Change Request workflow in RTC

The next step is to create and configure access to an RTC project area that is based on the Simple Team Process, and set up a new Requirements Change Request (RCR) workflow.

Before you begin

  • Get administrator rights in RTC.
  • If you want to run Firefox, install the IETab2 plug-in.

Procedure

Create a project area that is based on the Simple Team Process:

  1. Open RTC.
  2. Open the Create Project Area page:
    1. In the Team Artifacts view of the Work Items perspective, click Project areas.
    2. Select Create Project Area.
  3. Create the project area.
    1. Enter a project name and select Simple Team Process.
    2. Add a user to the Members and Administration sections.
    3. Click Save.
  4. Configure the new project.
    1. Click Project areas, and double-click the new project.
    2. Click the Permissions tab.
    3. Select Project Configuration, and select all of the permitted actions for the team member.
    4. Select Team Configuration, and select all of the permitted actions for the team member.
    5. Click Save.

Set up a new RCR workflow:

  1. In the new project, click the Work Items tab, and select Workflows.
  2. Create a workflow called RCR Workflow.
  3. Add or edit states. Make entries for Created, Assigned, Review, Approved, Applied, and Rejected:
    1. In the States section, click Add.
    2. Enter a name and brief description for the state.
    3. Select a group that is appropriate for each state. For Created, Review, Approved, and Rejected, select the Open group. For Assigned, select the In Progress group. For Applied, select the Closed group.
    4. The process templates include a set of icons. Select an icon, or click Add Icons and select your own graphics file to use as the icon for the state.
    5. Click OK.

      States in RTC

    Note: Add the Workflow Actions in the image after you have added the actions in Step 4.

  4. Add or edit actions. Make entries for apply, approve, assign, reject, restart, send to review, and start:
    1. In the Actions section, and click Add.
    2. Enter a name and brief description for the action.
    3. Select a target state that is appropriate for each state. For apply, select Applied, for approve, select Approved, for assign, select Assigned, for reject, select Rejected, for restart, select Created, for send to review, select Review, and for start, select Created.
    4. The process templates include a set of icons. Select an icon, or click Add Icons and select your own graphics file to use as the icon for the state.
    5. Click OK.

      Actions in RTC

    Note: You add the Resolutions in the image in Step 8.

  5. In the Transitions section, the state transition model is displayed. The row headings contain the From state, and the column headings contain the Target state. Add actions for the states:

    Transitions in RTC

  6. In the Workflow section, set the main workflow actions:
    1. In the Start action field, select start.
    2. In the Resolve action field, select apply.
    3. In the Reopen field, select restart.
  7. Add a resolution:
    1. In the Resolutions section, click Add.
    2. Enter a name and brief description for the manner in which a work item can be resolved. For example, you might define resolutions such as Fixed, Fixed indirectly, and Not a bug.
    3. Select or add an icon for the resolution, then click OK.
    To define all resolutions in the workflow, repeat these steps.
  8. In the Actions section, for each action that can be resolved, select those resolutions and the order in which they are displayed in the work item editor and other places throughout the user interface. To set the order of the resolutions, click Move Up and Move Down in the Resolution table.
  9. In the States section, for each state, set the order in which to display the available actions in the work item editor and other places throughout the user interface. Select a state. To set the order of the actions, click Move Up and Move Down in the Actions table.
  10. Click Save.
  11. To associate a type category with the new workflow:
    1. In the Configuration menu, click Types and Attributes.
    2. Select a type that is associated with the type category for which to designate the new workflow.
    3. Select the new workflow, and then click Save.

    If you change the workflow association for a type category, all work item types that are associated with that category also adopt the new workflow.

You now need to define a work item type that uses this workflow.


3. Define a work item type called Requirement Change Request

The next step is to set up a work item type that uses the RCR workflow you set up.

Procedure

Define a work item type called Requirement Change Request:

  1. In the project, open the Types and Attributes page:
    1. In the Team Artifacts view of the Work Items perspective, right-click the project area and select Open.
    2. Click the Process Configuration tab.
    3. Expand Project Configuration > Configuration Data > Work Items, and then click Types and Attributes.
  2. In the Work Item Types section, click Add.
  3. In the Add type window:
    1. In Name, enter Requirement Change Request.
    2. Create a type category to associate the work item type with. Enter demo.workitem.workitemType.rcr.
    3. Click OK to create the new work item type, and open it in the Types and Attributes page.
  4. Select an icon, and click OK.
  5. Create an alias. Enter rcr.
  6. Select an editor presentation that defines how the new work item type is displayed in each of the following editors:
    • Work Item Editor: The default editor for creating and modifying work items. Select demo.workitem.editor.
    • Inline Work Item Editor: The editor for inline work item modification. Select com.ibm.team.workitem.web.inline.task.
    • Lightweight Work Item Creation Dialog: The editor for quickly creating work items. Select com.ibm.team.workitem.lightweight.editor.section.
    • Plan Editor Preview: The editor for viewing and modifying work items inside a plan. Select com.ibm.team.apt.planPreview.task.
    You can customize the editor presentations on the Editor Presentations page.
  7. In Workflow, select RCR Workflow.
  8. Click Save.

    Work Item Type


4. Define the mapping between the change management type and work item type

The next step is to define the mapping between the change management type and work item type. The type bindings define the type of work items that are made available in OSLC integrations.

Procedure

Configure the Change Management Type binding in RTC:

  1. In the project, open the Change Management Type Bindings page:
    1. In the Team Artifacts view of the Work Items perspective, right-click the project area and select Open.
    2. Click the Process Configuration tab.
    3. Click Project Configuration > Configuration Data > Work Items, and then click Change Management Type Bindings.
  2. In the Defect row, select Defect, and then select the state that indicates that this type is ready for testing. Select the state that indicates that this type has reached resolution.
  3. In the Implementation Request row, select Requirement Change Request, and then select the state that indicates that this type is ready for testing.
  4. In the Quality Task row, select Task.
  5. In the Requirement CR row, select Requirement Change Request.

    Change Management type binding

  6. Click Save.

5. Configure RTC and Rational DOORS to communicate with one another

To allow the integration to work correctly, both RTC and the Rational DOORS database must be set up to communicate with one another.

In RTC:

  • Set up RTC to allow the connection from Rational DOORS
  • Add Rational DOORS to RTC as a friend
  • Add Rational DOORS to the Whitelist in RTC
  • Associate Rational DOORS with the project in RTC

You must then open Rational DOORS and set it up to allow the connection from RTC.

Before you begin

  • Get yourself database manager powers or custom user powers to manage the database in Rational DOORS.
  • Make sure that Rational DOORS Web Access is running in https mode.
  • Make sure that you have logged in to Rational DOORS Web Access at least once since it was started.

Procedure

Set up RTC to allow the connection from Rational DOORS:

  1. Log in to RTC as an administrator.
  2. Go to the Application Administration page for the RTC application, click Application Administration > Application, and then, in the Communication section in the navigation menu on the left, click Consumers (Inbound).
  3. Create a consumer entry for Rational DOORS. Enter a consumer name (for example, DOORS), enter a consumer secret, and then click Register. Make a note of the consumer secret. It is used later when you set up Rational DOORS.
  4. Rational DOORS is now registered in RTC as a consumer. Navigate to the list of authorized keys, and make a note of the consumer key that has been automatically allocated. It is used later when you set up Rational DOORS.

Add Rational DOORS to RTC as a friend:

  1. In the navigation menu on the left, click Friends (Outbound), and in the Friends pane, click Add.
  2. Enter a name for the connection (for example, DOORS).
  3. Enter the details for the Rational DOORS service. This service is hosted on Rational DOORS Web Access, and the default URL is https://hostname:8443/dwa/public/rootservices.
  4. Enter an OAuth secret (for example, DOORS). Make a note of the OAuth secret. It is used later when you set up Rational DOORS.
  5. Click Create Friend. A green confirmation message is displayed.
  6. Click Next. Make a note of the Provisional key. It is used later when you configure Rational DOORS to access RTC.
  7. Click Finish.

Add Rational DOORS to the Whitelist in RTC:

  1. In the navigation page on the left, click Whitelist (Outbound), and click Add.
  2. In the URL Whitelist pane, enter the URL of the Rational DOORS database. The default URL is https://hostname:8443/.
  3. Click Add. A green confirmation message is displayed.

Associate Rational DOORS with the project in RTC:

You can create an association between a project area in RTC and a module in Rational DOORS. After you establish the association, you can link RTC artifacts, such as work items and plans, between the project area and objects in the module in Rational DOORS. There are two associations to create.

  1. Open the project.
    1. In the Team Artifacts view of the Work Items perspective, click Project areas.
    2. Select the new project.
  2. On the Overview page, scroll down to Associations, and click Add.
  3. In Application, select the Rational DOORS connection. The name that is displayed is the name you entered in the Friends list.
  4. The Rational DOORS Web Access login screen is displayed. Log in.
  5. Go back to RTC.
  6. In Association, select Provides - Implementation Requests.
  7. In Artifact Containers, select the Rational DOORS module you want to work with.
  8. Click OK, and select the next association.
  9. In Association, select Provides - Requirements Change Requests.
  10. In Artifact Containers, select the Rational DOORS module you want to work with.
  11. Click OK, and then click Save to save the project.

Set up Rational DOORS to allow the connection from RTC:

  1. Log in to Rational DOORS as a database manager or a custom user who has the power to manage the database.
  2. Right-click the database root, and select the Remote Services tab.
  3. Add the RTC server to the Server List:
    1. Click Add, and enter a name for the connection (for example, RTC).
    2. Enter the URL for the root services of the RTC server.
      • If there was a clean installation of RTC 3.0, enter https://hostname:port/ccm/rootservices.
      • If RTC was upgraded from RTC 2.x, enter https://hostname:port/jazz/rootservices.
    3. Enter the consumer key and enter the consumer secret in OAuth secret. You made a note of these in step 3 and step 4 when you set up RTC.
    4. Click Register. The server is added to the list.
  4. Add collaboration links from RTC projects to the Rational DOORS database:
    1. In the Collaboration Links pane, click Add.
    2. Select the server that you registered (RTC). If a security warning is displayed, click Yes.
    3. The login page to RTC is displayed. Log in.
    4. Select the project you want to access from Rational DOORS, and click Add.
    5. Go back to Rational DOORS. The project is displayed in the Collaboration Links pane of the Remote Services tab.
  5. A Consumer Key and OAuth Secret should have been dynamically created when you added Rational DOORS as a friend to RTC earlier. If they have not been created, create a Consumer Key and OAuth Secret for the server:
    1. On the Local Keys tab of the Rational DOORS database properties, click Add.
    2. Enter the name of the connection (RTC).
    3. Enter the friends consumer key and in OAuth secret. You made a note of these when you added Rational DOORS to RTC as a friend.
    4. Click Register, and then click OK to close the database properties.

RTC and Rational DOORS are now configured to communicate with one another.


6. Define a configuration template in Rational DOORS

The next step is to define a configuration template in Rational DOORS.

Defining a configuration template uses the Change Management for Rational DOORS functionality that is built into Rational DOORS. The configuration template specifies the project area in RTC, the workflow to use, and the states and actions in RTC that are to be used by Rational DOORS.

For information about Change Management for Rational DOORS, see the Change Management for Rational DOORS manual.

Procedure

To define the configuration template:

  1. Open Rational DOORS.
  2. Click Change Management > Define Configuration Templates. Step 1 of the Configuration Template wizard is displayed.
  3. Enter a name for the template.
  4. Select OAuth as the authentication method.
  5. Select your configured RTC project area, and click Next. The RTC login screen is displayed. If a Security Alert window is displayed, click Yes.
  6. Log in to RTC. Step 2 of the Configuration Template wizard in Rational DOORS is automatically displayed.
  7. Map the RTC workflow states and actions to states and actions in the Requirements Change Management workflow.

    Note: You must use the internal workflow state and action identifiers, not the names that are displayed in RTC. If you are using the Simple Team Process in the RTC project area, you can find internal workflow state identifiers here: https://rtc:9443/ccm/oslc/workflows/project area ID/states/Workflow, and internal workflow action identifiers here: https://rtc:9443/ccm/oslc/workflows/project area ID/actions/Workflow:

    Internal workflow states and actions

    In this example, the URLs are:

    • https://jazz-server:9443/ccm/oslc/workflows/_s-z7UHPMEeCdQbc_cXlrQ/states/demo.workitem.rcrWorkflow
    • https://jazz-server:9443/ccm/oslc/workflows/_s-z7UHPMEeCdQbc_cXlrQ/actions/demo.workitem.rcrWorkflow

    When you open these URLs, an XML file is displayed listing the state identifiers and the action identifiers, for example:

    Example state identifier

    In this example, the state is Assigned, which is denoted by the dc:title, and the state identifier is RCR Workflow.state.s2, which is denoted by the dc:identifier.

    1. In Assigned State, enter the state identifier RCR Workflow.state.s2.
    2. In Review State, enter the state identifier RCR Workflow.state.s3.
    3. In Approved State, enter the state identifier RCR Workflow.state.s4.
    4. In Applied State, enter the state identifier RCR Workflow.state.s5.
    5. Select For Rational Team Concert.
    6. In Apply Action Attribute, enter the action identifier RCR Workflow.action.a2.
    7. In Review Action Attribute, enter the action identifier RCR Workflow.action.a3.
    8. In State Attribute, enter rtc_cm:state.
    9. In RCR Submit Form, select Requirement Change Request.
    10. In Conflicting Proposal Behavior, select Take no action.
    11. Clear Show RCR Recording Report and Enable Reject button in DWA:

      Step 2 of the Configuration Template wizard

  8. Click Next. Step 3 of the Configuration Template wizard is displayed.
  9. Select Plan Item in Use Submit Form and Plan Item in Use Add Form. Plan Item is one of the Change Management Binding Settings in RTC Project Area, and is bound to Story.
  10. Click Next, leave Step 4 blank, click Next, and then click Finish. The new configuration template is created.

7. Set up the module configuration in Rational DOORS

To use the integration, you must set up the module in Rational DOORS to use the configuration template.

Set up the module to use both Requirements Change Requests and Implementation Requests.

Procedure

To configure a module:

  1. Open Rational DOORS.
  2. Open the module you want to work with, and click Change Management > Configure Module.
  3. Select the RTC configuration template. This defines the project in RTC that you will connect to.
  4. Set Integration Status to ON.
  5. Select Enable Requirements Change Management to use Requirements Change Requests. The related fields can be edited. Leave them selected:
    • Create RCR Attrs View creates a view in the module that lists all the Requirements Change Requests that have been implemented against individual objects.
    • Manage External Links and Manage Internal DOORS Links manage traceability. Rational DOORS has both internal and external links, and they can be managed independently.

      Note: If you want to use the Implementation Request feature where requirements are sent to RTC for developers to use, then you must consider managing external links. An Implementation Request creates an external link to the work item in RTC. If you are managing external links, you must create an Implementation Request as part of a Requirements Change Request. If you are not managing external links, you can open the module for unmanaged changes and raise the Implementation Request.

  6. Select DOORS Attributes Managed by RCRs, choose the attributes you want to manage, and click Apply.

    By default, the integration manages the changes to Object Heading and Object Text. If you want, you can select other attributes (for example, custom attributes such as Priority, Cost, and so on).

  7. Select Enable Requirements Implementation to use Implementation Requests. The related fields can be edited:
    • Select Create IR Attrs View to create a view in the module that lists all the Implementation Requests that have been implemented against individual objects.
    • Clear Enable Requirements Gathering.
  8. Select Map Attributes for CM IR Submission, choose the attributes you want to map, and click Apply.

    The Rational DOORS attributes are listed. Associate the attributes with RTC values by entering the RTC values in the CM Attribute column. By default, Object Heading is mapped to title, and Object Text to description. Custom attribute values must match the available values in RTC. Rational DOORS does not automatically check the associations; make sure you check them manually.

    Select Managed Attributes

  9. Click OK, and then click Save.

Module configuration is complete.

Now that you have configured a module in Rational DOORS, you can proceed to use the integration.


For more information


About the author

Christopher Findlay is an Information Developer in the Rational DOORS lab in Edinburgh. He can be contacted at chris.findlay@uk.ibm.com.