Upgrade

This section describes how to upgrade an existing installation of an on-premises ALM Octane server on Windows.

Before you upgrade

  1. Verify that your server machine, and if relevant, all cluster nodes, meet all prerequisites.

    For details, see Prerequisites.

    Note: If the following are both true, add the CREATE SEQUENCE privilege to the site and shared space schemas: 

    • You are upgrading from an ALM Octane version earlier than 12.55.3. 

    • You are upgrading an installation without a DB admin, for example, your original ALM Octane was installed using the FILL_EXISTING site action.

  2. Create backups of:

    • Existing ALM Octane repository files, including setup.xml and octane.yml

    • Your database

    • Elasticsearch

    • If you are using ALM Octane Synchronizer, back up : 

      • C:\octane\wrapper\wrapper.conf

      • Service.locator.properties.example (C:\octane\webapps)

  3. Take note of any special aspects of your configuration, such as: 

    Special configuration Recommendation
    Did you install ALM Octane to a location other than C:\octane? Refer to the location you used while upgrading.
    Did you modifiy the C:\opt\octane\webapps\root\WEB-INF\classes\hpssoconfig.xml file to control session timeouts? 

    If you modified the this file to control session timeouts, your updates will be overwritten by the upgrade.

    After upgrading, control session timeouts by setting the MINUTES_UNTIL_GLOBAL_SESSION_TIMEOUT and MINUTES_UNTIL_IDLE_SESSION_TIMEOUT configuration parameters instead. For details, see Configuration parameters in the ALM Octane Help Center.

    Do you want to switch from native user management to LDAP user management with this upgrade? 

    If you are upgrading from an ALM Octane version using native user management, and want to start using LDAP user management with this new ALM Octane version:

    1. Realize that once you configure for LDAP user management, you cannot return back to native, internal user management.

    2. When configuring initial settings in the setup.xml file, set the DefaultSpaceMode to isolated. For details, see DefaultSpaceMode.

    3. Upgrade ALM Octane without configuring for LDAP. This means, when modifying the octane.yml file, do not enter any values in the LDAP Settings section.

    4. After the upgrade is complete, configure for LDAP.

    5. Deactivate any native, internal users after LDAP configuration. These users can no longer log into ALM Octane (except for the adminDN user).
    Did your organization's DBA made changes to database schemas, such as the addition of tables or columns?

    Define an exception file. The exception file instructs ALM Octane to ignore manual changes to the database schemas during installation. For details, see Using exception files for manual database changes.

  4. Stop the ALM Octane service on the server, and if relevant, all cluster nodes.

Back to top

Deploy

Download and deploy the new version of ALM Octane using:

setup.exe

For details, see Deploy ALM Octane.

Back to top

Configure initial settings

Here we describe how to modify settings in the setup.xml file.

  1. Manually add newly-introduced settings to setup.xml

    With each version of ALM Octane, settings are added to support new features. To upgrade to the new version, add the newly-introduced settings as listed in the table below to the setup.xml file.

    Give these new settings values.

    Here is a list of introduced settings for setup.xml by version:

    Version New Setting Example
    Introduced in 12.55.4, but mandatory as of 12.55.17

    DefaultSpaceMode

    <entry key="DefaultSpaceMode">shared</entry>

    12.60.4 A new section, oracle_database, was added. It contains the new useDefaultSort setting. See Oracle settings below.
    1. If not already open, open C:\octane\conf\setup.xml using an editor.

    2. Add any missing settings using this format:

      <entry key="<setting>"><setting value></entry>

      Do not modify any text in the <entry> and </entry> tags themselves. Only modify text between these tags.

    3. Save the file.

For a full list of settings for the current ALM Octane installation and their syntax, see Configure initial site settings .

Back to top

Configure other settings

Here we describe how to modify settings in the octane.yml file.

  1. Learn the format for yml files

    <setting><setting value>

    Caution: Correct indentation and formatting is essential when editing yml files to avoid unpredictable results during installation.

    There are resources available online that describe the exact rules and conventions for formatting yml files. We strongly recommend that you familiarize yourself with these rules before editing octane.yml.

    Here are some important rules when editing settings in octane.yml:

    • Put a single space after the colon between the parameter name and the value.

    • Do not add bullets or any other extra formatting.

    • Do not add extra spaces.

    • Use double quotes to enclose any values that include special characters, especially the #.

      A # that is not enclosed in quotes marks the beginning of a comment. Any text after it, until the end of the line, is ignored. The octane.yml file is then interpreted incorrectly during installation and causes errors.

    If these conventions are not followed, ALM Octane initialization or upgrade can fail.

    For an example, see the sample octaneExample.yml file.

  2. Determine settings to add to, and remove from, octane.yml

    With each version of ALM Octane, settings are added to support new features. To upgrade to the new version, add the newly-introduced settings as listed in the table below to the octane.yml file.

    Version Added / Removed Example
    12.55.17 In the License settings section, added the trialEdition setting. See licenses below.
  3. Modify settings

    1. Edit the C:\octane\conf\octane.yml file using an editor.

    2. Locate the right section for each setting you need to add.

    3. Add any missing settings as listed above using this format:

      <setting><setting value>

      General server settings

      cluster

      Cluster configuration: Enter a comma-separated list of node host names or IPs in the cluster.

      Example: 10.0.0.24,10.0.0.99,10.0.0.23

      This is a mandatory setting.

      By default, the cluster is not configured, and the default value is blank. This indicates a standalone ALM Octane server.

      heapSize

      Before starting the ALM Octane server the first time, change the heap memory values on all active cluster nodes.

      For example, you may need to increase the heap size if there is an increase in the number of active workspaces in ALM Octane, or an increase in the number of concurrent user sessions.

      heapSize should be set to half of available server memory on a dedicated server, regardless of load.

      Heap size should not exceed 31 GB.

      Values should be specified in MB (for example, 4096 for 4 GB).

      Default: 4096

      server

      The value of a Jetty port for HTTP, or a Jetty secure port for HTTPS.

      After you install ALM Octane, you may need to change the ALM Octane server port number.

      Because the installation uses a non-root user, common ports (below 1024) cannot be used with ALM Octane.

      By default, the installation uses port 8080 for HTTP or port 8443 for HTTPS (SSL).

      httpPort: 8080
      httpsPort: 8443  

      Leaving any of these ports empty disables the access using the specified http schema server.

      It is possible that the default application server port is used by another application that is running on the same machine. In this case, you can either locate the application that is using the port and stop it, or you can change the ALM Octane server port.

      proxy

      If ALM Octane is behind a firewall, and needs to access an outside server, you may need to configure ALM Octane to use a proxy server.

      An example of accessing an external server is when using a Trigger webhook rule.

      host: <proxy_host>

      port: <proxy_port>

      user: <user>

      password: <password>

      authenticationType

      Whether the ALM Octane installation should use native user management or LDAP authentication for user management.

      Values are: 

      ldap. Use LDAP authentication.

      internal, or any value other than ldap. Use internal, native ALM Octane user management.

      LDAP settings

      Make sure your LDAP system has the corresponding attributes for each mandatory LDAP setting.

      connectionTimeout

      Connection timeout in seconds. Optional.

      Default: 30 seconds

      adminDn

      The user that will log on to ALM Octane after initially setting up LDAP authentication. Its purpose is to make sure that one workable user exists to start configuring LDAP user authentication.

      When the ALM Octane server starts, it checks octane.yml, verifies that this user exists, and validates this user against the LDAP data. If this attribute is not defined correctly,the server will not start. Correct the user details and restart the server.

      This user can be same user as the user entered in the setup.xml file, or a different user. After entering the value for this user, and then restarting the ALM Octane server, the admin user entered in the setup.xml file is overwritten.

      Note: If the adminDn is changed and the server is restarted, both the original adminDn and the new adminDn exist as site admins. Modifying the adminDn does not remove the original one.

      LDAP server settings

      Make sure your LDAP system has the corresponding attributes for each mandatory LDAP setting.

      Enter the following settings for each LDAP server separately.

      Each LDAP server is defined by a group of settings. The settings for each LDAP server start with a hyphen (-) followed by the host setting.

      Caution: Back up all passwords set below because they are encrypted after the ALM Octane server is initialized.

      servers Header row to delineate that the information below is for each LDAP server. Do not enter a value.
      host

      The LDAP server host name or IP address. Mandatory.

      Prefix each host item with a - sign: - host. This instructs ALM Octane where each host begins, especially if there are multiple LDAP servers.

      port LDAP server connection port. Mandatory.
      isSsl

      Whether the LDAP server uses SSL.  Mandatory.

      Enter Y or N.

      If Y, establish trust to the certificate authority that issued the LDAP server certificate. For details, see Configure trust on the ALM Octane server.

      description

      Description of the LDAP server. Optional.

      baseDirectories

      Root of the LDAP path to use to search for users when including new LDAP users in ALM Octane spaces. This can be a list of common names and domain components (cns and dns), a list of organizational units (ou), and so on.

      Optional. Default: Blank.

      If specified,

      Make sure to put a space after hyphen ( - ) before specifying the filter.

      Example:

      baseDirectories:
         - ou=Groups,o=organization.com
         - dc=maxcrc,dc=com
      baseFilters

      Filters to use to refine the search for users when including new LDAP users in ALM Octane spaces. This is generally a list of LDAP objectClasses.

      Optional. Default:  (objectClass=*)

      Make sure to put a space after hyphen ( - ) before specifying the filter.

      Example

      baseFilters:
         - (objectClass=*)
         - (&(objectClass=user)(objectCategory=person))
      authentication:

      Header row to delineate that the information below is for authentication. Do not enter a value.

      method

      The LDAP authentication method supported by the LDAP server. Authentication method used by the LDAP server. The following methods are supported: 

      • anonymous. In this case, skip the next two parameters, user and password.

      • simple, user, and password are mandatory.

      user

      Only required if you set the authentication parameter to simple.

      User name for accessing the LDAP server. This user must have at least read permissions for the LDAP server.

      password

      Only required if you set the authentication parameter to simple.

      Password for accessing the LDAP server.

      This password will be encrypted.

      LDAP server mapping settings

      Make sure your LDAP system has the corresponding attributes for each mandatory LDAP setting.

      Enter the following mapping settings for each LDAP server separately.

      Values used in the mapping section are case-sensitive.

      ALM Octane attribute in octane.yml Sample LDAP attribute that can be used Values and descriptions
      mapping

      Header row to delineate that the information below is for mapping of LDAP attributes. Do not enter a value.

      dn

      distinguishedName

      (for Active Directory)

      The LDAP distinguished name attribute. Unique. Mandatory.

      This attribute is typically in a format that contains the common name and organization details, such as:

      cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain>

      The dn is a unique string that typically contains other LDAP attributes, such as cn, ou, and dc.

      Example

      1. If in LDAP, the entryDN attribute value is: cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain>

      2. In the octane.yml, the dn value would be mapped to: entryDN

      3. When exporting users from LDAP, the dn string representation of each LDAP user  would be the common name, followed by the organizational unit, followed by a part of the domain, such as: cn=Joe_Smith@nga,ou=my_org,dc=com

      entryDN

      (for other LDAP systems)

       

      uid

      objectGUID

      (for Active Directory)

      The LDAP attribute that should be used as the immutable, globally-unique identifier. Mandatory.

      In this documentation, we also refer to this as the UUID (universally unique ID).

      To work with ALM Octane with Active Directory, we use objectGUID.

      This is an attribute by which ALM Octane identifies each user internally for synchronization between ALM Octane and LDAP, including when importing users into ALM Octane.

      entryUUID

      (for other LDAP systems)

      The LDAP attribute that should be used as the immutable, globally-unique identifier. Mandatory.

      In this documentation, we also refer to this as the UUID (universally unique ID).

      To work with ALM Octane, we generally use entryUUID for OpenLDAP. However, depending on your LDAP, this attribute might be different, such as GUID or orclguid.

      This is an attribute by which ALM Octane identifies each user internally for synchronization between ALM Octane and LDAP, including when importing users into ALM Octane.

      You can configure other values, such as GUID or orclguid, or any other unique value.
      firstName givenName LDAP attribute for first name, such as givenName. Mandatory.
      lastName sn LDAP attribute for last name, such as sn. Mandatory.
      fullName cn LDAP attribute for full name, such as cn. Optional.
      logonName mail

      This is the unique identifier between all ALM Octane users, and this attribute is used to log onto ALM Octane.

      In some cases, ALM Octane may use this attribute to identify each user internally for synchronization between ALM Octane and LDAP, including when importing users into ALM Octane.

      mail is usually unique for each user, so mail is an appropriate LDAP attribute to use to map to logonName. Mandatory.

    4. You can change the logonName attribute mapping at any time, but make sure the logonName is unique across all ALM Octane users.

    5. email mail

      The LDAP attribute for email address, such as mail. Mandatory.

      phone1 telephoneNumber The LDAP attribute for the primary phone number, such as telephoneNumber. Optional.

      License settings

      trialEdition

      Enter team or enterprise, depending on your trial edition. For details, see the information about ALM Octane editions in the ALM Octane User Guide.

      Note: This setting is used the first time the ALM Octane server starts, and cannot be changed retroactively.

      mode
      • If you are using a standalone ALM Octane license, enter standalone. You can then skip the remaining fields in the License section. Default.

      • If you are allocating licenses from ALM to ALM Octane, enter almSharing. You then need to fill in the following fields as described below.

      The following fields are mandatory for almSharing mode:
      url

      Enter the full path that you use to access ALM. Typically, this includes the suffix qcbin.

      almIntegrationUser

      Enter the user name for accessing ALM. This user was defined in ALM for integration purposes.

      almIntegrationPassword

      Enter the password for the almIntegrationUser.

      This password is automatically encrypted after you restart the ALM Octane server.

      Oracle settings

      Section Setting Description and usage
      oracle_database: useDefaultSort

      For Oracle databases: Defines whether the standard Oracle binary sort (NLS_SORT="BINARY_CI") should be overridden for non-Latin language support.

      Valid values: yes, no, or blank

      Default: blank (yes) 

      Usage

      oracle_database:
        useDefaultSort: no
    6. Save the file.

Back to top

Upgrade

  1. On the server machine, select Start > ALM Octane > Initialize ALM Octane Server.

    Alternatively, run initserver.bat:

    C:\octane\install\initserver.bat
  2. Check the C:\octane\log\wrapper.log file. If you do not see the "Server is ready!" message, correct the errors shown in the log.

Caution: Do not use ALM Octane until you have completed Upgrade spaces in ALM Octane.

Back to top

Configure and upgrade cluster nodes

Caution: Do not use ALM Octane until you have completed Upgrade spaces in ALM Octane.

After the upgrade on the first node has completed successfully, you can then upgrade the remaining nodes in a cluster.

  1. Copy setup.xml and octane.yml to each node.

  2. Run initserver.bat on each additional node to install and initialize ALM Octane

    C:\octane\install\initserver.bat

For details, see Cluster installation (optional).

Back to top

Upgrade spaces in ALM Octane

After upgrading, log into ALM Octane as the site admin to upgrade each space.

  1. In a browser, navigate to <ServerURL>:<port>/ui?site.

  2. Log in as the space admin, with the user name and password you provided in the setup.xml file.

  3. Click Site and then click the Spaces tab.

  4. Select the space and click Upgrade.

    Upgrade is available only if the space needs to be upgraded.

    Click Refresh to see the updated status for the space.

    Note: Upgraded spaces are, by default, isolated. To work with shared spaces, create new spaces.

  5. Individual workspaces are upgraded in the background. In Settings > Spaces, click Background Jobs to track the progress of the workspace upgrades.

    Note: Until all of the background jobs have completed, some data may be unavailable in trend graphs.

For details on upgrading the space, see Upgrade spaces in the ALM Octane Help Center.

Back to top

Restart all Jetty servers

After upgrading the spaces in Settings, clear caches: 

  1. Stop all Jetty servers.

  2. Restart each Jetty server.

Note: Make sure all Jetty servers are stopped at the same time before restarting even one of them.

Back to top

After the upgrade

After the upgrade has completed successfully:

  • The space status becomes Active.

  • The space version is updated to the current version.

Back to top

Next steps:

  • Update mandatory configuration parameters, such as SMTP_NOTIFICATION_SENDER_EMAIL. See
    Configuration parameters in the ALM Octane Help Center.
  • Download the newest IDE plugins for this ALM Octane version. See IDE integrations in the ALM Octane Help Center.
  • If you work with the REST API, you might want to check if any API resources have been deprecated. While the deprecated resources are supported for a while, we recommend that you start updating your code so that you use the resource aliases instead. To see deprecated resources for a particular version, see the corresponding REST API example and how to use the interactive API client in the ALM Octane Developer Help, What's changed in the REST API.
  • Rollback