EditAttachPrintable
r5 - 2016-12-14 - 19:23:25 - Main.fryerkYou are here: TWiki >  Deployment Web > DeploymentTroubleshooting > PerformanceTroubleshooting > HowDoIDetermineIfMyNetworkHasAProblem > ConfigurationManagementFAQ

Frequently-asked questions (FAQ) about CLM configuration managementnew.png

Authors: KathrynFryer
Build basis: Rational solution for Collaborative Lifecycle Management (CLM) 6.x

This page answers common questions about the configuration management capabilities that were introduced in version 6 of the Rational Collaborative Lifecycle Management (CLM) solution, including Rational DOORS Next Generation (DNG), Rational Quality Manager (RQM), Rational Team Concert (RTC), and Rational Design Manager (RDM).

If you have a question that isn’t answered here, please ask it in the Jazz.net forum. We might add it to our list!

List of questions

The questions are organized by topic area, and listed here so you can more easily locate a specific question.

Enabling configuration management

Definitions and concepts Global configurations Managing streams and baselines Linking artifacts and resolving links Managing and delivering change Reporting on configurations

Qs: Enabling configuration management

Q: What benefits do I get from enabling configuration management for requirements and quality management domains?

A: Configuration management across the lifecycle provides many benefits:
  • Reproduce past results, because you can reliably recreate all artifacts associated with a particular milestone or release.
  • Improve collaboration and reuse, better supporting parallel development as well as product line variants.
  • Insulate and manage change to the current development work using change sets (DNG) or branched streams (RQM)
Increased reuse can lead to reduced costs and faster delivery, while improving change management and reliability can enhance quality.

Q: Where can I learn more about configuration management capabilities?

A: Read the Jazz.net article Welcome to configuration management for an overview of configuration management. You’ll find links to many other resources including educational videos, practice guidance, other articles, and IBM Knowledge Center topics.

Q: What extra CLM applications do I need to install for configuration management? If I don’t install them, does it limit any other capabilities?

A: The following CLM applications are required if you enable configuration management in your applications:
  1. Global Configuration Management (GCM) application
  2. Link Index Provider (LDX) application
  3. Lifecycle Query Index (LQE) application
If you are not using configuration management (other than RTC SCM for source control), you do not need the GCM or LDX applications. Omitting them has no other impact on the CLM applications. You can also optionally use LQE as a data source for reporting against projects that are not enabled for configuration management, in addition to the data warehouse; otherwise, the LQE application is not required.

Ensure that you consider these applications when planning your infrastructure, and allocate adequate resources. For more information on the applications and recommended topologies, see Recommended ALM deployment topologies for 6.x.

Q: How do I enable configuration management in the CLM applications?

A: RDM and RTC are enabled to work with configuration management by default; no additional steps are required. (Note: if you are using RDM v6.0 or v6.0.1, see this tech note.) For DNG and RQM, an administrator must enter an activation key in the application's setting for Local Versioning Component (under Advanced Settings); project administrators can then enable individual projects in the project settings. To request an activation key, contact IBM Support or visit [[https://jazz.net/products/clm/cm/get-keyJazz.net.

Q: Do I have to enable all my projects for configuration management?

A: RDM and RTC project areas are enabled to work with configuration management by default; no additional steps are required. You can enable individual DNG and RQM project areas; you can have both enabled and non-enabled project areas on a single server. However, if you have links between project areas, you must enable all of those projects, or none of them, to ensure that cross-project linking continues to resolve correctly. For example, if you have an RQM project that links to a DNG project, and that DNG project links to another DNG project, you must enable all three of those project areas to ensure that all the cross-project linking works correctly, and also define a global configuration that includes the configurations from all three project areas.

Q: What happens if I enable only one of my linked DNG or RQM projects?

A: If your projects link to each other, enabling only one of them for configuration management severely compromises your ability to continue to link between them. For that reason, you should enable all of your linked project areas, or none of them. Because linking is directional, the specific behavior depends on which project you enable. Read on for more details, but in general:
  • You cannot create any new links between the enabled and non-enabled projects.
  • Existing links might or might not be displayed, and might or might not resolve.
  • If the existing links do resolve, they always go to the artifact in the default stream.

If you enable only the DNG project:

  • Links between DNG and RQM will no longer appear (because back links are removed).
  • Links from RQM will continue to resolve to the artifact in the default stream.
  • You can delete the existing links from RQM (where they appear), but you cannot create any new links between the DNG and RQM project artifacts.

If you enable only the RQM project:

  • Links between DNG and RQM continue to appear in both applications (since RQM “owns” the links).
  • Clicking the link in DNG opens the RQM artifact in the default stream,
  • Clicking the link in RQM gives an error, although preview continues to work.
  • You cannot create any new links between the DNG and RQM project artifacts
  • You can only delete the existing links from the DNG side.
The outcome is similar when multiple DNG projects link to each other.

Q: What if I only want to use configuration management in one CLM application?

A: If your configuration-enabled projects will link to other projects, even to projects in the same CLM application, you still need global configurations to support the cross-project linking. If you only use one application, and you never link across projects, then you do not need to use global configurations or the Global Configuration Management (GCM) application. You still need the Link Index Provider (LDX) application to ensure that directional links within your project resolve correctly. If you plan to use interactive reports, you also need the Lifecycle Query Index (LQE) application for configuration-enabled reporting.

Q: Why do I see a configuration context menu in my non-enabled DNG project?

A: Even if your DNG project is not enabled for configuration management, you can make baselines of the artifacts at important milestones. You can then use the configuration context menu to select a particular baseline or the current artifacts, and determine what set of artifacts you are exploring.

Non-enabled RQM project areas do not show a configuration context menu because they use different mechanisms to manage snapshots.

Back to top

Qs: Definitions and concepts

Q: What is a component?

A: A component is part of your system – a unit of organization for a reusable set of engineering artifacts. The granularity of a component varies between providers, but typically it contains the set of artifacts used in some product, project, or a subdivision of such a set. In DNG and RQM 6.0.3, you can now create multiple components within a single project area; in earlier versions, a component corresponds to an entire project area. In RTC SCM, you can define components to the level of granularity you desire. A global component groups related components across the lifecycle, and optionally other global components, into a hierarchy like a product line.

Q: What is a configuration?

A configuration identifies a subset of the artifacts in a component, and selects one version of each of those identified artifacts. A single component can have multiple configurations. A configuration can be either a stream, where artifacts can be modified, or a baseline, where artifacts are captured at a particular point of time and can't be changed.

Q: What is a local configuration compared to a global configuration?

A: A local configuration is defined in a single application – for example, a stream in RQM. Local configurations can be assembled into a global configuration in the Global Configuration Management (GCM) application. To link artifacts across local configurations, the local configurations must be included in the same global configuration.

Q: What’s the difference between a version and a variant?

A: In our terminology, a variant is a version of an artifact that is identified by a specific set of characteristics that distinguish it from other versions of the same artifact, where each variant can exist at the same time as other variants of the artifact; think about models of a car or phone. There will, of course, often be several time-based versions of a given variant.

Q: What is the “default stream”?

A: For DNG and RQM, the default stream (also called default configuration) is the initial stream created when you first enable your project area for configuration management. If you never created another branch stream, all your work in that project area would be in the default stream. When an incoming link doesn’t specify version information for an artifact, the link resolves to the artifact in the default stream (if it exists). If the artifact isn’t in the default stream, the link fails to resolve.

Q: What is a personal stream and why do I need one?

A: A personal stream is a global configuration owned by and visible to a single user. When a DNG user creates a change set in the context of a global configuration, a personal stream is automatically created and associated with that change set and the original global configuration. The personal stream is effectively a personal override for the global configuration, allowing the changes made in the change set to be seen in the global context – but only by the user making the changes. Other users in the same global configuration context will not see the changes until they are delivered.

Back to top

Qs: Global configurations

Q: When should I work in a local or a global configuration context?

A: If you are working in the context of a single project area in a single CLM application, without any need to link to other project areas or applications, you can work in a local configuration context. If you need to link to artifacts in other project areas, in the same or other CLM applications, you should work in the context of a global configuration to ensure that those links resolve to the correct versions of the artifacts.

Q: Can a global configuration include multiple versions of the same local configuration (for example, two different streams from the same RM project)?

A: Yes, a global configuration can have multiple instances of a local configuration. However, including multiple instances that are different versions of the same configuration introduces “component skew”, which you typically would want to avoid. This is more likely to happen in nested product hierarchies, where the same configuration is used by more than one component in some larger assembly, but at different versions.

For example, the global configuration example below includes two different versions of the RM Stream local configuration:

Global Configuration Prime
   RM Stream 2.0
   QM Prime Stream
   Reusable Component Global Configuration
      RM Stream 1.0
      QM Stream 1.0
The system handles component skew by using the first instance of the local configuration that it encounters in the global configuration hierarchy (working down from the top). In the example above, when you open DNG in the Global Configuration Prime context, the RM Stream 2.0 local configuration will load, since it is higher in the hierarchy. To use a different local configuration, like RM Stream 1.0 in this example, reorder the hierarchy to make that configuration appear first; in the example, you could move Reusable Component Global Configuration above RM Stream 2.0. If changing the hierarchy would impact other users, you could also choose to work in a global configuration stream or baseline of the lower-level component, for example, in the context of Reusable Component Global Configuration, assuming that configuration includes the artifacts you need.

The GCM application provides a utility to identify component skew. For more information on troubleshooting component skew, see the topic “Unexpected local configuration in the Current Configuration menu” in IBM Knowledge Center.

Q: When do I create a new component instead of a new configuration?

A: Create a new component when you are creating a new physical or logical piece of your system: system – a new part, module, or whatever. Create a new configuration to revise or extend an existing part of your system, such as a new version or variant.

For example, say you have an Automated Meter Reader offering for the US market, defined by a global configuration, and you need a similar offering for the UK market; you would create a new global configuration from the US baseline and customize it for the new market. However, if you wanted to add a new braille or audio interface to your Meter Reader, you would likely need to create new components or project areas in each local application (requirements, design, code, tests), with a corresponding global configuration (component) that assembles those new local contributions. You might still use that UK variant of your Automated Meter Reader configuration, and add the new global component to that configuration. You would then add the stream from that global component to the appropriate variant stream of your Automated Meter Reader component.

Q: Can I write business rules for global configurations?

A: Currently, global configurations have only one business rule: a global baseline can only consist of global or tool-specific baselines (that is, global baselines cannot include streams). Other than that, there are no rules for creating global configurations.

The user must have a designated role to create a global configuration. There is a separate permission for creating baselines, since this might be given to a wider group of users involved in building the system. As of CLM 6.0.1, you can define custom attributes, including tags, for global configurations. Using the custom attributes and other configuration data in LQE, you could write reports to validate business logic.

Back to top

Qs: Managing streams and baselines

Q: When do I create a new stream?

A: Your organization should define an overall strategy for when to branch a new stream, as well as when to take baselines, at both the local and global configuration level. Your strategy will depend on your development practices and your goals. For example:
  • To enable parallel development of future items before your current release is complete, you could create a new stream based on the most recent baseline of your current stream. You continue to work on the current stream until that release is complete, and determine which changes to deliver across the current and future streams.
  • Alternatively, to avoid parallel development and merging, you could wait until the current release is complete before creating the new stream for the next release, although that might slow ongoing development.
  • You could even baseline the current stream when the release is complete, and then rename it to continue using it for your new “current” release; in this case, ensure you are very clear on naming conventions and usage so that teams are always clear on which stream to use.

You might also need to consider when to create new branches for maintenance releases, depending on when that work needs to start. If you start before the current release is complete, you will need to deliver changes from the current stream to the maintenance stream. During maintenance, you would need to determine which changes should be delivered back to the new current release. You might have one or multiple maintenance streams, again depending on whether you work on maintenance releases sequentially or in parallel with each other. In general, create a new stream only when necessary and when you are ready to start working in it; minimizing the number of concurrent work streams reduces the complexity of delivering across multiple streams.

Q: Are the artifacts in each stream copies of each other?

A: No, they are either true parallel variants, or different time-based versions, or the same versions reused by reference.

Q: When I go to a historical baseline, do I need to use a previous version of the application to view it?

A: When you upgrade the CLM applications, your baselines are migrated along with your other data, so you can view them in your current product version.

Back to top

Qs: Linking artifacts and resolving links

Q: What does “directional linking” or “no back links” mean?

A: In projects that do not enable configuration management, when you create a link between artifacts, both artifacts store a link property: a link and a back link, if you will, although it is not explicitly stated which is the link and which is the back link. With configuration management and versioned artifacts, maintaining both link and back link becomes extremely challenging, especially across applications.

As a result, the linking model for configuration-management-enabled projects has changed: for each link type, there is a source or “owner” application or artifact, and a “target”. The source artifact stores the link as a property, and its application feeds the link information to the Link Index Provider (LDX). The target artifact does not store or modify any property for the link (no “back link”); its application queries LDX for incoming links for the artifact, and displays them in the UI as if they were properties. This is true for all OSLC link types; for a few link types that are internal to an application, the application may continue to store back links.

For the CLM application user, these changes should be transparent. She can create links to and from artifacts as before, and the links continue to display as before; whether the link information is stored with the artifact or retrieved from the link index provider is not material. What might affect the end user is when a link resolves correctly in one configuration, but not in another because an artifact is missing. That scenario is addressed in the questions below.

Q: What happens when my artifact links to an artifact that is not included in my current global configuration?

A: For the link to exist, it must have been created either before configuration management was enabled in the project, or at a time when both artifacts were included in a global configuration. The scenario could occur for several reasons:
  1. Your global configuration is missing the configuration or component the artifact belongs to.
  2. The missing artifact is included in a different version or variant of the global configuration where the link was created (for example, a previous release), but is not in the current version of the configuration.
  3. The missing artifact is in a project area or application that does not enable configuration management. Linking behavior between enabled and non-enabled containers is described in What happens if I enable only one of my linked DNG or RQM projects?.

You can only observe this scenario from a source artifact (one that “owns” the link in question). If the artifact that is not part of the configuration is the target of the link, it shows no indication that the link exists. The source artifact shows some version of the link text, but you cannot preview or open a linked artifact that is not in the configuration; an error occurs or the link does not resolve correctly. In RTC, if the configuration context is not defined (the attribute mapping or release association is missing), the link resolves to the artifact in the default stream if it exists in that stream; otherwise, it gives an error.

To correct this problem, delete the link if it isn’t needed, or ensure that the artifact is included in the referenced configurations, and the correct set of configurations are included in the global configurations.

Q: What happens when I try to link to an artifact in a component not included in my current global configuration?

A: For DNG, RQM, and RDM, if you are in a configuration-enabled project, you can only create links to artifacts within your current configuration context. If you try to link to an artifact outside your current global configuration, you will get an error.

When you create link from artifacts in those applications to work items in RTC, you can clear the check box that shows only work items within the global configuration context and then link to any work item; however, these links may not resolve correctly in future. When you create a link from RTC, if the global configuration context isn’t specified (the attribute or release mapping is missing), you can link to artifacts outside of the configuration context, but only to artifacts in the default stream.

Q: Can I create a link from a versioned artifact to a non-CLM application?

A: Yes, if the other application provides some level of support for configuration management. The application must register as an OSLC provider or consumer, and set the globalConfigurationAware property in its service provider document; if that property is not set, the CLM applications assume no support for configuration management. If the application has no support for configuration management, you cannot create links from DNG, RQM, or RDM to that application.

However, you can still create links from the non-CLM application to RDM artifacts, but only those in the default stream.

Because RTC work items are not versioned, you can create links between work items and other applications that support OSLC, whether or not they support configurations. To determine whether your non-CLM application supports configuration management, contact the application provider. More information on enabling applications is included in the [[http://open-services.net/specifications/configuration-management/][OASIS OSLC Configuration Management specification] (draft) and the Jazz.net article on Enabling your application to integrate with configuration-management-enabled CLM applications.

Q: What happens to existing links to a non-CLM application that does not support global configurations (e.g. IBM Rational DOORS 9.X)?

A: This situation happens if you enable an existing CLM project area that has links to the non-CLM application. The link to the CLM artifact continues to appear in the non-CLM application; the link resolves to the version of the artifact in the default configuration.

If the CLM artifact “owns” the link, the link also continues to appear in the CLM application. When you follow that link, it continues to resolve as it did before, to the single non-versioned artifact in the non-CLM application.

As mentioned in the previous question, you cannot create new links between versioned artifacts (in DNG or RQM) and artifacts in applications that do not support configurations. You can still create links from an application like DOORS to RDM artifacts in the default configuration, or to non-versioned work items in RTC.

Q: When I create a new local configuration, will the existing links become inconsistent or unresolvable?

A: The new local configuration inherits the set of artifact links from the baseline from which the stream was created; that is, the new stream will use the same set of versions of the artifacts as the baseline, including their existing links.

However, these links will not resolve (and if the artifacts do not “own” the links, the links will not even display) if the new local configuration is not part of a global configuration that includes the artifacts on the other end of the links. To resolve the links, you need to include the new configuration, as well as configurations containing the linked artifacts, in a global configuration, and set your context to that global configuration.

It is the configuration lead’s responsibility to ensure that each global configuration has meaningful contributions from each component, and it is the user’s responsibility to ensure that links are meaningful in that context.

Q: If I delete a link and then link to another artifact, what happens to the history of the link to the previous artifact?

A: Links are part of the versioned state of an artifact, so previous links can be seen in previous versions of the artifact. You can use previous global baselines to navigate through links as they were at the time of that baseline. Individual tools may also offer ways to visualize the history of artifacts and the changes made to them.

Q: I cannot link from a baseline. This seems like a limitation. Is there a way around this?

A: Many kinds of links, such as traceability links, are an important part of the semantic content of an artifact. Baselines are intended to be non-editable, so you aren’t able to change the content of the artifact in the baseline.

However, with directional links, only the source (or “link owning” artifact) stores the link information; the target artifact does not store the link as an attribute, but queries the link index provider on request (see What does “directional linking” or “no back links” mean? for details on directional linking). The defined link directions take into account the likely order of artifact baselines: for example, requirements are typically baselined before test development and execution, so RQM artifacts “own” and store links to DNG artifacts. Thus, you can create a new link from an RQM test artifact in a stream to a DNG artifact in a baseline, without modifying the DNG artifact resource representation. If the RQM artifact is part of a baseline, you could not save the new link property.

Q: If baselines are not editable, why do links and link validity indicators sometimes change in my baseline?

A: See the answer above: Because links are directional, only the source (or “owning”) artifact stores the link information. The target artifact does not change, but uses the link index provider to determine relationships. Link directions take into account the likely order of baselines, so that artifacts that tend to complete later in the lifecycle (like test artifacts) store the links to artifacts that tend to be baselined earlier (like requirements). Thus, you can link from an RQM test artifact to a DNG baselined requirement because the DNG artifact does not store the link relationship and does not change. For more details on directional linking, see What does "directional linking" or "no back links" mean?.

Similarly, link validity is determined by a service. Validity is not stored as a property of the artifact resource; when the application renders the artifact, it queries the link validity service for the appropriate values to display. The baselined artifact does not change.

Q: What attributes are used to determine link validity?

A: For DNG, any change to predefined or custom properties (including the primary artifact content) causes the links to and from that artifact to become suspect. For RQM, a few attributes do not affect link validity (between RQM and DNG artifacts), since they do not inherently change the test artifact content: Priority, Risk, Review State, Weight, Lock, Estimate, Owner, Creator, and test script content. At this time, you cannot select which attributes to use when determining link validity. The validity service currently applies only to link types used between requirements, and between requirements and test artifacts.

Back to top

Qs: Managing and delivering change

Q: When I merge or deliver changes across streams, are the change sets physically copied to the receiving stream?

A: Artifacts are used by reference, not by copy. Delivering change sets (in DNG) or merging changes across streams (in RDM and RQM) does not copy artifacts, but instead updates the target configuration to point to different versions of the affected artifacts.

Q: How can I improve change management of my requirements?

A: DNG offers several capabilities to better manage changes to requirements, including change sets, linking change sets to change requests, and user roles and permissions.

Create change sets (from the configuration context menu or Manage Configurations view) to group or separate sets of related changes for better tracking and easier delivery across streams, and to isolate changes from the main stream until they are ready to deliver. You can mandate that all changes be made inside a change set by setting an option for each stream.

You can also require that users associate change sets with an approved change request before allowing delivery. This option is also set for each stream. If you set this option, if a change set is not linked to a change request, or the change request is not approved, the change set cannot be delivered. The change request can reside in any system (there is no restriction on configuration management support in this isolated case), and the change request system defines the criteria for approval.

Users must have the appropriate permissions to create and deliver change sets – their own, as well as those of other users. You can limit those permissions as needed, for example, restricting the ability to deliver changes to a small group, or only the team lead.

Q: Do I have to create a change set to make a change in DNG?

A: No, not unless your project administrator has set the option to require change sets. If you do not explicitly create a change set from the configuration context menu or Manage Configurations view, each change that you make creates its own implicit change set, which is delivered to the stream immediately when you save. For example, deleting or moving an artifact creates an implicit change set; editing an artifact creates an implicit change set with whatever changes you made in that edit session. The creation and delivery of the implicit change sets is transparent to the user. When you deliver change sets across streams, you can see the implicit change sets and deliver those changes. The drawback is that the list of implicit change sets can be very long, since the changes are very granular, and the names generated by the system are not very descriptive (for example, “Edit artifact 916”).

Q: When should I use explicit change sets in DNG?

A: Use explicit change sets to better track and manage requirements change, as well as to group (or separate) sets of related changes, and especially if you expect to deliver changes across configurations. In most cases, using explicit change sets, with a well-defined naming convention, is a good idea. If you want to enforce explicit change sets, you can set an option for the individual stream that prevents any change outside of a change set.

If you do not explicitly create a change set, each change you make creates its own implicit change set, with a very simple system-generated name, as described in the question above. When you deliver across streams, you then see a long list of change sets and it is difficult to determine which changes you want to deliver.

Creating a change set allows you to group a set of changes together, as well as to keep your changes separate from the main stream until you are ready to share them. In a team environment, several members might have their own change set in order to work in parallel (there are merge capabilities should conflict arise). When you need to deliver across configurations, your naming convention and grouping strategy should make it easier to identify the required change sets.

You might choose NOT to use explicit change sets if you are starting a new project, if changes are minimal and will be discarded or never reused, or if you know ALL changes will be delivered across configurations and you don’t need to track them individually.

Back to top

Qs: Reporting on configurations

Q: How is reporting on configuration-enabled projects different from reporting on non-enabled projects?

A: For interactive reporting on configuration-enabled projects, use the Report Builder in Jazz Reporting Service with the "Lifecycle Query Engine scoped by a Configuration" data source. (In some versions, this data source is called "Lifecycle Query Engine using Configurations".) The LQE data source recognizes versioned data, but the CLM data warehouse does not. With configuration-enabled reporting, reports are run in the context of a configuration, usually a global configuration, which determines which versions of artifacts to include in the report. You can also use the “Lifecycle Query Engine scoped by a Configuration” data source with Rational Engineering Lifecycle Manager (RELM).

For DNG and RQM project areas, enabling configuration management stops all feeds to the CLM data warehouse, and archives the existing project data in the warehouse. Business Intelligence and Reporting Tools (BIRT), Rational Reporting for Development Intelligence, and dashboard reports or widgets that use the data warehouse will not work for enabled DNG or RQM project areas.

Rational Team Concert does populate the data warehouse, but that data does not include configuration-related information. For versioned data, you must replace existing reports with new ones that use the Lifecycle Query Engine data source.

To generate documents, you can continue to access versioned data by reportable REST APIs, using built-in, template-based reporting in the CLM application or by using IBM Rational Publishing Engine. You can add configuration context to existing Rational Publishing Engine templates. The built-in document generation uses the current configuration context. You can also export reports from Report Builder to Rational Publishing Engine. For more information on reporting, see the Jazz.net article on Getting started with reporting by using LQE data sources.

Back to top

Related topics:

External links:

Additional contributors: NickCrossley

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r16 | r7 < r6 < r5 < r4 | More topic actions...
 
This site is powered by the TWiki collaboration platformCopyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.