Install the Synchronizer

The following section describes how to install and configure the Synchronizer for initial use.

Configure ALM Octane to enable the integration

To enable communication between ALM Octane and the Synchronizer, 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 URL of the Synchronizer. 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 Synchronizer must be identified as a non-proxy host. To do this, add the following line at the end of the wrapper.conf file:

    wrapper.java.additional.<next line number>=-Dhttp.nonProxyHosts=<Synchronizer 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=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, you will enter the client ID in the serviceApiKey property, and the secret in the serviceApiSecret property.

Back to top

Download the Synchronizer

After configuring ALM Octane to enable the integration, download and extract the Synchronizer.

  1. Download the Synchronizer installation package from Micro Focus download sites:

    https://www.microfocus.com/en-us/products/application-lifecycle-management-octane-on-prem/download

  2. Under /opt/ extract the tar file:

    tar -xzvf <installation file name>

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

Back to top

Configure Synchronizer parameters in the sync.yml file

Define values for the Synchronizer parameters in the /opt/sync/conf/sync.yml file. You can do this automatically or manually, as follows:

Script-populated values in simple environments

In simple environments (for example to test the Synchronizer), you can run a script on your ALM Octane server to automatically populate the sync.yml file using default ALM Octane configuration values. The script takes values from the ALM Octane installation files and uses them to populate the Synchronizer parameters with default values.

  1. Run the following command on your ALM Octane server:

    /opt/octane/install/enablesync.sh http://<Synchronizer host>:<Synchronizer port>/

  2. The script generates a sync.yml file. Copy this file to /opt/sync/conf/, replacing the existing sync.yml.

  3. If necessary, edit the values in sync.yml to match your environment, as described in Synchronizer parameter reference.

    For example, the script assumes that Synchronizer is installed in /opt/sync/, and uses port 8080. If you use a different port, edit the corresponding value in sync.yml.

Manual value entry in production environments

If you are working in a production environment, you must define the sync.yml parameter values manually. Fill in the parameters as described in Synchronizer parameter reference.

Note that the enablesync.sh script is not appropriate for complicated production environments.

Back to top

Define additional properties

After you configure the sync.yml file, perform the following steps (depending on your environment).

  1. Set the environment property JAVA_HOME to where the Java JDK is installed, and not the JRE.

  2. In a cluster deployment:

    Create a shared disk space which is accessible from all Synchronizer nodes. For all nodes configure the sync/repository/rootFolder property value in the .yml configuration file to point to this shared disk space.

  3. If Synchronizer is on a different URL than ALM Octane:

    In the file /opt/sync/conf/octane.site.params.properties, uncomment the line for SYNC_BASE_URL. Set its value to the public base URL of the Synchronizer (for example: http://sync-server.company.net:8080).

  4. If ALM Octane is in a site that has no internet access:

    In the file /opt/sync/conf/octane.site.params.properties, uncomment the line for EXTERNAL_HELP_URL. Set its value to the online help source on the ALM Octane server (for example: http://octaneserver.company.net:8080/Help/WebUI/Online).

Back to top

Install and start the Synchronizer

You can now install the Synchronizer and start the Synchronizer service.

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

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

  3. Start the Synchronizer service:

    <install_dir>/wrapper/octane-sync start

    Alternatively, run the following:

    service octane-sync start

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

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

Back to top

Enable the Synchronizer service in ALM Octane

Within ALM Octane, you will now enable the Synchronizer service in each relevant space.

  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 Synchronizer service.

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

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

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

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

You are now ready to perform synchronization.

Back to top

Using Synchronizer with SSO

Support for Synchronizer in SSO mode is currently limited to specific use-cases, but it will be expanded in the future.

The following procedure enables you to use Synchronizer with SSO. This requires an API key and secret with Site Admin role, which can only be generated when ALM Octane is in internal (non-SSO) authentication mode. This is relevant in the following scenarios:

  • If you upgrade from an earlier version of ALM Octane, and you previously generated an API key and secret with Site Admin role when ALM Octane was in internal (non-SSO) authentication mode.

  • If you install and configure ALM Octane without SSO, generate an API key and secret with Site Admin role, enable Synchronizer, and then switch ALM Octane and Synchronizer to SSO mode.

To use Synchronizer with SSO:

  1. In your sync.yml file, add a new section after the distributed cache section, with a blank line before and after this new section. Copy the following text and enter the corresponding values:

    sp:
        authenticationType: sso
        ssoSpBaseUrl: <AUTHENTICATION_SERVICE_URL>
        ssoOauthClientId: <THE_CLIENT_ID>
        ssoOauthClientSecret: <THE_CLIENT_SECRET>
    

    Note that the values for ssoSpBaseUrl, ssoOauthClientId, and ssoOauthClientSecret must be the same as in the sp section in your octane.yml file.

  2. In the sync.yml file, the fields Integration > serviceApiKey and Integration > serviceApiSecret must contain an API key and API secret that have the Site Admin role.

  3. The value of sso > initString is still relevant, but you can delete the other values in the sso section (redirectToAuthPageUrl, master, domain, loginUrl, and logoutUrl).

Back to top