Jazz Library Maintaining the Rational DOORS Next Generation type system in a configuration-management-enabled environment. Part 1: Manual procedures
Author name

clm,elm,requirements-management-doors-next,continuous-engineering-solution,rational-doors-next-generation

Tue, 06 Nov 2018
5 min read
0

Maintaining the Rational DOORS Next Generation type system in a configuration-management-enabled environment. Part 1: Manual procedures

Todd Dunnavant, Ph.D., P.E., IBM | Ian Zimmermann, IBM | Ralph Schoon, IBM
Last updated: 22 April 2019
Build basis: Rational solution for Collaborative Lifecycle Management, IBM Internet of Things Continuous Engineering Solution 6.0.6 and later

 

This article is the first in a three-part series about maintaining the type systems of configuration-management-enabled Rational DOORS Next Generation configurations. This article focuses on manual procedures for maintaining type systems. Part 2 of the series describes how to automate maintenance procedures by using published Rational DOORS Next Generation APIs. Part 3 provides recommended practices for managing variations in type systems.


This article assumes that you are familiar with these concepts:

  • Collaborative Lifecycle Management (CLM) and Continuous Engineering (CE) tool support for configuration management
  • How to work with Rational DOORS Next Generation configurations and perform common operations such as selecting a configuration and delivering changes
If you are unfamiliar with these concepts, see the Configuration management overview and Managing artifacts by using configurations sections in IBM Knowledge Center and review the related videos at the bottom of the second section.

Contents

Rational DOORS Next Generation type system and type system scope

A type system is the collection of these items for a Rational DOORS Next Generation project area or component configuration:

  • Artifact types
  • Attributes
  • Attribute data types (including enumerations and enumeration values)
  • Link types
  • Link constraints

The scope of a type system is the project area or component configuration for which it is defined.

Rational DOORS Next Generation components are the containers of versioned artifacts that are associated with a configuration-management-enabled project area.

Each configuration-management-enabled project area can have one or more components, with up to 100 components or more in a single project area.

A Rational DOORS Next Generation configuration is a baseline, stream, or personal stream that is associated with a Rational DOORS Next Generation component.

Importance of maintaining Rational DOORS Next Generation type systems

Most organizations maintain a very small number of Rational DOORS Next Generation type systems; however, there are good reasons to have more than one standard type system. For example, you might use one type system for configurations that manage informal content provided by stakeholders, and you might use a second type system for configurations that manage formal requirements derived and refined from that stakeholder content. However, there should be well-understood and agreed-to reasons for having more than one type system.

Consistent type systems are beneficial because they support these efforts:

  • Common requirements engineering processes and practices, such as creating meaningful how-to documentation that can be used by all team members who use the common type system
  • Creating and using automations to leverage the commonality of type systems
  • More effective and easier-to-perform merging of changes between editable configurations
  • Cross-team reporting
  • Basic Rational DOORS Next Generation operations, such as copying artifacts between components. The ability to copy artifacts between components depends on the source and target component configurations having identical type systems. For details, see Copying artifacts between projects in IBM Knowledge Center.

The absence of consistent type systems has a negative effect on these efforts. For example, having inconsistent type systems significantly impairs cross-team reporting. More concrete examples of these scenarios are described later in this article.

Manual procedures for maintaining Rational DOORS Next Generation type systems for editable configurations

As important and beneficial as it is to have consistent type systems, maintaining consistency can be challenging for large Rational DOORS Next Generation implementations. For example, some organizations have hundreds of components and thousands of editable configurations (streams and personal streams). A change to the organization’s common type system definition must be applied to each component and then to each editable configuration. For organizations with large or substantial numbers of components and configurations, success depends on well-defined maintenance approaches that are performed consistently.

Recommended practices

  • All configurations managed by a Rational DOORS Next Generation component should adhere to the same type system. For example, if an organization maintains one type system for informal input and another type system for formal requirements, all configurations in a component should adhere to one type system or the other. Mixing the type systems for the configurations in a component can be confusing and cause errors.

  • For all streams on all components, enforce the policy that edits must be captured in formal change sets. You select this option on the Details tab as shown in the following image.

  • Create a Master type system maintenance component for each type system on each Rational DOORS Next Generation server in the environment. All other components, the ones to which type system changes are imported, are dependent components.

  • Create a standard stream in each Master type system maintenance component, from which change sets are created to perform each instance of type system maintenance.

    • In each standard stream, on the Details tab, select the option that states change sets must be linked to an approved work item before they are delivered. Work items capture the motivation for the changes in each instance of type system maintenance.

  • Ensure that each type system element (all artifacts, attributes, attribute data types, attribute data type values, and link types) in each type system has an associated URI (URL-formatted tag). In Rational DOORS Next Generation, enumeration values are referred to as URIs or RDF URIs. Rational DOORS Next Generation uses these URIs to identify semantically equal elements across type systems. For details about URIs, see Creating attributes for requirement artifacts in IBM Knowledge Center. Many of the type system elements in the Rational DOORS Next Generation project area and component templates have URIs assigned to them. See those templates for sample URI formats.

    • Consider a situation where you create a type system element named Attribute1 and you apply this new attribute to your configurations. Later, you decide to rename this attribute Attribute2. You make the name change and apply it from your master type system component to the streams of your other components.
      • If you did not previously assign a URI to your attribute, the type system import mechanism determines that Attribute2 is a new attribute and your type systems now include two attributes: Attribute1 and Attribute2.
      • If you did assign a URI to Attribute1 before you apply it to the other configurations, the type import mechanism recognizes that Attribute2 is the same attribute, and the original attribute is renamed to Attribute2 (which is the desired result).

  • Do not change a type system element’s URI if you rename the type system element. Doing so will result in type system divergence. Repairing this divergence requires the specialized Rational DOORS Next Generation Reporting Tool from IBM Software Support. 

  • Never reuse an obsolete type to define a new type system concept. If a type is no longer used and a new vocabulary concept is being introduced, do not rename the type that is no longer in use to match the new vocabulary concept. Instead, create a new type.

    • Consider an enumeration named Level that no longer needs a value of Critical, but needs a new value of Safe, which is semantically different from Critical.
      • Do not rename Critical to Safe. If you do, all the configuration’s artifacts that had a Level value of Critical will then have a Level value of Safe.
      • Instead, delete the Critical value from the enumeration and add a new Safe value. Then, all the configuration’s artifacts that previously had a Level value of Critical will have null values. You can easily identify and update these artifacts by using Rational DOORS Next Generation views.

  • For each dependent component, designate a specific stream as the standard recipient of type system imports from the type-system-compatible Master type system maintenance component. Subsequent change delivery operations are easier if this is the initial stream that is created automatically when a Rational DOORS Next Generation component is created.


Maintaining Rational DOORS Next Generation type systems in a single-server environment

To maintain a type system in a single Rational DOORS Next Generation server environment, complete these steps:

  1. Make the type system changes in the Master type system maintenance component.
  2. Import the type system changes into the dependent components that use that type system.
  3. Deliver the type system changes into each stream of each dependent component.
Additional steps, described later, are required to migrate type system changes between servers.

Product APIs are available to automate the import and delivery of type system changes across same-server components and streams. Automation is addressed in Part 2 of this article series. Part 2 also provides code for a sample command-line utility that performs these automations.

Make the type system changes in the Master type system maintenance component

  1. Create a Rational Team Concert work item to capture the motivation for, and describe, the type system changes.
  2. Set your browser to the appropriate configuration management context:
    • The Master type system maintenance component, which is the master of the type system to change
    • The component’s standard stream for capturing type system changes
  3. Create a new change set, provide a name that reflects the work, and associate the change set with the work item. In this example, the change set is named Type system change set A.
  4. Make your type system changes.
  5. Have your work reviewed, have the work item approved, and then deliver Type system change set A to the Master type system maintenance component’s standard stream.

Import the type system changes into dependent components

For each dependent component, complete the following steps:

  1. Set your browser to the appropriate configuration management context:
    • The dependent component
    • The component’s standard stream into which type system changes are imported
  2. Create a change set to receive the type system changes. In this example, the change set is named Type system change set A import.
  3. Attach this change set to the Rational Team Concert work item that you created in the previous procedure. Attaching the change set to the work item helps document which components received the type system changes from the Master type system maintenance component.
  4. In your browser, click the Settings (gear) icon, and select Manage Component Properties.

     

  5. Select the Import Component Properties link on the right.



  6. In the Import Component Properties dialog box, click Browse and navigate to the Select a Component Configuration window.
  7. Select the project area, the Master type system maintenance component, and its standard stream into which you delivered the type system changes. Click OK.

  8. Confirm your selections and click Next.
  9. Review the type system changes. If they are correct, click Finish. The type system changes are imported into your change set.
  10. Deliver your change set to the component’s standard stream for receiving type system changes.

Deliver the type system changes into each stream of each dependent component

After you complete the previous procedure, complete these steps:

  1. Set your browser to the appropriate configuration management context:
    • The dependent component that received the type system changes
    • The component’s standard stream into which type system changes were delivered in the previous procedure
  2. In your browser, click the Settings (gear) icon, and select Manage Components and Configurations. A window shows the active configurations for the component.
  3. Select the streams view. A window opens and shows the hierarchy of streams in the component. The type system changes must be delivered from the initial receiving stream to each of the other streams.
  4. Select the check boxes for the two streams and click the Deliver changes icon as shown in the following image.

  5. Deliver the changes to the target stream using the standard delivery tools. After the delivery is complete, you return to the streams hierarchy view.
  6. Repeat the delivery operations until the type system changes are delivered to each of the component’s streams.


Maintaining Rational DOORS Next Generation type systems in a multiple-server environment

As of Rational DOORS Next Generation version 6.0.6 iFix003, you cannot use the Import Component Properties link to import properties between components that are managed using different Rational DOORS Next Generation servers. You must use an alternative procedure to migrate type systems across servers.

Recommended practices

The recommended practices for a single-server environment also apply to a multiple-server environment. In addition, adhere to this additional practice:

  • Select a specific Master type system maintenance server as the source for the type system changes. Ensure that all type system changes originate on this server.
This practice extends the recommendation to have a Master type system maintenance component for each type system on a Rational DOORS Next Generation server. In this case, an additional layer is added to the type system migration hierarchy: type system changes are first made in the Master type system maintenance components of the Master type system maintenance server. The changes are then migrated to the Master type system maintenance components of the other Rational DOORS Next Generation servers in your environment. These servers are dependent servers.

Migration mechanisms

You can migrate type system changes across servers by these file-based approaches. Each approach has its advantages and disadvantages.

  • Project or component templates

    • Templates enable you to transfer all type system elements (artifact types, attributes, attribute data types, link types, and link constraints) to the dependent Rational DOORS Next Generation servers.
    • Templates require you to create a new Master type system maintenance component on each server each time you migrate type system changes, because you cannot apply a new project or component template to an existing project area or component.
    • If you also maintain process elements, such as roles and permissions, in the Master type system maintenance component of your Master type system maintenance server, you must redirect each dependent component to the new Master type system maintenance component.

  • ReqIF file export and import

    • Requirements Interchange Format (ReqIF) is an industry standard format for transferring artifacts and inter-artifact links between requirements management systems. The type system elements associated with the artifacts and links are also transferred to the target system.
    • ReqIF transfers a subset of type system elements: link constraints are not transferred because ReqIF doesn’t include Rational DOORS Next Generation link constraints in its specification.
    • To transfer all changed type system elements, a body of artifacts and inter-artifact links that spans the changed aspects of the type system must be included in the ReqIF export. The type system elements needed to support the transferred artifacts and links are also part of the transfer.
    • ReqIF enables you to reuse each server’s Master type system maintenance component for each round of type system migration. ReqIF can be used to import changes into the same component, many times.

To migrate type system changes between servers, component templates are preferred because they can migrate all type system elements, including link constraints. With ReqIF, the migration of type system changes is secondary to the transfer of artifacts and can be a potential source of error. Administrators must be careful to ensure that each ReqIF export includes sufficient artifacts and links to span the current round of type system changes.


To maintain Rational DOORS Next Generation type systems in a multiple-server environment:

  1. Make the type system changes in the Master type system maintenance component of the Master type system maintenance server. Follow the instructions in the single-server procedure.
  2. Create a new component template from this component. Follow the instructions in Creating templates for requirements projects or components in IBM Knowledge Center. In this case, select the options to include the following project elements:
    • Artifact types and attributes
    • Link types
    • Preferred Link types
  3. Use the new component template to create a new Master type system maintenance component on each dependent Rational DOORS Next Generation server. Follow the instructions in Creating requirements projects in IBM Knowledge Center.
  4. For each dependent server, import the type system from the new Master type system maintenance component into each dependent component that uses that type system. Follow the instructions in the single-server procedure.
  5. Deliver the type system changes into each stream of each component. Follow the instructions in the single-server procedure.

Scenarios for maintaining Rational DOORS Next Generation type systems for baselines and editable configurations

Consider the following situation:

  • You have followed all recommended practices for maintaining your Rational DOORS Next Generation type systems. As you gain experience with Rational DOORS Next Generation, you realize that an attribute named Priority is too generic and clashes with other attributes in your system. You rename Priority to Customer Requested Priority and apply the rename to all editable configurations. But, you’ve already created several baselines with the attribute named Priority. These different names can cause problems if you need to create reports that span older baselines and newer streams, or if you need to create a new stream from an older baseline where the attribute is still named Priority.

    • If no URI was defined for the attribute, or if you haven’t applied the URI to all components, users might still see Priority in Report Builder reports, because of data contributions made by baselines in the Lifecycle Query Engine reporting repository.

    • If a URI was defined for the attribute and you did not apply the new name, Customer Requested Priority, to all components and their configurations, teams that still use Priority for the attribute might start seeing Customer Requested Priority in their reports. The results depend on which content is accessed from Lifecycle Query Engine. Even if these projects change the attribute name to Customer Requested Priority, all reports might not consistently reflect the new name, because of old baselines that still contribute Priority to Lifecycle Query Engine.

If problems occur because streams and baselines either contain obsolete type names or don’t include type system URIs, the Rational DOORS Next Generation Reporting Tool is available from IBM Software Support. The tool assesses Rational DOORS Next Generation data health, performs data validation, and repairs data inconsistencies, such as updating baselines to replace old names of type system elements with current names. The tool should only be used under the guidance and direction of IBM Software Support.

The Rational DOORS Next Generation Reporting Tool performs operations directly against the Rational DOORS Next Generation repositories. Read and understand the utility’s documentation, and back up your Rational DOORS Next Generation data, before you use the tool on production data.

The Rational DOORS Next Generation Reporting Tool does not target specific configurations. For example, you cannot use the tool to repair recent discrepancies but retain previous type systems in older baselines: you can’t repair one set of configurations while leaving another set untouched.

Related information

About the authors

Todd Dunnavant, Ph.D., P.E., is the Continuous Engineering Practice Lead and a Principal Solution Architect with IBM Watson IoT Services. He has 20 years of experience successfully transforming how software, systems, and product engineering teams work. For the past 7 years, Todd has focused on realizing these transformations using the IBM Jazz-based products. More recently, Todd has helped multiple product-centric companies adopt the lifecycle configuration management capabilities of the IBM Internet of Things Continuous Engineering tool suite. He can be contacted at twdunnav@us.ibm.com.

Ian Zimmermann is a CLM Solution Architect who has led requirements management, CLM, and global configuration implementations for many years. A former aerospace engineer with the Canadian Military, Ian has also held roles including Director of IZTech (an IBM Business Partner) and Director of Requirements and Project Portfolio Management for Telelogic. With deep expertise in the CLM suite and Rational DOORS, Ian is a Certified Rational DOORS Next Generation expert and has successfully migrated over 75 databases from Rational DOORS to Rational DOORS Next Generation. He can be contacted at ianz@ca.ibm.com.

Ralph Schoon is a member of the IBM Watson IoT Unleash the Labs team, which has a mission to help IBM staff and customers apply Jazz technologies. Ralph has his own blog about extending and automating Rational Team Concert. He has published multiple articles on Jazz.net and is committed to working with Jazz users on the Jazz.net forums to help them understand the technical details of the Jazz products and optimize their solutions. Before his current role, Ralph worked as a Leading Technical Sales Representative for IBM, a team lead and developer for machine control for an industrial company, a developer, a Microsoft Certified Professional, and a system and network administrator. He can be contacted at ralph.schoon@de.ibm.com.

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.

Tue, 06 Nov 2018