Content Comparison

elm-sync configuration is done in the Spring Boot application.yml file. The configuration associates one CDCM space with one or more ELM GCM serverservers, and lists the CDCM Configuration Areas in that space that should be synchronized with ELM GCM. Configuration includes the following topics:

...

Syncing configuration areas in other CDCM spaces requires a separate instance of elm-sync.

Configuration includes the following topics:

The elm-sync server configuration
ibm-elm server port and context-path
scheduler for elm-sync
spring application configuration including
- security for oauth2 for CDCM access
The
- SQLite database configuration for
elm-syncThe
- elm-sync
server configuration
cdcm sever host and ibmspace-elm API informationkey
OAuth1.0a configuration for access to ELM GCM
The cdcm Configuration Area to ELM GCM server mappings

Description

Usage

Access to CDCM uses AOuth 2 which is configured for the Spring Boot application

...

elm-sync uses the configuration information in the application.yml file to configure the CDCM and ELM GCM server URLs, access control and API information, and the list of CDCM Configuration Areas to sync. elm-sync then uses the CDCM TRS provider to read the change log to replicate changes in CDCM in the corresponding project areas and resources in ELM GCM. elm-sync does not use the CDCM TRS base to determine what configuration areas to sync. Rather the CDCM Configuration Areas to sync are explicitly defined in the configuration.area.mapping elements.

elm-sync also does not currently use the trs:cutoffEvent, as it is always 0. This effectively means elm-sync assumes the TRS base is empty and all the TRS provider information is in the change log. This will be updated when CDCM implements change log pruning.

Configuration

`application.yml`

The application.yml defines various information elm-sync uses to determine what CDCM configuration areas should be synced to ELM GCM and how to access them through their authenticated APIs. Here’s an example application.yml file.

Code Block

elm-sync:  # configuration for the elm-sync server
  instance:
    name: ELM-SYNC-1
  max-number-of-retries: 100
  retry-backoff: 100
  max-number-of-unique-title-retries: 100

server:
  port: 8080
  servlet:
    context-path: "/sandbox"

scheduler:
  cron: "0 * * * * *" #run the job every minute

logging:
  level:
    root: info
    com:
      mid:
        smartfacts:
          cdcm:
            issuer-urielmsync: https://keycloak.mid.de/realms/Smartfacts-Developmentinfo
spring:
  codec:
    max-in-memory-size: 10MB
  security:
   user-name-attribute: ${USER_NAME_ATTRIBUTE:preferred_username} oauth2:
      client:
        user-info-authentication-method: ${USER_INFO_AUTHENTICATION_METHOD:form} # header, form, queryregistration:
          cdcm-client:
            resourceserver:client-id: cdcm-client-id
            jwt:client-secret: secret
            issuer-uri: https://keycloak.mid.de/realms/Smartfacts-Development

elm-sync uses SQLite for persisting information about the CDCM configuration areas and ELM GCM project areas that are being synchronized. The information includes:

The Configuration Area id
The ELM Server URL and corresponding project area URL
The trs:order number of the last trs:change event processed by elm-sync. Changes after this event will be processed on the next elm-sync scan cycle.

Code Block

  datasource:  # tge /SQLite data source used by elm-sync
    url: jdbc:sqlite:/data/sqlite/elmsync.db
    driver-class-name: org.sqlite.JDBC
    username: sa
    password: sa
  jpa:
    database-platform: org.hibernate.community.dialect.SQLiteDialect
    hibernate:scope: service-user-roles
            authorization-grant-type: client_credentials
        provider:
          cdcm-client:
            issuer-uri: https://keycloak/realms/cdcm
            user-name-attribute: preferred_username
      resourceserver:
        jwt:
       ddl-auto: update   issuer-uri: https://keycloak/realms/cdcm
  datasource:
    show-sql: true

Configuration

elm-sync is configured using the Spring Boot project file application.yml. This file has to be put in the application’s resources folder. Spring Boot profiles can be used for different configurations such as application-local.ymlfor local development, and application-prod.yml for production.

Kubernetes

The application.yml contains security sensitive information such as consumer keys and secrets, and should be placed into a kubernetes secret, and mounted into the CDCM container. The name of this secret is "elm-sync", the value of is the application.yml file.

To integrate the application.yml file into your CDCM deployment, you need to create a secret called “elm-sync” in the namespace of your CDCM deployment.

There are two ways to do this:

Use kubectl

Code Block
kubectl create secret generic elm-sync --from-file=application.yml=./resources/application.yml -n cdcm

If the secret has to be created manually or from a vault, use this template:

Code Block
apiVersion: v1 data: application.yml: <base64 encoded content of the file application.yml> kind: Secret metadata: name: elm-sync namespace: cdcm type: Opaque

Save the file as application.yml and apply it with:

Code Block
kubectl apply -f application.yml -n <namespace>

Example `application.yml`

This examples defines various external servers and their required authentication mechanisms and a Gateway Proxy configuration. Connections to the Gateway Proxy in this example are authenticated using OAuth 2.0.

Code Block

spring:
  security:
    oauth2:
      client:
        registration:
          custom: #'custom' here can be anything
            client-id: ${CLIENT_ID:genoslc-development} #genoslc-development
   url: "jdbc:sqlite:/opt/elmsync/data/elmsync.db"
    driver-class-name: org.sqlite.JDBC
    username: sa
    password: sa
  jpa:
    database-platform: org.hibernate.community.dialect.SQLiteDialect
    hibernate:
      ddl-auto: update
    show-sql: false

cdcm:  # the CDCM server instance and Space to use, one instance per elm-sync server
  api:
    host: https://cdcm.com
    space-key: space_key

ibm-elm:  # the IBM ELM server instance to use, corresponds to a CDCM Space
  api:
    host: https://elm.com
    pa-creation-path: /gc/service/com.ibm.team.process.internal.service.web.IProcessWebUIService/projectArea
    pa-get-path: /gc/service/com.ibm.team.process.internal.service.web.IProcessWebUIService/allProjectAreas
    config-update-path: /gc/gc.webui.updateConfiguration

smartfacts:
  oauth10a:
    active: true
    outbound:
      details:
        client-secret: ${CLIENT_SECRET:z0AMmptqxxuQBBiZc7FMJVAisvGmMadD}
 name: elm.com
           redirect-uri: http://localhost:${server.port}/${server.servlet.context-path}/login/oauth2/code/customprotected-url-roots: https://elm.com:9443/jts/**,https://elm.com:9443/rm/**,https://elm.com:9443/gc/**
          consumer-key: key
  scope: ${CLIENT_SCOPE:openid}
        consumer-secret: secret
           authorization-grant-type: authorization_code
 rootservices: https://elm.com:9443/jts/rootservices

    inbound:
      provider:
          custom: #'custom' here can be anything
            issuer-uri: https://keycloak.mid.de/realms/Smartfacts-Development
            user-name-attribute: ${USER_NAME_ATTRIBUTE:preferred_username}
            user-info-authentication-method: ${USER_INFO_AUTHENTICATION_METHOD:form} # header, form, query
      resourceserver:
        jwt:
          issuer-uri: https://keycloak.mid.de/realms/Smartfacts-Development

  elm-sync:  # configuration for the elm-sync server
  instance:
    name: ELM-SYNC-1
  configuration:
    cdcm-configuration-url: http://localhost:8080/api/v1/objectMappings
    cdcm-url: https://www.example.com/
  max-number-of-retries: 6
  retry-backoff: 2
  max-number-of-unique-title-retries: 50

server:
  port: ${PORT:8080}
  servlet:
    context-path: "/sandbox"

cdcm:  # the CDCM server instance and Space to use, one instance per elm-sync server
  api:
    host: https://cdcm.demo.smartfacts.com
    space-key: CDCM-IPKvRuZYUps1

ibm-elm:  # the IBM ELM server instance to use, corresponds to a CDCM Space
  api:
    host: https://elmdemo.smartfacts.com:9443
    pa-creation-path: /gc/service/com.ibm.team.process.internal.service.web.IProcessWebUIService/projectArea
    pa-get-path: /gc/service/com.ibm.team.process.internal.service.web.IProcessWebUIService/allProjectAreas
    config-update-path: /gc/gc.webui.updateConfiguration

datasource:
    url: jdbc:sqlite:/Users/jamsden/data/sqlite/elmsync.db
    driver-class-name: org.sqlite.JDBC
    username: sa
    password: sa
  jpa:
    database-platform: org.hibernate.community.dialect.SQLiteDialect
    hibernate:
      ddl-auto: update
    show-sql: true

smartfacts:
  oauth10a:
    active: true
    outbound:elm
      details:
        - name: elmdemo.smartfacts.com
          protected-url-roots: https://elmdemo.smartfacts.com:9443/jts/**,https://elmdemo.smartfacts.com:9443/rm/**,https://elmdemo.smartfacts.com:9443/gc/**
          consumer-key: jamsden_auth
          consumer-secret: Chajas3mat#
          rootservices: https://elmdemo.smartfacts.com:9443/jts/rootservices
        - name: ibm-elm-qm
          protected-url-roots: https://elmdemo.smartfacts.com:9443/qm
          consumer-key: consumer-key
          consumer-secret: secret
          rootservices: https://elmdemo.smartfacts.com:9443/qm/rootservices

    inbound:
      realm-name: sandbox-realm
      auto-approve-consumer-keys: true
      auto-approve-tokens: true
      details:
        - name: mid-elm-inbound
          consumer-key: bc2a6767-af53-417a-a97c-c9487804d5df
          consumer-secret: secret

configuration:
  area:
    mapping:
      -
        source: 664f38242aac9257b5b0c79c
        target: https://elmdemo.smartfacts.com:9443
      -
        source: 664f383b2aac9257b5b0c7a0
        target: https://elmdemo.smartfacts.com:9443
      -
        source: 664c7d15f7eb227a1021a7ce
        target: https://elmdemo.smartfacts.com:9443

Reference

The following tables define each of the leave properties in the elm-sync configuration. See the example above for the property paths.

CDCM OAuth 2: spring.security.oauth2

Key	Description
`client-id`	The CDCM server OAuth 2 client id
`client-secret`	The CDCM server OAuth 2 client secret

Persistance: datasource

...

Key

...

Description

...

url

...

URL of the SQLite database. This database will be created if it does not exist.

...

driver-class-name

...

The SQLite driver class name, usually org.sqlite.JDBC.

Possible values are GET, POST, PUT, DELETE, OPTIONS, PATCH and ALL

...

username

...

The SQLite database user name

...

password

...

realm-name: sandbox-realm
      auto-approve-consumer-keys: true
      auto-approve-tokens: true
      details:
        - name: elm-inbound
          consumer-key: key
          consumer-secret: secret

configuration:
  area:
    mapping:
      -
        source: cdcm_area_id
        target: https://elm.com:9443
      -
        source: cdcm_area_id
        target: https://elm.com:9443
      -
        source: cdcm_area_id
        target: https://elm.com:9443

elm-sync server configuration

This section defines the elm-server configuration including the server port and context-path for accessing the elm-sync controllers, and server instance information. Note: the elm-sync controllers are only used for development and unit testing, the only elm-sync REST services intended for customer use are for sync error reporting and recovery as described in Trouble Shooting .

Code Block

elm-sync:  # configuration for the elm-sync server
  instance:
    name: ELM-SYNC-1
  max-number-of-retries: 6
  retry-backoff: 2
  max-number-of-unique-title-retries: 50

server:
  port: 8080
  servlet:
    context-path: "/sandbox"

elm-sync Spring Boot Application Configuration

The elm-sync Spring Boot application configuration specifies information about:

CDCM OAuth2.0 security information needed to access CDCM
An SQLite database for persisting information about the CDCM configuration areas and ELM GCM project areas that are being synchronized.

CDCM Authentication Configuration

Access to CDCM uses AOuth 2 which is configured for the Spring Boot application using the cdcm-client. Your CDCM administrator can provide your client-id and client-secret, and information on the provider.cdcm-client that does the authentication.

Code Block

spring:
  codec:
    max-in-memory-size: 10MB
  security:
    oauth2:
      client:
        registration:
          custom: #'custom' here can be anything
            client-id: cdcm-dev
            client-secret: secret
            redirect-uri: http://localhost:${server.port}/${server.servlet.context-path}/login/oauth2/code/custom
            scope: openid
            authorization-grant-type: authorization_code
          cdcm-client:
            client-id: cdcm-client-id
            client-secret: secret
            scope: service-user-roles
            authorization-grant-type: client_credentials
        provider:
          custom: #'custom' here can be anything
            issuer-uri: https://keycloak/realms/cdcm
            user-name-attribute: preferred_username
            user-info-authentication-method: form # header, form, query
          cdcm-client:
            issuer-uri: https://keycloak/realms/cdcm
            user-name-attribute: preferred_username
      resourceserver:
        jwt:
          issuer-uri: https://keycloak/realms/cdcm

There are two oauth2.client.registration configurations in the application.yml file for accessing CDCM:

cdcm-client: Used for elm-sync to CDCM server-to-server interactions
custom: used to specify the user who will be able to access elm-sync and do mapping repair operations.

For each client.registration, there is a corresponding client.provider that configures the authentication provider and method for that client.registration.

elm-sync Authentication Configuration

elm-sync provides a controller UI for accessing and repairing CDCM configuration area to GCM project area mappings as described in Trouble Shooting. This requires users to authenticate with elm-sync. See https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html for how this is done in a spring boot application. The spring.security.oauth2.resourceserver specifies how elm-sync is authenticated.

Code Block
resourceserver: jwt: issuer-uri: https://keycloak/realms/cdcm

Database Configuration

The database information includes:

The Configuration Area id
The ELM Server URL and corresponding project area URL
The trs:order number of the last trs:change event processed by elm-sync. Changes after this event will be processed on the next elm-sync scan cycle.

Code Block

spring:
  security:
    oauth2:
      client:
        registration:
          cdcm-client:
            client-id: cdcm-client-id
            client-secret: secret
            scope: service-user-roles
            authorization-grant-type: client_credentials
        provider:
          cdcm-client:
            issuer-uri: https://keycloak/realms/cdcm
            user-name-attribute: preferred_username
      resourceserver:
        jwt:
          issuer-uri: https://keycloak/realms/cdcm
  datasource:
    url: "jdbc:sqlite:/opt/elmsync/data/elmsync.db"
    driver-class-name: org.sqlite.JDBC
    username: sa
    password: sa
  jpa:
    database-platform: org.hibernate.community.dialect.SQLiteDialect
    hibernate:
      ddl-auto: update
    show-sql: false

CDCM Server and API

This section defines the CDCM server and space that is the source of configuration areas that will be synced to ELM GCM project areas. elm-sync only support configuration of a single CDCM server and a single CDCM space. Use multiple instances of elm-sync to synchronize other CDCM servers or spaces.

Code Block
cdcm: # the CDCM server instance and Space to use, one instance per elm-sync server api: host: https://cdcm.com space-key: space_key

IBM ELM server and API information

This section specifies the IBM ELM GCM server that will be synchronized with the CDCM space.

Code Block

ibm-elm:  # the IBM ELM server instance to use, corresponds to a CDCM Space
  api:
    host: https://elm.com
    pa-creation-path: /gc/service/com.ibm.team.process.internal.service.web.IProcessWebUIService/projectArea
    pa-get-path: /gc/service/com.ibm.team.process.internal.service.web.IProcessWebUIService/allProjectAreas
    config-update-path: /gc/gc.webui.updateConfiguration

Future considerations:

The pa-creation-path, pa-get-path and config-update-path are specified in ELM GCM private API. These paths are unlikely to change or could possibly be discovered and may not need to be configured manually. See https://jazz.net/gc/doc/scenarios.
The ibm-elm.api.host property limits elm-sync to syncing a single CDCM space to a single ELM GCM server. This will be updated to support multiple ELM GCM servers and this property will be removed, instead getting the value from the configuration.area.mapping.target value.

ELM GCM OAuth1.0a Security Configuration

elm-sync uses OAuth1.0a to access ELM GCM through the REST APIs. This access is done through a functional user whose ID is associated with a consumer key and secret.

Code Block

smartfacts:
  oauth10a:
    active: true
    outbound:
      details:
        - name: elm.com
          protected-url-roots: https://elm.com:9443/jts/**,https://elm.com:9443/rm/**,https://elm.com:9443/gc/**
          consumer-key: key
          consumer-secret: secret
          rootservices: https://elm.com:9443/jts/rootservices

    inbound:
      realm-name: sandbox-realm
      auto-approve-consumer-keys: true
      auto-approve-tokens: true
      details:
        - name: elm-inbound
          consumer-key: key
          consumer-secret: secret

The outbound.details provides the information elm-sync needs to be able to access ELM GCM services using OAuth1.0a for authentication.

name: a name for the outbound.detals for a specific ELM GCM server configuration. There could be many of these, one for each ELM GCM server used in the configuration mapping
protected-url-roots: lists the server URL roots that are protected by this outbound.details entry
consumer-key: the consumer key associated with the functional id
consumer-secret: the consumer secret associated with the consumer-key
rootservices: the URL to the ELM server’s root services document that provides OAuth1.0a authentication details needed to authenticate a connection

The smartfacts.oauth10a.inbound is required, but not currently used. It is included for future use.

Creating the ELM GCM functional id

elm-sync access the ELM GCM REST APIs using OAuth1.0a and a functional id. The is the most reliable way to do server to server communication with ELM servers because they all use OAuth1.0a to configure consumer/friend relationships to allow the ELM servers to talk to each other. OAuth1.0a can be reliably depended on to be supported by ELM servers.

For elm-sync to access ELM GCM, you must register elm-sync with the ELM Jazz Team Server (JTS) as a consumer (inbound) connection, with consumer key and secret. Then you need to associate that consumer with a functional id that has JazzAdmins, JazzUsers and JazzProjectAdmins repository permissions. Here a brief summary of the steps.

Navigate to the Jazz Team Server Administration Home page
Manage or create users and create the functional id with JazzAdmins, JazzUsers and JazzProjectAdmins repository permissions
Image Added
Click Manage Server and then Communication > Consumers (Inbound)
Use the Register Consumer form to create a Trusted Consumer Key with a Consumer Secret. This is the same information that will be used in the smartfacts.oauth10a.outbound.details entry in the application.yml file.
Edit the newly created Authorized Key and set the Functional User ID to the Id you create above:
Image Added

If you create GCM project areas manually, you must add the functional id as an Administrator for the project area, and a member of the project are with the following roles: Administrator, Baseline Maker, Configuration Lead, Contributor, Tag Manager.

When creating the GCM project areas manually, carefully check the following:

For the CDCM configuration.area.mappings specified in the application.yml file, ensure the GCM project areas are created in the target GCM servers with exactly the same name (not ID) as the CDCM configuration area.
Make sure the functional id associated with the smartfacts.oauth10a.outbound.details.consumer-key is an Administrator and member of the GCM project areas with the Administrator, Baseline Maker, Configuration Lead, Contributor, Tag Manager process roles.

CDCM Configuration Area to ELM GCM Server Mappings

This section maps the CDCM configuration area to the ELM GCM server used to create the corresponding project area.

Code Block
configuration: area: mapping: - source: cdcm_area_id target: https://elm.com:9443 - source: cdcm_area_id target: https://elm.com:9443 - source: cdcm_area_id target: https://elm.com:9443

Note: Although a configuration.area.mapping.target specifies the URL of the ELM GCM server, this URL must currently be the same as ibm-elm.api.host. elm-sync is currently configured to sync one CDCM server with one ELM GCM server. A different instance of elm-sync could be used to sync different CDCM and ELM GCM servers.

Future consideration: Support configuration of multiple CDCM and ELM GCM servers in a single elm-sync implementation:

Change configuration.area.mapping.source to a URL link to the CDCM configuration area, instead of just its ID
Derive the ibm-elm.api information for the configuration.area.mapping.target URL

Configuration

elm-sync is configured using the Spring Boot project file application.yml. The location of this files specified in the docker-compose.yaml file. Spring Boot profiles can be used for different configurations such as application-local.ymlfor local development, and application-prod.yml for production.

Kubernetes

The application.yml contains security sensitive information such as consumer keys and secrets, and should be placed into a kubernetes secret, and mounted into the elm-sync container. The name of this secret is "elm-sync", the value of is the application.yml file.

To integrate the application.yml file into your elm-syn deployment, you need to create a secret called “elm-sync” in the namespace of your elm-sync deployment.

There are two ways to do this:

Use kubectl

Code Block
kubectl create secret generic elm-sync --from-file=application.yml=./resources/application.yml -n cdcm

If the secret has to be created manually or from a vault, use this template:

Code Block
apiVersion: v1 data: application.yml: <base64 encoded content of the file application.yml> kind: Secret metadata: name: elm-sync namespace: cdcm type: Opaque

Save the file as application.yml and apply it with:

Code Block
kubectl apply -f application.yml -n <namespace>

Reference

The following tables define each of the properties in the elm-sync configuration that users will need to provide. See the example above for the property paths.

elm-sync Server Configuration: elm-sync, server

Key	Description
`elm-sync.instance.name`	A name for this elm-sync server instance
`elm-sync.max-number-of-retries`	Maximum number of retries for REST calls.
`elm-sync.retry-backoff`	Number of seconds between retries.
`elm-sync.max-numer-of-unique-title-retries`	Maximum number of retries for unique dcterms.title for an ELM GCM resource.
`server.port`	The port for the elm-sync server
`server.servlet.context-path`	/sandbox, the path for the elm-sync controllers e.g., http://localhost:8080/sandbox/api/v1/objectMappings

elm-sync Persistance: datasource

Key	Description
`url`	URL of the SQLite database. This database will be created if it does not exist.
`username`	The SQLite database user name
`password`	The SQLite database password

CDCM Server: cdcm

Specifies the CDCM server and space key to synchronize with ELM GCM:

Key	Description
`cdcm.api.host`	URL of the CDCM server to synchronize
`cdcm.api.space-key`	The key of the Space containing the Configuration Areas to sync to ELM GCM

CDCM Security: spring.security.oauth2

Specifies the CDCM OAuth 2 security information.

Key	Description
`client-id`	The CDCM server OAuth 2 client id
`client-secret`	The CDCM server OAuth 2 client secret

IBM ELM Server: ibm-elm

Specifies the IBM ELM GCM server that will be synchronized with the CDCM Space.

Key	Description
`ibm-elm.api.host`	URL of the ELM GCM server to synchronize with

Future consideration: these API paths are defined by the GCM REST API at https://jazz.net/gc/doc/scenarios and https://jazz.net/jts/doc/scenarios and may not be need to be configured manually.

ELM GCM Security Configuration: smartfacts.oauth10a

Provides the information needed for elm-sync to authenticate with ELM GCM and JTS using OAuth1.0a.

Key	Description
`active`	Whether the connection is active or not
`outbound`
`outbound.details`	A list of outbound connections to servers authenticated with OAuth1.0a
`outbound.details.name`	Path of the ELM GCM service to create a project area.
`protected-url-roots`	A comma separated list of URI patters to resources protected by this connection configuration
`consumer-key`	The consumer key for the consumer connection
`consumer-secret`	The consumer secret for the `consumer-key`

CDCM Configuration Area Mappings: configuration.area.mapping

This is a list of the CDCM configuration area IDs to ELM GCM server URI mappings.

Key	Description
`source`	CDCM Configuration Area ID
`target`	ELM GCM server URI, should be the same as `ibm-elm.api.host`.

Links

...

Version	Old Version 2	New Version 16
Changes made by	Jim Amsden (Unlicensed)	Jim Amsden
Saved on	Jan 31, 2025	May 30, 2025

Content Comparison

Versions Compared

Key

Overview

Overview

Description

Usage

Configuration

application.yml

Configuration

Kubernetes

Example application.yml

Reference

CDCM OAuth 2: spring.security.oauth2

Persistance: datasource

elm-sync server configuration

elm-sync Spring Boot Application Configuration

CDCM Authentication Configuration

elm-sync Authentication Configuration

Database Configuration

CDCM Server and API

IBM ELM server and API information

ELM GCM OAuth1.0a Security Configuration

Creating the ELM GCM functional id

CDCM Configuration Area to ELM GCM Server Mappings

Configuration

Kubernetes

Reference

elm-sync Server Configuration: elm-sync, server

elm-sync Persistance: datasource

CDCM Server: cdcm

CDCM Security: spring.security.oauth2

IBM ELM Server: ibm-elm

ELM GCM Security Configuration: smartfacts.oauth10a

CDCM Configuration Area Mappings: configuration.area.mapping

Links

`application.yml`

Example `application.yml`