Upgrade to ActivID CMS 5.1

ActivID CMS 5.1 only supports upgrades from ActivID CMS 5.0.3. The ActivID CMS upgrade includes a database upgrade.

There are 2 different ways to upgrade the database.

You can use:

  • Manual upgrade: Upgrade the ActivID CMS database manually by using the script packaged with the product, then install ActivID CMS 5.1 using the custom installation mode with the server component only. For detailed instructions on how to install ActivID CMS 5.1 - server only, follow the steps in Install the Server Components Only.

    Note: The upgrade procedure described on the following pages applies to an ActivID CMS installation on Microsoft SQL Server and Oracle databases. However, the screen shots in this procedure were taken on ActivID CMS installed with Microsoft SQL Server, using SQL Server authentication.
    Important: The URLs for the Operator Portal and User Portal must both be added as Trusted Sites in the user’s browser.

Particularities Concerning Upgrade to ActivID CMS 5.1

As with all major upgrades, the previously installed version of ActivID CMS will be removed. However, the mechanism to back up the user data has been modified in order to preserve user settings as much as possible.

A backup directory is created containing the contents of the previously installed ActivID CMS product directory, as well as a manually-constructed version of the settings directory, based on files located in the former WEB-INF/conf folder.

ActivID CMS 5.1 settings are located in the %PROGRAMDATA% directory and are organized into two folders:

  • %PROGRAMDATA%\HID Global\Credential Management System\Local Files, where files containing data exclusive to the current installation are stored, for example: certificates, logging configuration, or obfuscated passwords (for unattended deployments).

    Note: If some certificates files (for instance, Microsoft software KRA Key Recovery Agent) were stored in the "%CMS_INSTALL_DIR%\Certificates" directory before the installation of ActivID CMS 5.1, then they will be moved to the %PROGRAMDATA%\HID Global\Credential Management System\Local Files\Certificates directory after upgrade to ActivID CMS 5.1. As a result, the CA The Certificate Authority (CA) issues and manages security credentials and public keys for message encryption in a networks environment. repository configuration may need to be reviewed to point to the right location after the upgrade.

  • %PROGRAMDATA%\HID Global\Credential Management System\Shared Files, where customizable configuration files that can be shared between different ActivID CMS instances are stored.

    Note: Starting with ActivID CMS 5.1, the cms_portal\WEB-INF\conf folder no longer exists. Files that were previously found in this folder are available in the Shared Files folder listed above.

In addition, database URLs are centralized in a single database.properties file found in the Shared Files folder. The database.properties file contains the database configuration for all ActivID CMS components, including the Exchange Manager and Audit Check tools.

At the end of the installation process, the setup looks in the newly-created backup directory and restores the following files by moving them into the corresponding %PROGRAMDATA% folders:

  • The entire Local Files folder is restored from the back-up data.

  • As well as the following files found in the Shared Files folder:

    • PivEnrollment.properties

    • CivEnrollment.properties

    • Generic_plugins.properties

    • eventNotificationsplugins.properties

    • plugins.properties

    • PIVNotifications.properties

    • CivNotifications.properties

    • Cryptoki.ini

    • acvopsm.cfg

Other modified files (for example, localization properties for the User Portal) are kept in the back-up folder so that the user can manually re-apply the modifications they contain. See Re-apply User Portal Customizations below for details.

Important: When installing a Hotfix to ActivID CMS 5.1, a warning may appear if any conflicts occur between previously customized settings and the new installation. In this case, you must resolve the conflicts before completing the installation.

Installing Custom Profiles

If you need to install, on ActivID CMS 5.1 or higher, a custom profile that was initially delivered for a previous version of ActivID CMS, then the custom profiles readme instructions need to be adapted. Indeed, the following line cannot be applied as is:

  • Apply the files from the cms_portal directory included in this delivery into the "CMS" installation folder (by default, C:\Program Files\HID Global\Credential Management System). Set the Winzip “Use folders names” option.

It should instead read as follows:

  • Copy the sub-directories/files from the cms_portal\WEB-INF\conf\services\custom directory included in this delivery into the %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\services\custom directory.

  • Copy the sub-directories/files from the cms_portal\WEB-INF\conf\services\repositories directory included in this delivery into the %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\services\custom directory.

Re-apply User Portal Customizations

If you had made any updates to the localization files for the User Portal in ActivID CMS 5.0.3, then you MUST make similar updates to the new files included in ActivID CMS 5.1.

Specifically, if you customized the .properties files located in the following directories:

  • cms_install_dir/cms_portal/WEB-INF/classes/cardholder

  • cms_install_dir/cms_portal/WEB-INF/classes/common

then you MUST make the same changes to the new files.

Important: DO NOT OVERWRITE the new ActivID CMS 5.1 files. In order to gain access to the new ActivID CMS capabilities, you should instead update the file content with the relevant edits.
Note: This is not applicable in the case of an upgrade directly from ActivID CMS 5.1 to ActivID CMS 5.9. However, it does apply when you upgrade from ActivID CMS 5.0.3 to ActivID CMS 5.9 in one go as described in Install ActivID CMS with a Service Pack and/or Hotfix.

There are two ways to upgrade:

  1. Run the ActivID Credential Management System.msi program in the ActivID CMS 5.1 distribution.

  2. Go through the wizard until the Upgrade page appears:

  3. Click Next.

    The Select Java Runtime Environment page appears:

  4. Select Use the default Java Runtime Environment, and then click Next.

    This option automatically installs the default Java Runtime Environment (JRE) provided with the ActivID CMS set-up. If you prefer to use a JRE that is already installed on the machine, choose Select an existing Java Runtime Environment and indicate the path to the home directory of the JRE to be used.

    Important: It is not possible to change the JRE subsequently if the Use the default Java Runtime Environment option is chosen during ActivID CMS installation.
    Note:

    • If you choose not to use the default JRE, you must make sure that the JRE selected using the Select an existing Java Runtime Environment option meets the minimum requirements for ActivID CMS.

    • JRE 11 is the minimum requirement for ActivID CMS 5.3 and higher.

    • You can also customize the JRE after installation using the CMS_JAVA_HOME environment variable, but only if the Select an existing Java Runtime Environment option was used during ActivID CMS installation.

    The Database Server Information page appears:

    The Database Server Type and Database Server are preset based on the detected database used with the previous ActivID CMS version and cannot be changed.

    Depending on the authentication mode (Windows vs. SQL Server), some of the fields on this page may differ.

  5. Enter the database passwords:

    • Under Database Administrator Credentials, enter the Login Name and the Database Administrator Password.

    • Under Database Owner Password, enter the Password for the Microsoft SQL Server or the Oracle database owner accounts used by ActivID CMS to connect to the database server. (This is the password you defined when installing your previous version of ActivID CMS.)

  6. Click Next.

    The Web Server Configuration page appears:

  7. Under the Apache Tomcat user account, enter the password for the user account defined during the setup of your previous ActivID CMS installation. The account needs to have a "Log on as a service privilege". See Required Account Types and Privileges and Setting Up “Log On as a Service” Privilege for more details.

  8. Click Next. The Security Key Management page appears:

  9. In the Password field, enter the ActivID CMS Security Key Password defined during the previous ActivID CMS installation.

    This is the Security Key Password you want to set for your ActivID CMS system. The Security Key Password protects a cipher key that encrypts the sensitive fields in the six ActivID CMS databases. It is required to start the ActivID CMS portal.

  10. If Hardware Security Module was selected in the initial installation, then browse for the appropriate HSM Library File. Then, enter the HSM PIN in the Operator PIN field. If you selected No, then a warning message appears when you click Next.

    The Library file refers to the HSM drivers that must be installed manually. Each HSM comes with its own installation program for installing the HSM drivers. For information about how to install the HSM drivers on the ActivID CMS server machine, refer to your HSM documentation.

    Note: With ActivID CMS, the required HSM drivers to be used are 64-bit drivers.

    The PIN protects the access to the keys stored in the HSM. You must specify the HSM Operator PIN that was set when you initialized the HSM with the Key Management System (not applicable for network HSMs).

    Note: For upgrade with an Entrust platform, a reconfiguration is to be done in the entrust.ini file to use the achsmf.dll file located in (%SystemDir%\system32) since Entrust components are now using 64-bit HSM drivers. Refer to the HID ActivID Credential Management System Entrust Authority Technical Note for more information on the configuration of the entrust.ini file.

  11. Click Next.

    The Ready to Install the Program page appears:

  12. Click Upgrade to start the upgrade process.

    After the install is complete, the InstallShield Wizard Completed page appears:

  13. Click Finish.

  14. Reboot the Windows server for the changes to take effect.

    If attended startup mode was selected during setup, see Provide Passwords in Attended Startup Mode in order to start ActivID CMS.

The following procedure applies to an ActivID CMS installation on Microsoft SQL Server and Oracle databases. However, the screenshots in this procedure were taken on ActivID CMS installed with Microsoft SQL Server using SQL Server authentication. The procedure has two main steps:

  1. Upgrade the ActivID CMS database manually by using the script packaged with the product.

  2. Run the ActivID CMS installer to perform the software upgrade.

Before upgrading, be sure to refer to the release-note.txt file in the DBScripts folder of the ActivID CMS distribution for detailed instructions.

You can upgrade ActivID CMS using database scripts on:

  • Microsoft SQL Server using Windows authentication

    Note: To upgrade ActivID CMS with SQL in Windows authentication mode, you have to log in as User or Administrator of the domain; if you use a local account, you are not able to upgrade ActivID CMS.

  • Microsoft SQL Server using Mixed Mode authentication

  • Oracle Database 11g, 12c, 18c or 19c

Note: To perform this database upgrade in Windows authentication mode, you have to log in as User or Administrator of the domain.

  1. On the ActivID CMS distribution, go to: \DBScripts\sqlserver and copy all the files on your hard disk.

  2. Right-click the hard-disk copy of the file sqlserver-config.bat, and then click Edit. Make sure you deselect the “Read-only” field in the Properties of the file.

  3. Set the values for the following variables:

    • DB_INSTANCE (Set the ActivID CMS Database Server and Instance name)

    • CMS_AUTH_MODE (Set to WindowsAuthMode)

    • CMS_NT_USR (Set the ActivID CMS database user’s NT username)

  4. Run the sqlserver-upgrade.bat file.

  5. Run the sqlserver-populate.bat file.

  1. On the ActivID CMS 5.1 distribution, go to: \DBScripts\sqlserver and copy all the files on your hard disk.

  2. Right-click the hard-disk copy of the file sqlserver-config.bat, and then click Edit. Make sure you deselect the “Read-only” field in the Properties of the file.

  3. Set the values for the following variables:

    • DBA_USR

    • DBA_PWD

    • DB_INSTANCE

    • CMS_AUTH_MODE (Set to MixedAuthMode)

    • CMS_SQL_PWD

  4. Run the sqlserver-upgrade.bat file.

  5. Run the sqlserver-populate.bat file.

  1. On the ActivID CMS 5.1 distribution, go to: \DBScripts\oracle and copy all the files on your hard disk.

  2. Right-click oracle-config.bat, and then click Edit.

  3. Set the values for the following variables:

    • INPUT_DBA_USR

    • INPUT_DBA_PWD

    • INPUT_DATABASE_INSTANCE

    • INPUT_DBO_PWD

    • INPUT_DATAFILES_PATH

    • INPUT_INDEXFILES_PATH

  4. Define the password values in the oracle-config.bat file:

    • If the password contains a percent sign (pass%word), add an additional percent sign (pass%%word) to the password value.

    • If the password contains a > or < sign (pass>word), add a caret sign (^) before each > or < sign (pass^>word) to the password value.

  5. Run the oracle-upgrade.bat file. (Do not call the oracle-upgrade.bat file twice on the same ActivID CMS database because it installs the AIMSRQI database from zero.)

  6. Run the oracle-populate.bat file.

  7. Run the oracle-expimp-aimsrqi.bat file.

  8. Complete the upgrade by installing ActivID CMS 5.1 in custom installation mode without the database component. Follow the steps in Install the Server Components Only.