Enabling GCM servers to contribute configurations to other GCM servers
When the 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.
- 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:
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:
- Architecture Management (AM)
- Change and Configuration Management (CCM)
- Design Management (DM)
- Quality Management (QM)
- Requirements Management (RM)
- 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
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
- 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.
- 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
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.
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.
- 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
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 (
jts/admin). You don't need to add the URLs to the same property in the GCM application.
- 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
By default, this instance is the one registered to the same Jazz Team Server as the domain-specific application.
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.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.
ExampleContinuing 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.
- A global configuration hierarchy can have only one external
contribution from each of any number of other GCM instances. The GCM application enforces this
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.
- 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.
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).
Add friend relationships.
On each Jazz
Team Server, go to the
(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.
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.
For each friend relationship that you add, approve the friend relationship in one of these
- 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.
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 ELM application).and, in the Authorized Keys section, set the functional user for each authorized friend (one for each
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.
- Confirm that there are no other items to approve on this page.
- 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.
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.
- On the banner, click .
- On the Overview page, scroll to the Associations section.
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.
- Click Save near the upper right of the page. Repeat these steps for the other project areas in this GCM instance.
- 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.
- After you add associations for all the project areas in this GCM instance, repeat these steps for the rest of the GCM instances.
On each home GCM server, set the following properties on the Advanced
Properties page at
MQTT broker URI: Example:
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.
- Use MQTT for contribution cache: Set this option to true.
- Project area associations are required for contributions: Set this option to true.
- Allow external contributions of global configurations: Set this option to true.
- Click Save.
- Restart the GCM instances.
- Restart the other applications.
- MQTT broker URI: Example: tcp://broker_server_name:1883
Consolidate the LDX servers.
- Choose one of the LDX servers as the common LDX server that all the applications will use: https://server_name:port/ldx.
Add data sources.
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.
In the Advanced Properties page on each Jazz
Team Server (except the
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.
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.
Ensure that all applications (GCM, RM, QM, and so on) use the same LQE
- 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.
- 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.
- If you stopped multiple LQE servers in step 5.a, consider removing those servers from the deployment.
- 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.
Stop and then restart all the GCM servers and other applications in this order:
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:
- First, restart each home GCM server.
- Restart the ELM applications on each home GCM server.
- Restart any other applications on external servers that are affected by the changes that you made in steps 1 and 2.
- MQTT broker URI
- Allow external contributions of global configurations
- Project area associations are required for contributions
- Use MQTT for contribution cache
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).
What to do next
You can query for global configurations having external or local contributions to monitor the reuse of components. For more information, see Find global configurations having external or local contributions.