Enabling GCM servers to contribute configurations to other GCM servers

Sometimes teams with isolated IBM® Engineering Lifecycle Management (ELM) deployments need to collaborate on product assemblies across multiple lines of business. In such cases, you can configure a Global Configuration Management (GCM) server to accept contributions from different GCM servers. The contribution of a global configuration from one GCM server to a global configuration on a different GCM server is called an external contribution.

Before you begin

It's an advanced feature with several constraints. Before you proceed, read this topic carefully and ensure that you understand the feature, when to use it, its constraints, and the examples.

Also, ensure that you understand the following GCM concepts:

External contribution

The contribution of a global configuration from one GCM server to a global configuration on a different GCM server.

Home GCM server

The home GCM server that domain-specific applications contribute local configurations to.

The following applications can contribute local configurations to global configurations:

• Architecture Management (AM)
• Change and Configuration Management (CCM)
• Design Management (DM)
• Quality Management (QM)
• Requirements Management (RM)

The domain-specific applications can contribute local configurations to only one GCM instance: their home GCM server. Jazz® Team Server indicates the home GCM server in one of these ways:

• Explicitly: By the value set in the Global Configuration Provider URL advanced server property.

  If the contributing applications are registered to a different Jazz Team Server than GCM, you must specify the home GCM server on the Jazz Team Server for those applications.

• Implicitly: By the GCM instance that is registered to that Jazz Team Server.

  If all contributing applications are registered to the same Jazz Team Server as GCM, that GCM instance is automatically the home server, so you don't have to set the Global Configuration Provider URL property. Registering multiple GCM instances to the same Jazz Team Server is not supported.

When to enable GCM servers to contribute configurations to other GCM servers:

If your organization needs to collaborate across lines of business and share global configurations, use this feature only if the following conditions are true:

• You can't get the scalability or performance you need from a single GCM instance, even if that instance runs on more a powerful machine.
• You are prepared to install and maintain Eclipse Amlen.
• You are prepared to configure and maintain several project area associations: one for each current and potential project area that a GCM instance interacts with across all deployments.
• You can configure at least one instance of the Link Index Provider (LDX) to accept feeds from all the ELM applications in a deployment, including the other GCM instances in the other deployments.
• You can set up external contributions that meet the constraints as described in the Constraints section.

If your organization needs more time to meet these conditions, you might consider setting up multiple project areas in a single GCM instance to achieve similar control over contributions between servers. If your organization is ready to enable contributions between GCM servers, ensure that you understand the prerequisites described later in this section.

Important: After you enable external contributions for a GCM server, disabling this feature is not supported.

Example

The following example is typical for teams that work on separate ELM installations, each with its own Jazz Team Server. For simplicity, the following image shows only the RM and GCM applications. Constraints for this feature are highlighted in bold and are discussed in the Constraints section.

• In this example, there are two Jazz Team Server instances: JTS 1 and JTS 2.
• JTS 1 has an RM instance, named RM instance 1, and a GCM instance, named GCM instance 1 (see the dotted lines). By default, these applications are friends because they're on the same Jazz Team Server. You can register only one GCM instance to a Jazz Team Server.

  Because GCM instance 1 and RM instance 1 are registered to the same Jazz Team Server, GCM instance 1 is the home server for RM instance 1. (For this example, assume that no Global configuration provider URL value is specified in the Jazz Team Server Advanced Properties page.)

  Therefore, RM instance 1 can contribute its local configurations to only GCM instance 1, as indicated by the solid green arrows. A domain-specific application can contribute its local configurations to only one GCM instance.

• JTS 2 has a similar setup: an RM instance named RM instance 2, and a GCM instance named GCM instance 2. By default, these applications are friends. GCM instance 2 is the home server of RM instance 2, so RM instance 2 can contribute its local configurations only to GCM instance 2.
• In earlier versions, the GCM instances were unable to contribute configurations to each other. Starting in version 6.0.6, they can if a GCM administrator completes the steps in the Procedure section.
• In a configuration hierarchy in GCM instance 2, global configurations from GCM instance 1 are called external contributions (see the solid red arrow). In a GCM project area, a global configuration hierarchy can have only one external contribution from any other GCM instance. For details and an example, see Constraint 2 later in this topic.

  Although GCM instances can contribute global configurations to each other, choose carefully: A configuration can either be an external contribution, or have an external contribution: it cannot do both.

Consider a scenario where different teams design different parts of a car. Team 1 designs a transmission on JTS 1 and Team 2 designs an engine on JTS 2.

As development progresses, the configuration lead for Team 2 creates a Car global configuration in GCM instance 2. Team 1 now needs to contribute their global configurations to the Car global configuration.

As an administrator, you must configure the ELM installations so that Team 1 can contribute to configurations in project areas in GCM instance 2.

Prerequisites

• Global configuration provider URL: If a Jazz Team Server doesn’t have a GCM application registered to it, and applications registered to that Jazz Team Server want to use global configurations, the applications must define the Global configuration provider URL value on the Jazz Team Server Advanced Properties page.
• Your deployment must include a Message Queuing Telemetry Transport (MQTT) broker. Ensure that the broker is running and available. Now, only Eclipse Amlen is supported, which is available only for Linux servers.

  If you already have Eclipse Amlen installed to support IBM Engineering Workflow Management (EWM) clustering, you can use the same Eclipse Amlen instance, or install another instance on a different host to prevent a single point of failure.

  Eclipse Amlen is not part of the ELM installation. You must obtain and install it separately. For details, see the related link to the interactive installation guide: when you answer the questions in the guide, in the Supporting applications section, select Global Configuration Management , and click Yes for at least one of the questions in that section. In the generated instructions, click the link to the section about installing Eclipse Amlen.

• Friends: Identify which friend connections you must configure on each server.

  Applications that are registered to the same Jazz Team Server as the home GCM server are friends by default. Ask the configuration leads which applications contribute to global configurations but are not registered to the home server's Jazz Team Server.

  Friend relationships are required between the Jazz Team Server and contributing applications as shown by the arrows in the following diagrams:

  
  
• LQE and LDX: Ensure that you have one Lifecycle Query Engine (LQE) instance and one LDX instance.
  • Ensure that each GCM instance is added as a data source in both LQE and LDX.
  • Ensure that LQE and LDX have the same list of data sources.

  All the global and local configurations that can be in one GCM hierarchy, from however many instances of GCM or ELM applications, must be indexed by the same LQE and LDX servers.

  These applications generate indexes for different uses. LQE indexes artifacts so that team members can report on related artifacts in a global configuration that has external contributions. LDX indexes artifacts so that team members can see links between different types of artifacts, such as between test cases and requirements.

  Typically, only one LDX instance is needed across multiple Jazz Team Server instances. All applications (GCM, RM, QM, and so on) that are friends must use the same LDX instance so team members can see incoming links in applications that use a different home GCM server. For example, team members working in a global configuration context can see links to QM test artifacts when they work with RM requirements.

  If your deployment uses multiple LDX servers, consider consolidating them. You might keep the LDX instance on the Jazz Team Server that has the most applications registered. One Jazz Team Server instance will have LDX registered with it, and the others will not. If you choose to maintain more than one LDX instance, you must ensure that they have the same data sources listed so that the indexes are complete for each LDX instance. Later, in step 4, you consolidate LDX servers.

• Project area associations: Identify which project areas provide or will provide configurations (global and local) to global configurations in a project area so you can define project area associations between the project areas.
  • To identify the project areas that currently provide configurations, use the sample SPARQL query provided on the Global Configuration Management - Project Area Associations wiki.
  • To identify project areas that might contribute configurations in the future, ask the configuration leads of each project area.
• SSO: All the applications that contribute local or global configurations should use single sign-on (SSO) authentication. For details, see the related link about single sign-on authentication in ELM.

  If you don’t configure SSO, people might receive multiple log-in prompts and they might have to try tasks again after they are prompted to log in.

  Important: If your deployment uses Lightweight Third-Party Authentication (LTPA) SSO authentication, in which there are friend connections in addition to registered applications, you must add the root URLs (https://hostname:port) to the Jazz Authentication Proxy SSO Allowlist property on the Jazz Team Server Advanced Properties page (https://hostname:portjts/admin). You don't need to add the URLs to the same property in the GCM application.

Constraints

Ensure that you understand these constraints for enabling contributions between GCM servers.

1. Domain-specific applications (AM, CCM, DM, QM, and RM) can contribute local configurations to only one GCM instance. To enforce this constraint, you must add the required project area associations.

   By default, this instance is the one registered to the same Jazz Team Server as the domain-specific application.

   Example

   In this high-level example, GCM 1 is the home GCM server, and RM 1 is an instance of the RM application. As shown in the example with the check mark, RM 1 can contribute its local configurations to only one GCM instance, GCM 1. Typically, RM 1 and GCM 1 would be registered to the same Jazz Team Server. RM 1 can't contribute its local configurations to both GCM 1 and GCM 2, as shown in the example with the X.

   
   Important: If you don’t enforce this constraint, unexpected results can occur. To enforce this constraint, you must set up project area associations so that configurations from any of the project areas in one application are provided only to the projects areas of one GCM instance, typically the home GCM server. For details, see step 2.

   You can create the associations on either the GCM project area administration page or the other application's project area administration page, but ensure that you understand the difference between the Uses - Configurations and Provides - Configurations associations so that you choose the correct one. The GCM project area uses configurations that other applications provide.

   Example

   Continuing with the preceding example, the RM instance RM1 has two project areas:

   • RMA, which contains a local configuration named RM_A
   • RMB, which contains a local configuration named RM_B.

   The home GCM server has two project areas, named GCA and GCB. For each GCM project area on the GCM home server, you must add a Uses - Configurations association (represented by the arrow between servers) for each project area that has configurations that this GCM project area uses. Conversely, you could go to the RM1 server (and all the other applications) and, for each project area, and add a Provides - Configurations association to the project areas on the home GCM server.

   
2. A global configuration hierarchy can have only one external contribution from each of any number of other GCM instances. The GCM application enforces this constraint.

   To add more than one external contribution from a GCM instance, configuration leads can group configurations in that instance, and then add the group configuration to the hierarchy on the home server.

   Conventions in the following image:

   • Green boxes represent global configurations on the home GCM server.
   • Yellow boxes represent external contributions from another GCM instance.

   

   On the home GCM server, you can add only one global contribution from any GCM instance. Suppose a configuration lead needs to add GC B1 and GC B2 to the GC A1 configuration. Because you can add only one contribution from another GCM instance, the configuration lead must create a group configuration (GC B3) that contains the GC B1 and GC B2 configurations, and then add GC B3 to GC A1 on the home server.

   You can't add multiple contributions from the same instance to a configuration on the home server, as shown in the second and third examples.

3. A configuration can either be an external contribution or have an external contribution: it cannot do both. The GCM application enforces this constraint, which prevents circular contributions and helps mitigate performance issues caused by having too many levels in a GCM topology.
   Conventions in the following image:

   • Green boxes represent a global configuration on the home GCM server.
   • Yellow boxes represent external contributions from a second GCM instance.
   • Blue boxes represent external contributions from a third GCM instance.

   In the first example, the GC B1 and GC C1 global configurations do not have external contributions. They are contributions to GC A1.

   The GCM application prevents you from creating the second and third examples in the following image:

   • In the second example, GC B1 can't be a direct contribution to GC A1 and have a direct external contribution (GC C1).
   • In the third example:
     • GC B1 can't contribute to GC A1 and have an external contribution (GC B2)
     • GC B2 can't contribute to GC B1 directly, GC A1 indirectly, and have an external contribution (GC C1).

   

1. Add friend relationships. For more information, see the prerequisites.
   1. On each Jazz Team Server, go to the administration page (https://hostname:port/jts/admin), and create outbound friend relationships to the following applications. Do this even if there are no direct links between artifacts in those applications.
      • Applications that will use or contribute to global configurations and that are on servers that aren't registered to the Jazz Team Server of the home GCM server.
      • Applications whose artifacts you want to link. For example, if you want to create links between RM and QM artifacts but these applications are on different servers, you must configure a friend relationship between them.

      For details, see Establishing friend relationships.

      Example

      The configuration tree in the following image contains configurations from two ELM instances. Each application in the ELM 1 instance (the top highlighted section of the hierarchy) is friends with each application in the ELM 2 instances (the bottom highlighted section of the hierarchy), and vice versa. These friend relationships must be configured even if applications don't directly interact with each other.

      
   2. For each friend relationship that you add, approve the friend relationship in one of these ways.
      • In the wizard when you create the friend relationship: You can approve the provisional key, and configure the functional user for each friend relationship in the same wizard.
      • On the Jazz Team Server (GCM and RM only): On the Server Administration page, click Consumers (Inbound), and open the OAuth Consumers page. In the Provisional Keys section, change Pending to Approved.
      • In the friend application (applications other than GCM and RM): On the Application Administration page, click Consumers (Inbound), and open the OAuth Consumers page. In the Provisional Keys section, change Pending to Approved.
   3. For each friend relationship, if you didn't configure the functional user before, you can specify it using the following method:
      • RM and GCM applications: Go to https://hostname:port/jts/admin.
      • Other ELM applications: Go to the Application Administration page.

      Then, click Consumers (Inbound) and, in the Authorized Keys section, set the functional user for each authorized friend (one for each ELM application).

      The functional user does not require any privileges and can be any user on the other Jazz Team Server. For convenience, you can use the predefined functional user for that application. For details, see System users.

      For details about configuring consumers and functional users, see Configuring OAuth consumers.

   4. Confirm that there are no other items to approve on this page.
2. Create project area associations.
   Note: Complete this step before you set the Project area associations are required for contributions property to true (step 3.c). Otherwise, team members won’t find the configurations they need in the configuration picker and on the configuration context menu.

   See the Project area associations section for details about the SPARQL query on the wiki that can help you complete this step.

   On each home GCM server, for each GCM project area, add associations to all project areas that provide configurations.

   1. On the banner, click Administration > Manage This Project Area.
   2. On the Overview page, scroll to the Associations section.
   3. Click Add, select the application, and select Uses – Configurations; then, select a project area, and click OK.

      Repeat this step until you've added all the project areas that contribute or will contribute configurations to global configurations in this project area.

   4. Click Save near the upper right of the page. Repeat these steps for the other project areas in this GCM instance.
   5. After you add the associations for the current project area, repeat steps 2.a to 2.d for the other GCM project areas in this GCM instance.
   6. After you add associations for all the project areas in this GCM instance, repeat these steps for the rest of the GCM instances.
3. On each home GCM server, set the following properties on the Advanced Properties page at https://server_name:port/gc/admin:
   1. MQTT broker URI: Example: tcp://broker_server_name:1883

      The broker URI should use a fully qualified domain name (FQDN) so that it resolves to the same MQTT broker across all the participating servers.

      Port 1883 is typically the default port for the MQTT protocol.

   2. Use MQTT for contribution cache: Set this option to true.
   3. Project area associations are required for contributions: Set this option to true.
   4. Allow external contributions of global configurations: Set this option to true.
   5. Click Save.
   6. Restart the GCM instances.
   7. Restart the other applications.
4. Consolidate the LDX servers.
   1. Choose one of the LDX servers as the common LDX server that all the applications will use: https://server_name:port/ldx.
   2. Add data sources.
      • Click Manage data sources > Add Data Source and follow the steps in the wizard.
        • The applications that are already registered to the same Jazz Team Server as LDX will appear in the data source list.
        • You can also add applications from other Jazz Team Server instances using the Root Services URL option as described in Adding data sources to Lifecycle Query Engine by using root services documents.

          For information on how to create consumer keys that are required to authenticate users for adding data sources, see Configuring OAuth consumers.

      • Make sure the list includes these data sources:
        • Data sources that are shown on the Data Sources pages across the LDX servers before consolidation.
        • Data sources for all the GCM instances and ELM applications that contribute or will contribute to global configurations.
   3. In the Advanced Properties page on each Jazz Team Server (except the Jazz Team Server where the common LDX server is registered), set the Link Index Provider URL property to the common LDX instance.

      You do not have to add this URL to the same property on the Advanced Properties page of the applications. The applications use the value you added for the Jazz Team Server.

   4. Optional: Remove LDX servers you no longer need.
      You can remove them in one of the following ways:

      • Ignore them and leave them running.
      • Stop the application in the web container or script.
      • Unregister and uninstall the server.
5. Ensure that all applications (GCM, RM, QM, and so on) use the same LQE server.
   1. If your deployment uses multiple LQE servers, stop all of them except one. For example, you might not stop the LQE server on the home GCM server that has the most applications registered.
   2. In the LQE application, add data sources for all the GCM instances and ELM applications that contribute or will contribute to global configurations on the home GCM server. See the related topic about managing LQE data sources.
   3. If you stopped multiple LQE servers in step 5.a, consider removing those servers from the deployment.
6. In the Report Builder application you want to use across all the multiple GCM and related app instances, ensure that it is connected to the same LQE server that you chose to keep in step 5.
7. Stop and then restart all the GCM servers and other applications in this order:
   1. First, restart each home GCM server.
   2. Restart the ELM applications on each home GCM server.
   3. Restart any other applications on external servers that are affected by the changes that you made in steps 1 and 2.
   Note: If you install other applications that contribute to global configurations and any of the following GCM properties are not set to their default value, you must restart those new applications after you register them:

   • MQTT broker URI
   • Allow external contributions of global configurations
   • Project area associations are required for contributions
   • Use MQTT for contribution cache