12.1.3. Steps for Upgrading an EKM Server

Engineering Knowledge Manager

Installation Guide | Chapter 12: Upgrading an EKM Server from a Previous Version | 12.1. Upgrading from EKM 17.x to EKM 18.2 |

12.1.2. Prerequisites |  | 12.2. Upgrading from EKM 18.0 or 18.1 to EKM 18.2
Prev |  | Next

### 12.1.3. Steps for Upgrading an EKM Server

This section describes the steps needed to perform an upgrade, including details on fulfilling all the prerequisites described in the previous section.

The steps for upgrading an EKM server are:

- Prepare the EKM 17.0 Server for an Upgrade
- Prepare the EKM Database for an Upgrade – Part 1
- Set Up a New EKM 18.2 Server for an Upgrade
- Prepare the EKM Database for an Upgrade – Part 2
- Pre-Upgrade Instructions
- Launch the Upgrade Wizard
- Run the Upgrade Wizard
- Review the Post-Upgrade Instructions
- Post-Upgrade Instructions

#### 12.1.3.1. Prepare the EKM 17.0 Server for an Upgrade

This section describes the steps needed to prepare an EKM 17.0 server for an upgrade. These steps are:

1. Before upgrading, ensure that no workspace is in configuration mode.

2. Verify the existing EKM 17.0 installation.

3. Back up EKM 17.0.

##### 12.1.3.1.1. Verify the Existing EKM 17.0 Installation

Begin your upgrade preparations by verifying the existing EKM 17.0 installation. Verify the location of the `EKM_ROOT170` directory. For example:

Windows: `c:\ekm\v170`

Linux: `/home/ekm/v170`

`EKM_HOME_170` refers to the `EKM_HOME` directory of the existing EKM 17.0 installation: `EKM_ROOT170/ekm-server`

Also, determine if the server uses the default MySQL database server or an existing database server.

##### 12.1.3.1.2. Back Up EKM 17.0

Before upgrading to EKM 18.2, it is necessary to perform a full backup of the EKM 17.0 server. Refer to the Backing Up and Restoring EKM chapter in the EKM 17.0 Administration Guide for more information. If the upgrade procedure fails, you may need to recover your EKM 17.0 server from backup.

Important: Failure to perform a full backup of EKM 17.0 according to the instructions in the EKM 17.0 Administration Guide could result in unrecoverable loss of data.

#### 12.1.3.2. Prepare the EKM Database for an Upgrade – Part 1

EKM provides flexible deployment options for the EKM database and EKM database server. ANSYS EKM Server product installation provides the option to install a default MySQL database server to host the EKM database, or to use an existing MySQL or Oracle database server to host the EKM database.

Depending on the configuration of the EKM 17.0 server being upgraded, and the desired configuration of the new EKM 18.2 server, different steps may be required to prepare the EKM database for an upgrade.

Decisions you make in this step will affect options that must be specified during installation of EKM 18.2 as performed by the ANSYS EKM Server product installation, and may require manual steps to be performed outside of the product installation.

##### Special Instructions for EKM Servers that use MySQL Database Server:

EKM 18.2 supports MySQL server version 5.5.41 or higher.

An EKM 17.0 server (including EKM 17.0, 17.1 or 17.2) that uses an existing MySQL database server that is not installed by the ANSYS EKM Server product installation must also use MySQL database server version 5.5.41 or higher.

ANSYS EKM Server product installation can install a default MySQL database server for EKM 18.2, which is suitable for transferring an EKM 17.0 database that is hosted on an older version of MySQL server. Alternatively, a new MySQL database server meeting the minimum version requirement can be installed manually and used as an existing database server.

In any case where the EKM database must be transferred to a new EKM database server to meet minimum version requirements, the transfer of the EKM database from the old EKM database server to the new EKM database server must be performed prior to executing the Upgrade wizard, and the EKM 18.2 server must be configured to use the new EKM database server that contains the transferred EKM database.

##### Preparing the EKM Database:

Choose from the following options to prepare the EKM database for upgrade, based on the configuration of your EKM database server. The choices you make here will determine certain options you must specify in the ANSYS EKM Server product installation for EKM 18.2:

- Option: Use the existing EKM 17.0 database:

  The EKM 18.2 server is configured to use the same EKM database server and EKM database that are currently being used by EKM 17.0.

  When running the product installation for EKM 18.2: On the Database Server Settings screen, enter values (host name, port number, database name[12], and so on) that match the EKM database server and EKM database being used by the existing EKM 17.0 server (see Installing a New EKM Server).

  Use this option when all of these conditions apply:

  - The EKM 17.0 database is hosted on a database server that meets the minimum database server version requirements for EKM18.2.

  - You do not want to, or do not need to transfer the EKM database to a new EKM database server.

- Option: Use a new EKM database containing the existing EKM 17.0 database data:

  The EKM 18.2 server is configured to use a new EKM database that contains the data from the EKM 17.0 database, which has been exported from the old EKM database server and imported into a new EKM database server. Note that this database transfer may take place before or after running the product installation, but must be completed prior to executing the Upgrade wizard.

  When running the product installation for EKM 18.2: On the Database Server Settings screen, enter values (host name, port number, database name[12], and so on) that match the new database containing the EKM 17.0 database data (see Installing a New EKM Server). The new database can either be hosted on the default MySQL database server installed by the product installation, or on a compatible database server that is installed separately from EKM.

  Use this option when any of the following conditions apply:

  - The EKM 17.0 database is hosted on a database server that does not meet the minimum database server version requirements for EKM 18.2.

  - You want or need to transfer the EKM database to a new EKM database server.

#### 12.1.3.3. Set Up a New EKM 18.2 Server for an Upgrade

Important: The new EKM 18.2 Server must be installed on the same server host as the old EKM server. This requirement is met if one of the cluster nodes of the new server is on the same server host as one of the cluster nodes of the old EKM server.

Before you can upgrade to EKM 18.2 from a previous version of EKM, you must first set up a new EKM 18.2 server for an upgrade. To set up a new EKM 18.2 server for an upgrade, follow these steps:

1. Prepare to set up an EKM server by fulfilling all installation prerequisites (see EKM Server Prerequisites). Some key prerequisites are:

   - Verify that the ANSYS Multiphysics Products Version 18.2 (see Required Software Applications) is correctly installed, licensed, and tested.

   - Verify that ANSYS Licensing is correctly installed, and that licenses for EKM and ANSYS Multiphysics are installed and available for use (see ANSYS Licensing).

2. Follow the steps in Setting Up an EKM Server, making sure to follow the Special Instructions for Upgrade.

3. Follow the steps in Post-Setup, making sure to follow the Special Instructions for Upgrade.

#### 12.1.3.4. Prepare the EKM Database for an Upgrade – Part 2

Prior to executing the EKM Upgrade wizard, as instructed in Prepare the EKM Database for an Upgrade – Part 1, the EKM database from the EKM 17.0 server must be available at the location specified during ANSYS EKM Server product installation for EKM 18.2.

If the EKM database of the EKM 17.0 server needs to be transferred from another database server to the EKM database server specified during product installation for EKM 18.2, this transfer must be completed now.

For MySQL database servers, instructions for backing up and restoring a MySQL database in Backing Up and Restoring EKM provide the instructions necessary to transfer the EKM database from one database server to another by backing it up on the old server and restoring it on the new server.

#### 12.1.3.5. Pre-Upgrade Instructions

The EKM Upgrade wizard will be run on one and only one of the cluster nodes of the new EKM 18.2 server. As previously mentioned in the Prerequisites, one of the cluster nodes of the new EKM server must be on the same server host as one of the cluster nodes of the old EKM server. The EKM Upgrade wizard will be run on this one server host, and will upgrade the EKM database and EKM repositories to EKM 18.2. General Post-Upgrade Instructions and cluster-specific Post-Upgrade Instructions are then followed to complete the upgrade to EKM 18.2.

#### 12.1.3.6. Launch the Upgrade Wizard

Important: Before proceeding with any of the following steps, it is a requirement that you back up the EKM 17.0 server, including the database (see Back Up EKM 17.0). The Upgrade wizard will upgrade the data in the EKM database to be compatible with EKM 18.2. It will no longer work with EKM 17.0 once it has been upgraded to work with EKM 18.2.

If there are problems with the EKM upgrade, it may be necessary to restore the EKM 17.0 database before attempting the upgrade again.

EKM 18.2 provides a utility called the EKM Upgrade wizard (“Upgrade wizard”) that helps automate the upgrade of an old EKM 17.0 server to a new EKM 18.2 server, and converts the EKM server data to the new EKM 18.2 format.

To launch the Upgrade wizard from the command line on Windows or Linux systems, use the Upgrade wizard launch script:

`EKM_ROOT182/utils/bin/UpgradeEKMServer.(cmd|sh)`

Important: The Upgrade wizard should be launched using the EKM server account. This will ensure that the Upgrade wizard can access all necessary files and EKM data.

Once the Upgrade wizard is launched, follow the steps to run the Upgrade wizard and perform an upgrade.

#### 12.1.3.7. Run the Upgrade Wizard

Once you have prepared for an upgrade and set up a new EKM 18.2 server, you are now ready to perform the upgrade using the Upgrade wizard.

Important: You must fulfill the required prerequisites before running the Upgrade wizard.

##### Fulfilling the Prerequisites

Important: The Upgrade wizard can be used to upgrade to EKM 18.2 only if specific prerequisites are satisfied (see Prerequisites).

Before Launching the Upgrade Wizard:

1. Stop the old EKM server.

2. Stop the new EKM server.

3. Start the database server that will be used by the EKM 18.2 database server. This database server must contain the EKM database from the EKM 17.0 server, which will be upgraded by the Upgrade wizard for use with EKM 18.2 (see Prepare the EKM Database for an Upgrade – Part 1 and Prepare the EKM Database for an Upgrade – Part 2). During the upgrade, you will be asked by the Upgrade wizard to confirm that this database server is running before proceeding further.

   You may now launch the Upgrade wizard using the EKM server account.

4. In the Prerequisites step, click on the links to the Installation Guide to review the prerequisites that are required for upgrade. Select Prerequisites fulfilled only if all of the requirements are met. Click Next > to continue.

   Figure 12.1: Upgrade Wizard: Prerequisites Step

5. In the Setup Directories step, specify the base directory (`EKM_NODE_ROOT`) for one of the cluster nodes of the old server (for example, `C:\ekm\node1`).

   Then, specify the base directory (`EKM_NODE_ROOT`) for one of the cluster nodes of the new EKM server (for example, `C:\ekm\node1`).

   Note that every EKM server installation is a cluster configuration, even if the cluster has only one node. When upgrading to a multi-node EKM server, specify the base directory of one of the cluster nodes. The Upgrade wizard is only run on one and only one cluster node, regardless of how many nodes there are.

   Click Next > to continue.

   Figure 12.2: Upgrade Wizard: Setup Directories Step

6. In the EKM Database step, confirm that the EKM 17.0 database is ready to be upgraded to work with EKM 18.2. Select I have fulfilled the requirements only if all of the requirements are met.

   Figure 12.3: Upgrade Wizard: Prepare the EKM Database Step

   Summary of requirements listed in this dialog:

   - Requirement 1

     If you have completed the database preparation outlined in Prepare the EKM Database for an Upgrade – Part 1 and Prepare the EKM Database for an Upgrade – Part 2, this requirement has been met.

   - Requirement 2

     If not already running, start the database server now for the EKM database shown in the dialog box.

   Click Next > to continue.

7. In the Upgrade step, EKM will upgrade the EKM server data to the EKM 18.2 format. The `Upgrading EKM Server...` message will persist during the process. This may take a while. Click Finish when the upgrade is completed.

   Figure 12.4: Upgrade Wizard: Upgrade Step

#### 12.1.3.8. Review the Post-Upgrade Instructions

The upgrade from EKM 17.0 to EKM 18.2 is now complete. Before the new EKM server can be used, certain post-upgrade instructions must be followed. These are documented below.

Before using the upgraded EKM server, all users who access the EKM server must clear their browser caches. This will prevent display problems in the EKM web client that can be caused by cached information from the old version of EKM.

#### 12.1.3.9. Post-Upgrade Instructions

This section documents post-upgrade steps that must be performed before the new EKM server can be used.

- Synchronize the Repository Folders on All Cluster Nodes
- Synchronize the Revision ID for All Cluster Nodes in the Cluster Database
- Copy Audit Log Files
- Update Shared Applications

##### 12.1.3.9.1. Synchronize the Repository Folders on All Cluster Nodes

When upgrading to EKM 18.2, the Upgrade wizard is run on one cluster node of the new server. Along with updating the EKM database and EKM data directory to EKM 18.2, the Upgrade wizard updates the content of the `REPOSITORIES_HOME_182` folder of this cluster node. This updated `REPOSITORIES_HOME_182` folder needs to be manually synchronized to the other cluster nodes of the new server after the Upgrade wizard completes.

In the instructions that follow, we present an example scenario of a three-node cluster whose node names are `node1`, `node2`, and `node3`. The Upgrade wizard is run on `node1`.

1. Save a backup copy of the `repository.xml.template` on the other cluster nodes, or make a note of the cluster ID of each cluster node. The cluster ID is set in `REPOSITORIES_HOME_182/repository.xml.template` in the `id` attribute of the `Cluster` element, and is set to the value entered for the EKM cluster node ID during the product installation.

2. Copy the entire `REPOSITORIES_HOME_182` directory from `node1` of the cluster to each of the other cluster nodes.

3. Visit each of the other cluster nodes and modify the contents of the `REPOSITORIES_HOME_182/repository.xml.template` and the `repository.xml` file within each subdirectory of `REPOSITORIES_HOME_182`. In each `repository.xml` file, set the cluster ID back to its original, correct value for that cluster node.

The following are example paths for `REPOSITORIES_HOME_182` in a cluster of three nodes:

    c:\ekm\node1\repositories
    c:\ekm\node2\repositories
    c:\ekm\node3\repositories

Example 12.1: Synchronize the repository folders of node2 and node3 with the repository folder of node1

1. Make note of the cluster IDs of `node2` and `node3`.

   1. In `REPOSITORIES_HOME_182/repository.xml.template` on node2, the cluster ID is `node2`:

          <Cluster id="node2" syncDelay="2000">

   2. In `REPOSITORIES_HOME_182/repository.xml.template` on node3, the cluster ID is `node3`:

          <Cluster id="node3" syncDelay="2000">

2. On `node2` and `node3`, delete the `REPOSITORIES_HOME_182` folder.

3. On `node2` and `node3`, copy the `c:\ekm\node1\repositories` folder to `c:\ekm\node2\repositories` on `node2` and to `c:\ekm\node3\repositories` on `node3` to replace the deleted `REPOSITORIES_HOME_182` folder.

4. On `node2` and `node3`, edit `REPOSITORIES_HOME_182/repository.xml.template` to set the cluster ID back to the original, correct value for that cluster node.

5. On `node2` and `node3`, for each subdirectory in `REPOSITORIES_HOME_182`, edit `repository.xml` to set the cluster ID back to the original, correct value for that cluster node.

##### 12.1.3.9.2. Synchronize the Revision ID for All Cluster Nodes in the Cluster Database

Connect to the EKM cluster database and for each repository check the `REVISION_ID` value for all of the cluster nodes:

- Each repository is represented in the database by a set of database tables with a common table name prefix "`r`N`_`" where ``N`` is a number; for example: `r0_` and `r1_`.

- For each repository with table name prefix `r`N`_`, the value of `REVISION_ID` for all cluster nodes in the table `rN_jl_local_revisions` should be the same for all cluster nodes and should be the same as the value of `REVISION_ID` in the table `rN_jl_global_revision`.

An example is shown below, with additional instructions shown in bold:

    mysql> use ekm;
    Database changed

    mysql> show tables like '%revision%';
    +----------------------------+
    | Tables_in_ekm (%revision%) |
    +----------------------------+
    | r0_jl_global_revision      |
    | r0_jl_local_revisions      |
    | r1_jl_global_revision      |
    | r1_jl_local_revisions      |
    +----------------------------+
    4 rows in set (0.00 sec)

    There are two repositories, with table name prefixes: r0_ and r1_.

    mysql> select * from r0_jl_global_revisions;
    +-------------+
    | REVISION_ID |
    +-------------+
    |     3255318 |
    +-------------+
    1 row in set (0.00 sec)

    mysql> select * from r0_jl_local_revisions;
    +------------+-------------+
    | JOURNAL_ID | REVISION_ID |
    +------------+-------------+
    | node1      |     3255318 |
    | node2      |     1347377 |
    | node3      |     1473274 |
    +------------+-------------+
    3 rows in set (0.00 sec)

    If there are incorrect values for any of the nodes,
    correct the values as shown below. Note that there may
    not be values stored for all nodes, so the steps to delete
    may not be needed.

    delete from r0_jl_local_revisions WHERE JOURNAL_ID='node2';
    delete from r0_jl_local_revisions WHERE JOURNAL_ID='node3';

    insert into r0_jl_local_revisions (JOURNAL_ID, REVISION_ID) values ('node2', '3255318');
    insert into r0_jl_local_revisions (JOURNAL_ID, REVISION_ID) values ('node3', '3255318');

    Verify that all values are now the same.

    mysql> select * from r0_jl_global_revision;
    +-------------+
    | REVISION_ID |
    +-------------+
    |     3255318 |
    +-------------+
    1 row in set (0.00 sec)

    mysql> select * from r0_jl_local_revisions;
    +------------+-------------+
    | JOURNAL_ID | REVISION_ID |
    +------------+-------------+
    | node1      |     3255318 |
    | node2      |     3255318 |
    | node3      |     3255318 |
    +------------+-------------+
    3 rows in set (0.00 sec)

    mysql>

    Repeat this procedure for each repository.

##### 12.1.3.9.3. Copy Audit Log Files

Before starting EKM, copy any audit log files from the EKM 17.0 log directory (`EKM_HOME_170/ekm-server/logs`) to the EKM 18.2 log directory (`EKM_HOME_182/ekm-server/logs`).

##### 12.1.3.9.4. Update Shared Applications

If you are upgrading from EKM 17.0, follow the steps below after starting EKM. You do not need to perform these steps if you are upgrading from 17.1 or 17.2.

1. Sign in to EKM as an administrator (a member of the `admin` group).

2. Go to the Adminstration section and select the Shared Applications page.

3. Select the Batch job application and select Edit > Application.

4. In the Edit Custom Application dialog box, change the Macro name for dialog creation to `com.ansys.ingress.core.ui.job.launcher.ExecuteBatchJobWizard`. Click OK.

5. Select the Interactive job application and select Edit > Application.

6. In the Edit Custom Application dialog box, change the Macro name for dialog creation to `com.ansys.ingress.core.ui.job.launcher.ExecuteInteractiveJobWizard`. Click OK.

[12] The ANSYS EKM Server product installation supplies a default value of `ekm` for the database name. You should change this to be the name of your EKM 18.2 database.

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

Release 18.2 - © ANSYS, Inc. All rights reserved.