Jazz Library Configuration management: Best practices for collaborating with ReqIF between Rational DOORS Next Generation instances
Author name

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

Wed, 28 Nov 2018
5 min read
0

Configuration management: Best practices for collaborating with ReqIF between Rational DOORS Next Generation instances

Ian Compton, Kathryn Fryer, Yianna Papadakis-Kantos
Last updated: 27 November 2018
Build basis: IBM Rational solution for Collaborative Lifecycle Management and IBM Internet of Things Continuous Engineering Solution 6.0.6 and later

 

This article is one in a series that provides guidance and practices for configuration management in the IBM Rational solution for Collaborative Lifecycle Management (CLM) and IBM Internet of Things Continuous Engineering (CE) Solution. This article addresses data exchange between Rational DOORS Next Generation projects. Another article (coming soon) addresses practices for ReqIF exchange between IBM Rational DOORS Next Generation and IBM Rational DOORS 9 projects.

Many organizations that use IBM Rational DOORS Next Generation collaborate with one or more external partners to specify, refine, and fulfill requirements. Partners might exchange data multiple times to clarify and negotiate details. Typically, organizations use the Rational DOORS Next Generation Requirement Interchange Format (ReqIF) capabilities to exchange requirements. With Rational DOORS Next Generation projects enabled for configuration management, using ReqIF can become more complex. This article describes considerations and practices for ReqIF with configuration-enabled projects.

This article assumes that you are familiar with these concepts:

  • Collaborative Lifecycle Management (CLM) and Continuous Engineering (CE) configuration management capabilities
  • ReqIF import and export in Rational DOORS Next Generation.
If you are unfamiliar with these concepts, see Configuration management overview, Managing artifacts by using configurations, and Importing and exporting ReqIF files in IBM Knowledge Center. Additional information on best practices for configuration management and Rational DOORS Next Generation type system maintenance are included at the end of this article.

The practices in this article also reflect the following constraints related to information exchange between partners:

  • Organizations might share only a subset of requirements or attribute values with any given partner.
  • Organizations might need to restrict partners from viewing their internal data, or data from other partners.
  • Organizations want a record of what was shared with a partner and what was returned.
  • Organizations usually maintain their own type systems that they don’t want affected by partner data.

This article uses the following terms or roles to represent the parties in a collaborative partnership:

  • Original Equipment Manufacturer (OEM): An organization that incorporates components or work products from other organizations into their own branded products or solutions.
  • Supplier: An organization that creates and delivers a component or work product for another organization or OEM.

Contents

General guidance for ReqIF exchange

Many practices are similar for both the OEM and supplier roles, and vary mostly by how they are applied. This section presents general guidance, and the following sections present the practices from the perspective of each role.

 

Preparing to exchange data
  • Where possible, use separate components for the requirements to exchange.

    Because type systems are defined at the component level, you can isolate the types for the partner relationship from the other requirements in your internal systems. If you allow partners to access the requirements in your system and want to restrict their visibility to only the shared components, put the components in a separate project area, because read access is granted at the project-area level.

    ReqIF does not preserve cross-component links. If you need to share linked requirements, they should reside in the same component. If the linked artifacts are in the same component, you can export them in separate ReqIF packages. When both packages are imported, ReqIF will reconstruct the intra-component links.

  • Define your component’s type system, including RDF URIs for artifact types, attributes, and link types.

    For more information, see Maintaining the Rational DOORS Next Generation type system in a configuration-management-enabled environment. To minimize duplication or conflicts during data exchange, establish the URIs and their format with your partners.

  • Use modules and module views to define the artifacts and attributes to export.

    Views must be public and specific to a module (not shared across modules).

  • Define ReqIF packages in the component properties before you create a baseline to export from.

    Because baselines can’t be changed, you can’t update properties to create a new ReqIF definition in a baseline.

Exporting a ReqIF package
  • Before exporting or importing, ensure that you are in the correct configuration context.

    ReqIF operations always occur in your current context, which can be a global or local configuration. To import, you must be in a stream.

  • Export from a baseline, so you know and can re-create exactly what you send. Use work items or a similar tracking system to record what was created when, by whom, and for what purpose.

    When you export from a baseline, you can be sure that nothing will change during the export, and if necessary, can recreate that export or branch a new stream with certainty that it matches what was exported. However, because baselines can’t change, the system can’t save the ReqIF package with the component properties as it would for a stream. Ensure that you download the package when you generate it. It’s also a good practice to create a work item or other tracking mechanism where you can attach or store the package, along with the details on who created it, when, from what baseline, and for what purpose.

  • Follow good baseline practices, as described in Best practices for CLM/CE global configuration management, including using naming conventions and archiving baselines that you no longer need.

    Although baselines are not resource-intensive, large numbers of baselines can affect usability and performance, for example, when you select a configuration context to work in or report on. Naming conventions for both baselines and streams are essential to ensure that users can correctly identify the desired configuration.

Importing a ReqIF package
  • Import into a change set so that you can review the imported changes and discard them if you see issues.
  • Select the attributes to import from the package to ensure that you get only desired changes and avoid any unexpected effects on other attributes or the type system.

    In Rational DOORS Next Generation version 6.0.6 and later, you can choose which attributes to import from the package; in earlier releases, you import all included attributes. Carefully determine what is imported and potential effects to your type system. Be especially careful of importing type changes, which will affect the target import stream and any other streams to which you deliver changes from the import stream.

  • If multiple partners collaborate on the same requirements, import each partner’s package into its own stream, separate from the original requirements stream. 

    Depending on your needs, you might have standard attributes that each partner completes, or partner-specific attributes.

  • Take a baseline after you import a package so that you have a record of what was sent and can compare to the original versions or future updates.

Additional considerations
  • Observe the ReqIF limits on package size. The maximum compressed file size is 150MB by default, and the maximum upload size is 50MB.

    You can increase these limits in the Requirements Management (RM) administration Advanced Properties under RM Client Component. Consider that import and export operations can be resource-intensive operations. Large amounts of change can also cause change set deliveries to slow down or time out. You can create more granular packages. As noted above, ReqIF can preserve links across packages if they are within the same component. If creating smaller packages is not viable, contact IBM Support.

  • Consider using work items to formally track key exchange activities.

    For additional governance for delivering ReqIF import results, you can require a Rational DOORS Next Generation change set to be linked to an approved change request. For details, see Associating change sets in the RM application to work items in IBM Knowledge Center.

Guidance from the OEM perspective

This section reiterates several practices from the perspective of the OEM, who will share information with the supplier. The OEM scenario illustrates how the practices might apply in a usage scenario.

 

Preparing data to exchange
  • Where possible, keep the requirements that you will exchange with partners in components separate from the requirements that you manage internally.

    Because the type system is managed at the component level, your partner requirements can include different types and attributes, if necessary, and any changes introduced by imports will not affect the types in your other components. You can still link across components if it is appropriate to relate your internal and partner requirements. 

    Note: If you are exporting from more than one component, ReqIF does not preserve or reconstruct any cross-component links. If you export multiple packages from a single component, with links that span those packages, ReqIF will reconstruct those links when you import both packages into a new component. If you want the requirements from the imported package to link to requirements in other components, you must manually reconstruct those links.

    If you have discrete sets of requirements for different partners, create a different component for each set. If you share one set of requirements with multiple partners, reuse the same component or components with one stream per partner.

  • Define your type system, including external URIs, and gain agreement from partners.

    Maintaining a type system with defined URIs is a best practice itself, and described in Maintaining the Rational DOORS Next Generation type system in a configuration-management-enabled environment. If a partner uses the same attribute name with a different URI (or no URI), or a different attribute name, you could end up with duplication or conflicts.

  • Include attributes that your suppliers will update and return.

    Typically, you expect feedback from each supplier with whom you share the requirements, such as comments and whether they accept the requirement. In the component’s type system, add the attributes for each supplier to complete, for example, Supplier1-Comments, Supplier1-Acceptance, Supplier2-Comments, Supplier2-Acceptance, and so on. Those attributes would initially be blank, and set by the supplier when it returns the requirements.

  • Use modules to organize requirements within the component and module views to define what to export.

    Instead of sharing an entire module with the supplier, you can specify which artifacts and attributes to include in the ReqIF package. For each module, define one or more module views to filter the requirements and attributes. The view must be public and specific to a given module (not shared across modules). If you exchange the same requirements with multiple suppliers, but with different attributes (as described above), define views for each supplier.

    In each view:

    • Specify the artifacts in the module to share with the supplier, including any headings or supplemental artifacts. Consider what background data suppliers might need to understand, as well as what they need to change.
    • Include all necessary attributes to communicate with different suppliers. For example, you might have one view that includes Supplier1-Comments and Supplier1-Acceptance, and another that includes Suppler2-Comments and Supplier2-Acceptance.
    • Exclude any attributes that the specific supplier should not see, for example:
      • Attributes that are sensitive or proprietary to the OEM
      • Attributes intended for use by a different supplier
      • Attributes not needed by the supplier, which can be excluded for clarity and efficiency

  • On the ReqIF tab of the component properties, create ReqIF package definitions for each supplier.

    Just as you create different views for each supplier, you’ll create different packages that use those views. For example, your Supplier1 ReqIF definition will include the module views to share with Supplier1 (including the Supplier1-related attributes), while the Supplier2 definition will include the module views to share with Supplier2 (including the Supplier2 attributes).

    You can include views for multiple modules in a single ReqIF package. When you define the package, first select the module, then switch to the Select View tab to select and add the view for that module. Continue to select and add views until you include all the module views for the supplier.

    The ReqIF package will include only the attribute definitions and types visible in the view: the supplier importing the package has no awareness of any other attributes or artifacts that might exist outside the views. You can’t prevent suppliers from updating any of the artifacts or attributes in the package. However, when you import the returned package, you can specify which attributes to update (as of version 6.0.6 and later).

Exporting and importing ReqIF packages
  • Export from a baseline so that you have a record of the state of the artifacts when the ReqIF package was sent and can recreate that same state later if necessary. Use work items or other tracking mechanisms to keep a record of the export for future reference.

    Because baselines can’t be changed, you must create the ReqIF package before you generate the baseline. For the same reason, the generated ReqIF package is not stored with the baseline. When the export finishes creating the ReqIF file, you must click Download to save it. If you close the dialog box without downloading, you must repeat the export operation. Create a work item or other tracking mechanism where you can attach or store the package, along with the details on who created it, when, from what baseline, and for what purpose. You can use this work item to track the exchange with the supplier and as a record of the work.  Note: If you export from a stream, the stream records the ReqIF package on the ReqIF tab in the component properties and you can access it later without repeating the operation.

  • Ensure that you set your configuration context correctly before you perform the ReqIF export or import.

    The ReqIF operations use your current configuration context to determine which artifact versions to include.

  • Import the ReqIF package returned from the supplier into a different stream from your original requirements, branched from the baseline you used to send the package. When collaborating with multiple suppliers, import each supplier’s response into a separate stream.

    Keeping supplier responses separate from your original requirements makes it easier to update and resend your requirements, as well as update responses from the supplier, which reduces potential conflicts and data loss. Having a separate stream per supplier ensures that you don’t accidentally overwrite or confuse data between suppliers and maintains a clear record of each supplier response. You can also compare responses across supplier streams, and to your own original requirements stream.

    You might or might not choose to merge changes from a supplier into a common stream. Depending on your process, you might want to keep your original requirements and any supplier responses separate, or you might want to merge responses into a common stream to see data from multiple suppliers in one location. Delivering changes across streams will include any changes to the source type system.

  • Use a change set for each ReqIF import. Ensure that you have an established baseline of the stream before you import.

    The returned ReqIF package might include new or deleted artifacts or type system changes. Using a change set for import enables you to review the changes before you deliver them, which provides more control over the changes and the ability to discard undesirable results. For even tighter governance, you can also require an approved change request to deliver the change set. Having a baseline ensures that you can return to a known state if the delivery causes problems.

  • Use selective import (version 6.0.6 and later) to restrict the attributes and associated type changes that are imported.

    In version 6.0.6 and later, you can choose which attributes to import from the ReqIF package, which can help you avoid unwanted changes to the type system or to other attributes that you manage internally. You can’t restrict partners from modifying any of the data that you send them, but you can restrict what you import back. If you’re using an earlier version of Rational DOORS Next Generation, the import includes all attributes. Carefully review what is imported before you deliver changes. You can also use a separate stream for the supplier imports, and if there are type changes, avoid delivering changes from that supplier stream into other streams. You can also ask your partners to define their ReqIF packages so that they include only the specific attributes you asked them to update.

  • Take a baseline after each import operation to maintain a record of each supplier response.

For an example of how an OEM might apply these practices as it interacts with suppliers, see the OEM scenario.

 

Guidance from the supplier perspective

This section reiterates several practices in the general guidance from the perspective of the supplier who receives requirements from one or more OEMs and returns a response. The Supplier scenario illustrates how a supplier might apply these practices in a usage scenario.

  • Ideally, start with a separate and empty component for each OEM partner and project. If you need to restrict read access to the component, put it in a separate project area.

    Importing the initial ReqIF package from the OEM will set the type system and populate the component. Avoid making any modifications to the type system that would affect what you return to the OEM. You can still create links between the OEM requirements and artifacts in your own internal components; those links are not included in the views you export, so do not affect the type system in the package.

  • Import into a change set, so that you can review and control the delivery of changes.

    This practice is especially important after you establish your initial component content.

  • Maintain a separate stream for importing the OEM requirements, and create a separate stream to update the requirements for your response.

    Keeping the input in a separate stream protects it from inadvertent changes and enables comparisons with your response. If the OEM sends an updated package, you can import it into the original OEM import stream without affecting work already completed on your response. If appropriate, you can deliver updates from the import stream into your response stream or branch a new stream from the updates and possibly deliver changes from your original response stream into a new response stream.

  • Each time you import a ReqIF package from the OEM, take a baseline before you make any changes.

    With a baseline, you can easily review what was originally sent and, if necessary, branch from the original contents. You can also compare your response to the baseline of what the OEM originally sent.

  • Understand which attributes the OEM expects you to modify.

    After you import the ReqIF package, you can modify anything that it contains. However, your OEM partner might want you to restrict changes to specific attributes. Avoid changing other attributes, or making changes to the type system, including URIs.

  • Baseline your response stream before you generate the ReqIF package to return to the OEM.

    The baseline gives you a record of what you are sending back. You can reuse the ReqIF definition that you imported from the OEM for your export. If you need to modify that definition, do so before you create the baseline: you can’t modify the definition in the baseline. As explained previously, your export package will not be recorded or stored with the baseline. Generate a work item or other tracking mechanism to store the exported package, capturing details of who created it when at on which baseline, and tracking the exchange with the OEM.

  • Ensure that you set your configuration context correctly before export (or import). As noted previously, ReqIF operations use your current configuration context.

Sample scenarios that illustrate the practices

The following sample ReqIF scenarios further illustrate the practices from both the OEM perspective and supplier perspective. The OEM is collaborating with at least two different suppliers on a set of requirements. The supplier is responding to a single OEM.

OEM scenario

OEM prepares and sends data to suppliers

The OEM creates a component named “OEM Reqts” to share with multiple suppliers. In this component, the OEM establishes a type system with defined URIs that includes additional attributes for Supplier1-Comments, Supplier1-Acceptance, Supplier2-Comments, Supplier2-Acceptance, and so on. The OEM populates the component, and uses change sets to create and modify requirements as appropriate.

For each module in the component, and for each supplier, the OEM defines public, module-specific views based on what it wants to exchange with the supplier. Each supplier has a different view to include the specific attributes to update. The modules and requirements might have links to other artifacts in the OEM systems. Those links are excluded from the views, and because the links are outside the component, they are not part of the export anyway. The views and export could include artifact links within the component.

In the component properties, the OEM creates a ReqIF definition for the requirements to share with each supplier, using the module views defined for that supplier.

The OEM takes a baseline of the component stream, gives it a meaningful name based on established conventions (OEM V1.0 in this example), and switches to the baseline configuration context. From the component properties, the OEM selects and right-clicks the ReqIF definition for Supplier1, and then selects Export. When the export finishes creating the ReqIF file, the OEM clicks Download to save the exported file, which includes only the artifacts and attributes included in the module views specified in the Supplier1 ReqIF definition. The OEM sends the ReqIF file to Supplier1.

The OEM repeats the same steps to export the ReqIF package for Supplier2 and sends that package to Supplier2.

 
OEM receives a response from Supplier1

After preparing its response, Supplier1 sends the ReqIF package back to the OEM. To import the updated requirements from Supplier1, the OEM creates a new stream from the baseline used to send the requirements (in this case, OEM V1.0), names it to reflect the supplier, and switches to the new Supplier1 stream context.

The OEM creates a change set to import the changes. Depending on the governance required, the OEM could link the change set to a change request to track the delivery. When it imports, the OEM might choose to select only the Supplier1_Acceptance and Supplier1_Comment fields to ensure it receives no other unexpected changes. The OEM reviews what else might be imported, and ensures that changes will not adversely affect its type system.

After importing Supplier1’s ReqIF package, the OEM verifies the changes in the change set, and compares it to the current Dev stream and the OEM V1.0 baseline. After it is satisfied, the OEM delivers the change set. The OEM has some ability to accept, reject, or merge changes to the artifact content as part of the change set delivery: all changes to the type system are delivered with the change set.

After delivering the change set, the OEM baselines the new stream so that there is a record of what the supplier returned.

Note: If Supplier1’s response included multiple ReqIF packages (for example, because of size limits), the OEM would create a change set for each of the packages and create a baseline after each successful import and delivery. If there were links between artifacts in those different packages, they would be reconstructed when all imports to the component were complete.


OEM sends an updated request to the suppliers

The OEM identifies changes to the requirements and uses change sets to update the artifacts in the component stream. If necessary, the OEM changes the module views and ReqIF definitions as well. The OEM creates a new baseline named OEM V1.1.

From that baseline context, the OEM exports and downloads updated ReqIF packages for each supplier, which it send back to the suppliers.

Note: In this sample scenario, the OEM is sending updates to all the suppliers, so it uses the main development stream. The OEM might also want to question or amend the response from a specific supplier, for example, to continue a discussion. In that case, the OEM might choose to export from the supplier response stream, and ensure that appropriate baselines are in place before making any modifications to that stream, and before exporting the ReqIF package.


OEM receives responses to the OEM V1.1 request

Supplier1 responds to the updated OEM V1.1 package with its own updated ReqIF package. When the OEM receives the updates, it uses the stream it established for Supplier1, and ensures there is a current baseline that represents the previous response.

The OEM then creates a new change set on the supplier stream, and optionally links it to a change request. The OEM repeats the same steps as when it imported the initial response: reviews and selects the attributes to import from the ReqIF file into the change set, verifies the contents in the change set after the import, delivers the change set, and takes a new baseline to capture the updated response.

The OEM did not deliver changes from the OEM Dev stream into the Supplier1 stream because the Supplier1 stream represents the supplier’s response. However, OEM V1.1 updates will end up in the supplier’s updated response and, therefore, in the Supplier1 stream after that import.

The OEM can compare the most recent Supplier1 response to the previous response as well as to the OEM Dev stream and baselines.

Supplier2 also sends a response to the OEM V1.1 requirements; it did not send a response to the original request. The OEM proceeds as it did for the initial response from Supplier1: it branches a new stream for Supplier2 from the baseline where the request originated, in this case OEM V1.1. The OEM creates a change set on the new stream, optionally linked to a change request, imports and verifies the Supplier2 content, delivers the change set, and takes a baseline to capture the content that was sent.

The OEM can compare across the supplier streams, as well as to the OEM Dev stream and its baselines. If appropriate, the OEM can create a new stream to consolidate all the supplier input to view all the content in a single stream, while still maintaining a separate stream of the original requirements (not shown in the illustration). Because the OEM used partner-specific attributes, those attributes remain distinct, although other changes to the requirements must be merged and their origin is less clear in the merged stream. If the OEM uses a single set of generic attributes to capture partner input, the input must remain in separate streams.

When the OEM later updates requirements to generate an OEM V2.0 baseline and ReqIF package, the same actions repeat: the OEM sends the updates to the suppliers, imports updated responses into the appropriate supplier response stream, and ensures baselines are taken to capture what was sent and received.

 

Supplier scenario

This scenario explores the same situation from the perspective of Supplier2.

 

Supplier2 receives OEM requirements and updates

Supplier2 has created a new empty component named “OEM1” for requirements from this OEM for this project. Supplier2 has components for each OEM partner it works with, as well as components for its own internal requirements, which are not shared with partners.

When Supplier2 receives the OEM V1.0 package, it creates a change set on the OEM import stream to import the ReqIF package. The import includes all the requirements and attributes (and corresponding type system), as well as the module views and the ReqIF package definition. Supplier2 verifies the content from the import and delivers the change set. Supplier2 might optionally link the change set to a change request for governance. Immediately after completing the import, Supplier2 takes a baseline, and applies its established naming conventions (OEM V1.0 in this example), so it has a record of exactly what was sent.

Before Supplier2 starts work on this project, the OEM sends an updated ReqIF package OEM V1.1. Supplier2 ensures there is a baseline for the previous package and creates a new change set in the import stream. Supplier2 follows the same steps as for the initial import, verifying the content in the change set before delivering the change set and taking a new baseline.

 
Supplier prepares and sends a response to the OEM

Supplier2 is now ready to start work and branches a new stream from the most current baseline (OEM V1.1) to capture its response to the OEM.

In its response stream, Supplier2 reviews the OEM requirements. Supplier2 uses change sets to update the requirements according to the OEM’s requests, for example, ensuring to specify values for Supplier2_Comments and Supplier2_Acceptance. Supplier2 can update any of the imported content; however, the OEM might or might not accept unexpected changes. Where appropriate, Supplier2 might link requirements from its internal components to the OEM’s requirements, for example, to establish coverage. If necessary, Supplier2 can update the views and ReqIF definition it will use to send content back to the OEM, or it could use what the OEM included in the original package; that decision depends on the agreement between the two partners.

When Supplier2 completes its work, it takes a baseline of its response stream. From the baseline in the response stream, Supplier2 exports the ReqIF package, downloads it, and sends it back to the OEM.


Supplier2 receives and responds to the subsequent OEM update

The OEM sends another updated package (OEM V2.0) to Supplier2. Supplier2 ensures the OEM import stream has a current baseline. Supplier2 then repeats the same steps as before to import this new package into a change set in the OEM import stream, and delivers after it validates the package.

Supplier2 can then compare the new OEM V2.0 baseline to the previous baseline, as well as to the response to the previous baseline. Depending on the nature of the change, Supplier2 might choose to deliver changes from the OEM import stream to its response stream. If it does deliver the changes across streams, Supplier2 ensures the response stream has a current baseline before that delivery and takes a baseline after the delivery.

Supplier2 continues to update the requirements in its response stream, and uses change sets as before. After the changes are complete, Supplier2 takes a baseline of the response, and switches to the context of that baseline. Supplier2 exports and downloads the updated ReqIF package from the response stream, and returns it to the OEM.

Summary

For many organizations, ReqIF offers a way to collaborate on requirements with partners. Using ReqIF with configuration-enabled Rational DOORS Next Generation projects can offer benefits, such as separate streams for partner imports and exports, baselines to capture content as received or sent, and change sets to verify and control change. Following the practices in this article can help you realize the benefits while avoiding potential issues.

Ensure that you also follow the best practices for configuration management in general, as referenced in the related information.

Related information

About the authors

Ian Compton has worked in software and system testing for 19 years, starting with testing Rational DOORS 4 for QSS in 1999, and moving on via Telelogic to system testing the IBM CLM, SSE, and CE solutions. He recently started a new role as a Solution Architect for the presales team at Persistent Systems Limited. He can be contacted at ian_compton@persistent.com.

Kathryn Fryer is a Solution Architect with over 25 years at IBM, most recently focused on the IBM CE/CLM solutions including Global Configuration Management. She works closely with customers, sales, and development to develop usage models, aid adoption, and improve product offerings. She can be contacted at fryerk@ca.ibm.com.

Yianna Papadakis Kantos is focused on defining and developing education. She works closely with management and customer-facing teams to align learning deliverables with business goals. Leveraging her proven consulting, project management, and instructional design skills, she delivers education that demonstrates the value and technical use of IBM Watson IoT solutions and products. She can be contacted at ypapadak@us.ibm.com.

© Copyright IBM Corporation 2018, 2019

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.

Wed, 28 Nov 2018