Enabling GCM servers to contribute configurations to other GCM servers

When teams with isolated IBM® Engineering Lifecycle Management (ELM) deployments need to collaborate on product assemblies across multiple lines of business, 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

This is 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 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 IBM IoT MessageSight.
  • 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 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.

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.)

    RM instance 1 can therefore 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 couldn't 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.

Image shows a sample topology of 2 GCM instances where one instance contributes configurations to the other.

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. At this time, only IBM IoT MessageSight is supported, which is available only for Linux servers.

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

    IBM IoT MessageSight 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 IBM IoT MessageSight.

  • 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 will contribute to global configurations but are not registered to the home server's Jazz Team Server.

  • 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 Whitelist 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, GCM1 is the home GCM server, and RM1 is an instance of the RM application. As shown in the example with the check mark, RM1 can contribute its local configurations to only one GCM instance, GCM1. Typically, RM1 and GCM1 would be registered to the same Jazz Team Server. RM1 can't contribute its local configurations to both GCM1 and GCM2, as shown in the example with the X.

    Two-part diagram that shows RM providing configurations to global configurations in one GCM instance, which is supported, and also shows the invalid scenario of RM providing contributions to global configurations in different GCM instances.

    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.
    Diagram that shows the Uses - Configurations associations between two GCM project areas on a home server and two RM project areas registered to that home 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.
    Image showing a grouping configuration that contributes to a configuration on the home server, and also two examples that are not valid

    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).
    Image showing that an external configuration to a home server can't be a contribution to any other GCM instance

Procedure

  1. Add friend relationships.
    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.

      Shows a global configuration hierarchy with external contributions and all the required friend relationships

    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 in the wizard, but you must still configure the functional user in the other application, as described in step 1.c.
      • 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, configure the user that each ELM application uses to make requests to other ELM applications. Typically, you specify the functional user.
      • 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. Go to the LDX server that 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. Make sure the list includes these data sources:
      • Data sources that are shown on the Data Sources page of the other LDX servers.
      • Data sources for all the GCM instances and ELM applications that contribute or will contribute to global configurations on the home GCM server.
    3. On the Jazz Team Server Advanced Properties page, set the Link Index Provider URL property to the shared 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. Restart the LDX server.
    5. 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. On the Advanced Properties page of each application that does not specify an LQE instance on its Jazz Team Server, set the Link Index Provider URL property to the shared LQE instance.

      You do not have to add this URL to the same property on the Jazz Team Server Advanced Properties page.

    4. Restart the LQE server.
    5. If you stopped multiple LQE servers in step 5.a, consider removing those servers from the deployment.
  6. 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

Results

Configuration leads can now build configuration hierarchies that include global configurations from associated project areas on other GCM instances. The configurations are filtered, so they'll see configurations only from associated project areas, which can help prevent version skew.

The GCM application also detects component skew in nested configurations from EWM source control management (SCM) and IBM Engineering Systems Design Rhapsody® - Model Manager (RMM). This type of component skew is referred to as deep component skew. For an example of deep component skew, see Checking for multiple different configurations of a component (detecting component skew).


video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki