Install the Synchronizer

The Synchronizer includes two services: the Integration Bridge service (IBS) and the Synchronizer service. The following section describes how to set up these services.

Step 1: Configure ALM Octane to enable the integration

To enable communication between ALM Octane and the Synchronizer services, perform the following steps within your ALM Octane environment. (In a cluster configuration, this must be done separately for each ALM Octane node.)

    Note:
  • If you upgrade ALM Octane the following configuration changes are overwritten. Back up the files described below before upgrading, and restore them after upgrading.

  • This document provides paths for ALM Octane on Linux. If you are using ALM Octane on Windows, the paths are similar but use Windows format. For example, the octane.yml file is located at C:\octane\conf\octane.yml.

  1. Within /opt/octane/webapps, copy the service.locator.properties.example file to service.locator.properties:

    cp service.locator.properties.example service.locator.properties
  2. Within the service.locator.properties file, enter the correct internal URLs of each service. Note that the URLs cannot start or end with spaces.

  3. Open the /opt/octane/wrapper/wrapper.conf file. In the section headed #on-prem configuration, uncomment the following lines (remove the # character from the beginning of each line):

    wrapper.java.additional.38=-Dservice.locator.properties.location=%DEPLOY_BASE_DIR%/webapps/service.locator.properties
    wrapper.java.additional.39=-Denable_services_integration=true

    This enables ALM Octane to communicate with the Synchronizer.

  4. If ALM Octane is configured behind a proxy, the Integration Bridge service and Synchronizer service must be identified as non-proxy hosts. To do this, add the following line at the end of the wrapper.conf file:

    wrapper.java.additional.<next line number>=-Dhttp.nonProxyHosts=<Integration Bridge service host>|<Synchronizer service host>

    For example, if the last line in the wrapper.conf file begins with wrapper.java.additional.62, add the following line: 

    Example: wrapper.java.additional.63=-Dhttp.nonProxyHosts=ibs.service.company.com|sync.service.company.com
  5. Restart the ALM Octane server. In a command line, enter:

    service octane restart

  6. The Synchronizer needs to use an API client ID and secret to communicate with ALM Octane. To generate these, go to /opt/octane/install and run the following:

    ./generateadminapikey.sh <octane-server-url> <site-admin-name> <site-admin-password>

    In an ALM Octane on Windows installation, go to C:\octane\install, and use generateadminapikey.bat.

    Example of output:

    Example: "client_id":"micro-services-key_12qw97wx4wp8phrr4wwqzkore"
    "client_secret":"$00~7_djkRV~?vGF@ExMsFPn"
  7. Save the client ID and secret. When you configure the Synchronizer services as described in the next steps, you will enter the client ID in the serviceApiKey property, and the secret in the serviceApiSecret property.

Step 2: Install and configure the Integration Bridge service

  1. Download and extract the Integration Bridge service installation package from Micro Focus download sites.

    Under /opt/ extract the tar file:

    tar -xzvf <installation file name>

    The file structure should now be /opt/ibs/.

  2. In the /opt/ibs/conf/ibs.yml file, define the following values for the Integration Bridge service parameters.

    Note: Sensitive data, such as the encryption seed (sync|ibs/firstTimeInit/encryptionSeed), are removed from the .yml file.

    Integration Bridge service parameter values

    serviceLocations: Section with URLs of services and ALM Octane
    octane

    Base URL of ALM Octane (or its load balancer for multi-node deployment)

    Example: http://octane.company.com:8080

    opb (Integration Bridge service)

    Base URL of Integration Bridge service (or its load balancer for multi-node deployment)

    Example: http://octane.company.com:8080/opb

    sync

    Base URL of Synchronizer service (or its load balancer for multi-node deployment)

    Example: http://octane.company.com:8080/sync

    firstTimeInit

    Values from this section are deleted after the service is run for the first time.

    encryptionSeed

    Enter the contents of the initstring file on the ALM Octane machine installation:

    <octane-repository>/storage/site/initstring.txt

    Example: more /opt/octane/repo/storage/site/initstring.txt

    general

    Section of service-specific properties

    logFolder

    Folder where Integration Bridge Service logs will be located.

    Example: /opt/ibs/logs

    port

    HTTP port where the Integration Bridge Service listens.

    Example: 8080

    database

    Section of database-related properties

    action

    Enter one of the following:

    • CREATE_NEW for a new installation (first execution of installation script). This creates the site admin schema.

    • FILL_EXISTING for a new installation, where the site admin schema is supplied by the organization's DBA. This populates the empty schema. Note that for MSSQL, a login named hpu must exist and have access to the supplied schemata.

    • AUTO for detecting and performing the needed action automatically.

    • UPGRADE for an existing deployment. This updates the existing schema if needed.

    • CONNECT_TO_EXISTING for an existing deployment. This connects to the existing schema without upgrade.

    type

    The supported database types are:

    • ORACLE

    • MSSQL

    connectionString

    The Java Database Connectivity (JDBC) database connection string required to connect to the database. It includes the following details: database type, database server name, and database server port number.

    Examples:

    jdbc:mercury:sqlserver://dbserver1:1433 

    jdbc:mercury:oracle://db_sever_host:1521;servicename:ORCL

    adminUser

    The name of the database admin user.

    Note: In case of FILL_EXISTING action, enter the saSchemaUser for Oracle, or hpu for MSSQL.

    adminPassword

    The password of the database admin user (DBAdminUser for Oracle, MssqlLoginNameForSetup for MSSQL).

    Note: In case of FILL_EXISTING action, enter the saSchemaPassword for Oracle, or password of the hpu login for MSSQL.

    saSchemaUser

    The name of the site schema that is created by the database admin user during the installation, or supplied by the organization's DBA.

    Example: ibs_sa

    saSchemaPassword

    The plain-text password of the site schema.

    schemaUser

    Used with FILL_EXISTING action. The name of the space schema that should be populated, supplied by the organization's DBA.

    schemaPassword

    Password of a user created by the service for each attached space.

    Note that for MSSQL, schemaPassword must be the same as saSchemaPassword.

    oracle: Section for Oracle DB only

    tableSpace

    The tablespace in the Oracle database where the site schema segment will be created. Case-sensitive.

    Example: USERS

    tempTableSpace

    The temporary tablespace in the Oracle database. Case-sensitive.

    Example: TEMP

    repository: Section of file repository related properties
    rootFolder

    Root folder for file repository. This folder must be located on disk space which is shared among all service nodes.

    Example: /opt/ibs/repo

    integration:

    Section of integration specific properties

    serviceApiKey

    API client ID

    serviceApiSecret

    API client secret

    distributedCache:

    (Optional) Cluster configuration section

    password

    Password of the cache. Must be the same on all of the service's distributed cache nodes.

    clusterNodes

    • This is not needed in single-node deployment. ֲBy default, the cluster is not configured, and the default value is:

      - localhost

    • In multi-node deployment, enter the list of nodes where the Integration Bridge Service's distributed cache is running. For example:

      - "node1"
      - "node2"
      - "10.0.0.23"

      Alternative notations could be in a single line:

      Nodes: ["node1","node2","10.0.0.23"]

    port

    Default cache port

    Example: 5701

    Note that if this is not a valid integer, the validation fails.

    sso:

    Section of SSO-related properties

    initString

    Enter the contents of the authenticationKey file on the machine installation:

    /opt/octane/repo/storage/site/authenticationKey.txt

    redirectToAuthPageUrl

    Authentication provider sign-in page

    In most cases, this is the ALM Octane login URL.

    master:

    SSO provider properties

    domain

    The user-facing domain name. This must be identical for the Integration Bridge service, Synchronizer service, and ALM Octane.

    Example: If the user-facing address is almoctane.mydomain.com, the domain should be written as mydomain.com.

    loginUrl

    Authentication provider sign-in URL

    Example: http://octane.company.com:8080/authentication-point/web-ui-login.jsp

    logoutUrl

    Authentication provider sign-out URL

    Example: http://octane.company.com:8080/authentication/sign_out

  3. In a cluster deployment only: Create a shared disk space which is accessible from all service nodes. For all nodes configure the ibs/repository/rootFolder property value in the .yml configuration file to point to this shared disk space.

  4. Set the environment property JAVA_HOME to where the Java JDK is installed (and not the JRE).

  5. Save a backup copy of the ibs.yml file. When you run install.sh in the next step, sensitive data such as passwords are replaced by encrypted values, and the encryption seed is removed from the .yml file. If the installation fails, you can restore the backup file and troubleshoot any issues.

  6. Within /opt/ibs/install, execute the install.sh script under a desired user. (You may need to set install.sh as executable.)

      Note:
    • Make sure that ALM Octane is running before you execute the install.sh script.

    • If you need to connect to servers over a secure channel, configure trust before executing the install.sh script. For details, see Configure trust.

    If the sudo command is used to run the script as root, make sure the root user has the necessary environment variables set (mainly JAVA_HOME), or use the –E option in the sudo command: sudo -E ./install.sh

    This runs the setup tool which configures the database, and populates configuration files inside the distribution. It also registers the service as an OS service if executed under root.

  7. Start the service:

    <install_dir>/wrapper/HPEOctaneIBS start

    Alternatively, run the following:

    service HPEOctaneIBS start

    To verify success, look at the Sync service logs: /opt/ibs/server/wrapper.log.

    You can also run the following command: tail -f /opt/ibs/server/wrapper.log and wait until you see the message server is ready.

Step 3: Install the Synchronizer service

  1. Download and extract the Synchronizer service installation package from Micro Focus download sites.

    Under /opt/ extract the tar file:

    tar -xzvf <installation file name>

    The file structure should now be /opt/sync/.

  2. In the /opt/sync/conf/sync.yml file, define the following values for the Synchronizer service parameters.

    Note: Sensitive data such as passwords or initString (excluding encryptionSeed) are written in plain text. When the installation script is executed ("service start"), the plain text values are replaced by encrypted values. The encryption seed (sync|ibs/firstTimeInit/encryptionSeed) is removed from the .yml file.

    Synchronizer service parameter values

    serviceLocations: Section with URLs of services and ALM Octane
    octane

    Base URL of ALM Octane (or its load balancer for multi-node deployment)

    Example: http://octane.company.com:8080

    opb (Integration Bridge service)

    Base URL of Integration Bridge service (or its load balancer for multi-node deployment)

    Example: http://octane.company.com:8080/opb

    sync

    Base URL of Synchronizer service (or its load balancer for multi-node deployment)

    Example: http://octane.company.com:8080/sync

    firstTimeInit

    Values from this section are deleted after the service is run for the first time.

    encryptionSeed

    Enter the contents of the initstring file on the ALM Octane machine installation:

    <octane-repository>/storage/site/initstring.txt

    Example: more /opt/octane/repo/storage/site/initstring.txt

    general

    Section of service-specific properties

    logFolder

    Folder where Synchronizer service logs will be located.

    Example: /opt/sync/logs

    port

    HTTP port where the Synchronizer service listens.

    Example: 8080

    synchronization Section related to synchronization of entities.

    publicOctaneUrl

    Public (base) URL of ALM Octane.

    Example: http://octane.company.com:8080

    database

    Section of database-related properties

    action

    Enter one of the following:

    • CREATE_NEW for a new installation (first execution of installation script). This creates the site admin schema.

    • FILL_EXISTING for a new installation, where the site admin schema is supplied by the organization's DBA. This populates the empty schema. Note that for MSSQL, a login named hpu must exist and have access to the supplied schemata.

    • AUTO for detecting and performing the needed action automatically.

    • UPGRADE for an existing deployment. This updates the existing schema if needed.

    • CONNECT_TO_EXISTING for an existing deployment. This connects to the existing schema without upgrade.

    type

    The supported database types are:

    • ORACLE

    • MSSQL

    connectionString

    The Java Database Connectivity (JDBC) database connection string required to connect to the database. It includes the following details: database type, database server name, and database server port number.

    Examples:

    jdbc:mercury:sqlserver://dbserver1:1433 

    jdbc:mercury:oracle://db_sever_host:1521;servicename:ORCL

    adminUser

    The name of the database admin user.

    Note: In case of FILL_EXISTING action, enter the saSchemaUser for Oracle, or hpu for MSSQL.

    adminPassword

    The password of the database admin user (DBAdminUser for Oracle, or MssqlLoginNameForSetup for MSSQL).

    Note: In case of FILL_EXISTING action, enter the saSchemaPassword for Oracle, or password of the hpu login for MSSQL.

    saSchemaUser

    The name of the site schema that is created by the DBAdminUser for Oracle, or MssqlLoginNameForSetup for MSSQL, during the installation, or supplied by the organization's DBA.

    Example: sync_sa

    saSchemaPassword

    The plain-text password of the site schema.

    schemaUser

    Used with FILL_EXISTING action. The name of the space schema that should be populated, supplied by the organization's DBA.

    schemaPassword

    Password of a user created by the service for each attached space.

    Note that for MSSQL, schemaPassword must be the same as saSchemaPassword.

    oracle: Section for Oracle DB only

    tableSpace

    The tablespace in the Oracle database where the site schema segment will be created. Case-sensitive.

    Example: USERS

    tempTableSpace

    The temporary tablespace in the Oracle database. Case-sensitive.

    Example: TEMP

    repository: Section of file repository related properties
    rootFolder

    Root folder for file repository. This folder must be located on disk space which is shared among all service nodes.

    Example: /opt/sync/repo

    integration:

    Section of integration specific properties

    serviceApiKey

    API client ID

    serviceApiSecret

    API client secret

    distributedCache:

    Optional: Cluster configuration section

    password

    Password of the cache. Must be the same on all of the service's distributed cache nodes.

    clusterNodes

    • This is not needed in single-node deployment. ֲBy default, the cluster is not configured, and the default value is:

      - localhost

    • In multi-node deployment, enter the list of nodes where the Synchronizer Service's distributed cache is running. For example:

      - "node1"
      - "node2"
      - "10.0.0.23"

      Alternative notations could be in a single line:

      Nodes: ["node1","node2","10.0.0.23"]

    port

    Default cache port

    Example: 5701

    Note that if this is not a valid integer, the validation fails.

    sso:

    Section of SSO-related properties

    initString

    Enter the contents of the authenticationKey file on the machine installation:

    /opt/octane/repo/storage/site/authenticationKey.txt

    redirectToAuthPageUrl

    Authentication provider sign-in page

    In most cases, this is the ALM Octane login URL.

    master:

    SSO provider properties

    domain

    The user-facing domain name. This must be identical for the Integration Bridge service, Synchronizer service, and ALM Octane.

    Example: If the user-facing address is almoctane.mydomain.com, the domain should be written as mydomain.com.

    loginUrl

    Authentication provider sign-in URL

    Example: http://octane.company.com:8080/authentication-point/web-ui-login.jsp

    logoutUrl

    Authentication provider sign-out URL

    Example: http://octane.company.com:8080/authentication/sign_out

  3. In a cluster deployment only: Create a shared disk space which is accessible from all service nodes. For all nodes configure the sync/repository/rootFolder property value in the .yml configuration file to point to this shared disk space.

  4. Set the environment property JAVA_HOME to where the Java JDK is installed (and not the JRE).

  5. If the Synchronizer and Integration Bridge services are on a different URL than ALM Octane, perform the following:

    1. Within the file /opt/sync/conf/octane.site.params.properties, uncomment the lines for SYNC_BASE_URL and EXTERNAL_HELP_URL.

    2. Set their values as follows:

      SYNC_BASE_URL. The public base URL of the Synchronizer service (for example: http://sync-server.company.net:8080).

      EXTERNAL_HELP_URL. The online help source on the ALM Octane server (for example: http://octaneserver.company.net:8080/Help/WebUI/Online).

      Note: Do not change the other parameters, which are mandatory for synchronization.

    3. Within the file /opt/sync/conf/sync.site.params.properties, uncomment the line for IBS_BASE_URL and set its value as follows:

      IBS_BASE_URL. The public base URL of the Integration Bridge service (for example: http://ibs-server.company.com:8080).

      Note: You can use the other parameters to define Synchronizer email notification settings.

  6. Save a backup copy of the sync.yml file. When you run install.sh in the next step, sensitive data such as passwords are replaced by encrypted values, and the encryption seed is removed from the sync.yml file. If the installation fails, you can restore the backup file and troubleshoot any issues.

  7. Within /opt/sync/install, execute the install.sh script under a desired user. (You may need to set install.sh as executable. )

      Note:
    • Make sure that Octane is running before you execute the install.sh script.

    • If you need to connect to servers over a secure channel, configure trust before executing the install.sh script. For details, see Configure trust.

    If the sudo command is used to run the script as root, make sure the root user has the necessary environment variables set (mainly JAVA_HOME), or use the –E option in the sudo command: sudo -E ./install.sh.

    This runs the setup tool which configures the database, and populates configuration files inside the distribution. It also registers the service as an OS service if executed under root.

  8. Start the service:

    <install_dir>/wrapper/HPEOctaneSync start

    Alternatively, run the following:

    service HPEOctaneSync start

    To verify success, look at the Sync service logs: /opt/sync/server/wrapper.log.

    You can also run the following command: tail -f /opt/sync/server/wrapper.log and wait until you see the message server is ready.

Step 4: Enable the services in ALM Octane

  1. Open ALM Octane as a site admin, and click the settings icon.

  2. Select Site > Spaces.

  3. Select the space for which you want to enable the Integration Bridge service and Synchronizer service.

  4. Click Enable Bridge Service. This will take several seconds to run.

  5. Click Enable Synchronizer Service. This will take several seconds to run.

    After successfully enabling each service you will see the service version in its relevant column.

  6. Select Users, and assign a dedicated user the Synchronizer Admin role.

  7. Log in as a Synchronizer Admin. Click Settings and then Synchronizer to access the Synchronizer UI.

The next step is to download and install the Integration Bridge agent as described in the ALM Octane Help Center. For details, see Set up the Integration Bridge.

After you set up the agent you are ready to perform synchronization.