Upgrade the APM Database Server

Upgrade the APM Database to V4.6.10.0.0

To upgrade your APM database, you will use the APM Database Upgrade Manager application, which guides you step-by-step through the database upgrade process. The application is installed automatically when you install the APM Server.

During the database upgrade process, the APM Database Upgrade Manager will:

  1. Replace all the baseline database content in your database with the updated baseline APM database content.
  2. Compare your public database content to the baseline APM database content, and then:
    • Retain any customized database content.
    • Replace any database content that you have not customized in your database with the updated baseline database content.
  3. Record every event in the database upgrade log and display a status on the interface.
  4. Report errors as they occur.
  5. Compile the database when the upgrade is complete.
  6. Display a confirmation message when the database upgrade process is complete.
The progress of this process will be displayed while it is running. When it is finished, a message will appear, displaying a summary that includes the number of failures, if any, that occurred during the upgrade process.
Note: The information in this note applies only to SQL Server. Altering the database recovery mode to SIMPLE for the duration of the upgrade will limit disk space consumption on the APM Database Server and may be necessary to successfully upgrade larger databases. The database upgrade executes many transactions, all of which are logged by SQL Server. If the database is in FULL recovery mode, SQL Server must retain all of these transactions, causing the transaction log file to become very large. This could potentially cause the upgrade to fail by consuming all available disk space or exceeding the size limit for the file.

Upgrade failure of this kind can be safely avoided by temporarily modifying the database recovery mode to SIMPLE before running the upgrade and then resetting it to FULL after the upgrade. Your database administrator can use the following commands to modify the database recovery mode:

To put the database in SIMPLE recovery mode:

USE [master] 
GO
ALTER DATABASE [mydb] SET RECOVERY SIMPLE WITH NO_WAIT
GO

To put the database in FULL recovery mode:

USE [master]
GO
ALTER DATABASE [mydb] SET RECOVERY FULL WITH NO_WAIT
GO

For more information about SQL Server database recovery modes, consult the Microsoft documentation.

Upgrade workflow

The table in this section lists the prerequisite tasks that must be completed before you initiate the database upgrade process. These instructions assume that your APM Server and APM Database Server machines meet the APM hardware and software requirements. You can use the Database Upgrade Manager to upgrade a database from any version V3.4.0 SP3 or later to your target version. Details on upgrading from a starting version that is earlier than V3.4.0 SP3 are not provided in this documentation. For more information on upgrading your database from a version earlier than V3.4.0 SP3, contact the APM Professional Services department.

Step

Task

Notes

1

Complete all steps before Upgrade the Meridium Enterprise APM Database Server in the upgrade APM to APM workflow.

This step is required. For example, if you are upgrading your system to APM, you should upgrade your dedicated APM Server to APM before attempting to upgrade your database to the APM database version. Doing so ensures that your machine contains the latest database content file, which is a compressed folder containing the content of the baseline APM database for the target database version.

2

Read and understand how your customizations will be protected during the upgrade process.

You will need to understand how your content is protected to determine what, if any, content you should export from your pre-upgrade database before initiating the database upgrade process.

3

Create a backup of your database.

You should always back up the database before beginning any upgrade process. If any problems occur during the upgrade, the database can then be restored to its original state from the backup copy.

4Log in to Oracle Server 12.2 as a privileged user, and then run the following command: SQL> GRANT SELECT ANY DICTIONARY TO <user>;

...where <user> is the name of the user that you created when you created the APM Oracle Schema on the APM Database Server.

5

Using a backup copy of your database, perform the upgrade in a test environment.

We recommend that you perform the upgrade in a test environment so that you can assess any issues that you may encounter and correct them before upgrading your database in a production environment.

6Log in to SQL*Plus (or equivalent) as the schema owner, and then run the following command: SQL> EXEC MI_DDL.CRT_SIDX_SI_MI_GEOD_GD

This step is required only if both of the following are true:

  • You plan to use an Oracle Database Server.

    -and-

  • You are upgrading from a version of APM version V4.2.0.0 or later.
7 Perform the upgrade in the production environment.

This step is required.

Note: Before you upgrade your database in a production environment, all the issues that were discovered during the test upgrade must be resolved. Otherwise, the resulting state of your database could be unstable.
8Log in to Oracle Server 12.2 as a privileged user, and then run the following command: SQL> REVOKE SELECT ANY DICTIONARY FROM <user>;

...where <user> is the name of the user that you created when you created the APM Oracle Schema on the APM Database Server.

9If your pre-upgrade database employed Enterprise Data Filtering and you want to convert your Enterprise Data Filtering values to Site Reference Keys, consult a member of the APM Professional Services department for more information.

This step is optional.

If your pre-upgrade database did not employ Enterprise Data Filtering or you do not want to convert your existing Enterprise Data Filtering values to Site Reference Keys, then skip this step.

10 Modify each custom family that you do not want to be enabled for site filtering.

During the upgrade, custom families are set to be enabled for site filtering. For each custom family that you do not want to be enabled for site filtering, you must modify the family by clearing the Enable Site Filtering check box in the Information section of the workspace for the family.

11Confirm that Site Reference Keys were populated correctly during the upgrade. Modify the site assignments for records as needed.

This step is required.

To support site filtering, a APM Default site was added to the Site Reference family during the database upgrade.

If the APM Default site is the only site in your Site Reference family, then records of families that are enabled for site filtering are assigned to it.

If there are two sites in your Site Reference family (i.e., the APM Default site and one other site), then records of families that are enabled for site filtering are assigned to the site that is not APM Default site.

During the upgrade, additional logic is used, based on a record’s specific relationships with other records, to assign a site for each record belonging to a family that is enabled for site filtering.

Note:

The manner in which Site Reference Keys are spread across families to assign sites to records can vary from module to module. If you have questions about how Site Reference Keys were populated during the upgrade, contact the APM Professional Services department.

If a record's site assignment could not be populated automatically during the upgrade, then the record is designated as a global record (i.e., it is not assigned to any specific site).

For some records, the site assignment may need to be modified by a Super User.

12 Verify that users' site assignments and default sites are correct . Assign default sites to any users who do not have one.

This step is required.

To support site filtering, a APM Default site was added to the Site Reference family.

If the APM Default site is the only site in your Site Reference family, then all users are assigned to it, and it is set as their default site.

If there are two sites in your Site Reference family (i.e., the APM Default site and one other site), then all users are assigned to the site that is not APM Default site, and the site that is not APM Default site is set as each user's default site.

If there are three or more sites in your Site Reference family (i.e., the APM Default site and two or more other sites), then no default site is set for users. If there are three or more sites in your Site Reference family, then you must verify site assignments and assign a default site for each user.

13If the system from which you upgraded utilized an Oracle Database Server, then configure the APM Server for Oracle components.This step is required only if the system from which you upgraded utilized an Oracle Database Server.
14 Remove database notification elements from the database.This step is not mandatory, but is recommended by APM.
15In APM, build the search index.This step is not mandatory, but is recommended by APM.

Terms Used in this Documentation

The following table lists the common terms that are used throughout the database upgrade documentation and their definitions.

Term

Definition

Examples

Database content

Items that exist in the APM database and are displayed in some form via the APM interface. There are two versions of database content that exist in your database at a given time:

  • Baseline content: The database content that matches the baseline APM database. With the exception of rules and Catalog items, you cannot view baseline content in the APM interface. This content is stored in a separate location from the corresponding public version of that content.

  • Public content: The database content that you interact with in the APM interface. This content may be the same as the baseline content or it may be the baseline content plus your customizations.

Queries

Entity families

Customized database content

Baseline database content that has changed in your database.

Added a field to a baseline datasheet.

Modified an Entity family description.

Baseline database content

The database content as it is developed and delivered to you in the baseline APM database.

Query in the baseline Catalog folder

Equipment family

Custom content

Database content that exists only in your database and not in the baseline APM database.

New query

New Entity family and fields

Pre-upgrade public version

In the context of the upgrade process, pre-upgrade public version refers to the public version of the database content that exists in your database (prior to upgrading it to the later version).

Query in the Public Catalog folder

Datasheet

(applies whether or not the query or datasheet has been customized)

Pre-upgrade baseline version

In the context of the upgrade process, pre-upgrade baseline version refers to the baseline version of the database content that exists in your database (prior to upgrading it to the later version).

Query in the Baseline Catalog folder.

Datasheet with no customizations

 

Content protection

The process by which the custom changes that you apply to baseline database content are preserved during the database upgrade process. Note that, after you apply changes to baseline database content, the database content is considered customized database content.

Field added to a baseline datasheet in your pre-upgrade database also appears in your upgraded database.

About Customized Database Content Protection

Illustration of content protection

Consider a scenario where Datasheet A exists in the baseline APM database and you want to upgrade a database in which Datasheet A has been customized (e.g., you added a new field). The following diagram illustrates what the two databases would contain in this case, where the squares represent the unchanged baseline datasheet and the hexagon indicates the same baseline datasheet with your customizations.

Note: Note: As indicated by this illustration, in the baseline APM database, the public and baseline versions of an item are always identical.

When this database is upgraded to the new database version, only the baseline version of Datasheet A will be replaced in your database, as illustrated in the following diagram.

In this way, all your custom changes are retained. Likewise, however, your database will not contain the baseline changes that APM delivers in a given release . For this reason, you will want to determine which database items will be retained in your database so that you can determine which baseline changes your database will not contain after you upgrade. With that information, you can determine whether you want to:

  • Continue to use your database content as is, without APM's changes

-or-

  • Apply APM's changes manually to your customized database content.

Database content replacement versus protection

In general, you can assume that all the custom changes you have made to your database content will be retained in your upgraded database. In addition, you can assume that for any custom change that is protected in your database, your database will not contain any baseline changes that APM delivers for that item in a given release. In other words, if APM delivers updated changes to the baseline version of an item that you have customized in your database, you will not receive those changes because your custom changes will take precedence over the baseline changes. As a result, you should evaluate each baseline change that is delivered to determine if you want to apply those changes to your database content.

Note: Note: In a given release, there may be exceptions to the content protection criteria. These exceptions will be communicated via the APM Release Notes for that version. For example, if APM changes a baseline field caption, it is possible that APM can choose to forcibly replace that field caption in your database even if you have customized that field caption already.

You can use the Database Comparison Tool (in pre-upgrade mode) to determine what content will be protected in your database. The output of this tool indicates:

  • The baseline APM database content that has been updated in the target version (i.e., content that includes new baseline changes from APM).

    -and-

  • Among the content that has been updated in the baseline APM database, that which you have customized in your pre-upgrade database.

Using a combination of the results from the Database Comparison Tool and your understanding of the content protection criteria, you can predict which baseline database content changes will not be available in your upgraded database. For example, consider the following scenario in which the Database Comparison Tool indicates that the baseline query Available Recommendations has been updated in the baseline APM database for your target version and that you have customized the Available Recommendations query in your pre-upgrade database.

In this case, you can assume that your upgraded database will contain:

  • Your public version of the Available Recommendations query with all your customizations (in the Public Catalog folder).

  • The updated baseline Available Recommendations query only in the Baseline folder.

Before you upgrade your database, you can use the Database Comparison Tool to view the specific differences between the Available Recommendations query in the baseline APM database for the target version and the same baseline query as it exists in your current version. For example, you could see that APM has added the Asset Description column to the baseline query. At this point, you can decide whether or not you want to either manually apply that change to your custom query after you upgrade or manually replace your public query with the baseline query in the Baseline folder.

Protected database content

The following table lists the types of content that exist in your database and indicates whether customizations to an existing baseline item of that type will be protected during the database upgrade process.

For items in which your customizations will not be protected during an upgrade, to maintain your customizations, you will need to export your customized items from your pre-upgrade database using the Import/Export tool, and then import them into the upgraded database. Alternatively, you can customize the items again, manually, in the upgraded database.

For some attributes of families and family fields, APM may make a change in the baseline database that will be applied to your database, regardless of whether you have customized that item or not. In these cases, the affected content will not be protected. APM will, however, communicate such changes via the release notes for that version (i.e., in the content changes section). For example, if a family caption changes in the baseline database, your database should contain this change. Therefore, if you have made changes to the same family's caption, your customization will be overwritten. You can, however, obtain the baseline content after you upgrade your database.

Baseline Database Content TypeProtected?Notes

Family attributes (Entity and Relationship)

Associated Pages

Yes

Associated Pages are considered one database item per family. This means that if you customize one Associated Page (of many), the database upgrade process will consider all the Associated Pages for that family as customized.

Family description

Yes

None

Family captions

Yes

None

ID Template

Yes

None

Family help text

Yes

None

Datasheets

 

Yes

A single datasheet is considered one database item. This means that if you customize any attribute of a datasheet, the database upgrade process will consider the entire datasheet as customized.

Field attributes

  • Caption

  • Description

  • Help text

  • Override parent flag

  • ID flag

  • UTC

Yes

The UTC property will be protected based on whether records exist for the family to which the field belongs. If records exist in a family, the field property will be protected. In other words, if APM sets the UTC property in a baseline field to True and you already have records in the family to which that field belongs, you will not receive the updated property setting automatically.

Catalog Items

Metric Views

No

Baseline Metric Views are always overwritten with the updated baseline Metric View.

Queries

Yes

None

Reports

Yes

None

Graphs

Yes

None

Security Groups

Security Group caption

Yes

None

Security Group ID

Yes

None

Security Group description

Yes

None

Security Group privileges

No

Baseline Security Group privileges are always overwritten with the updated baseline Security Group privileges.

Records and links between records

Records

Yes (with some exceptions)

After baseline records for a given family exist in your database, the records in that family will never be overwritten or updated during the database upgrade process, even if you have not customized them in any way. This means that if APM delivers updates to the existing baseline records or adds additional baseline records in a given family, you will not receive those changes by default. If this occurs, you can choose to perform an additional step to manually obtain the new records or revert your existing records to baseline.

There are, however, several families whose records are not protected in this way. The following baseline families are considered recurring exceptions to the rule that all records and links are protected. This means that the database upgrade process will overwrite the baseline records in these families. In other words, all the baseline records in the following families will always be overwritten in your database with the updated baseline records:

  • Analysis Services Cube

  • CMMS System

  • Device

  • Device Data Presentation

  • Device Mapping

  • Device Mapping Family

  • Device Mapping Field

  • Pipe Properties

  • Security Group

  • Calibration Template Defaults

This means that if you have customized any baseline record in one of the families in the preceding list, because all the baseline records are overwritten, your changes will be overwritten.

Links between records

Yes

When the records are protected, the relationships that link the records together are also maintained with that record.

Groups of records and links that make up a single entity (e.g., Baseline Risk Matrix)

Yes

A group of records and links that make up a single entity, also known as a composite entity, is treated as one entity for the purposes of the database upgrade process and content protection. After such an entity exists in your database, it will never be overwritten or updated during the database upgrade process, even if you have not customized the records and links in any way.

State Configuration

State Configuration Roles

No

Baseline State Configuration Roles are always overwritten with the updated baseline State Configuration Roles.

State Configuration Role Description

Yes

None

State Configuration Role Caption

Yes

None

State Role Security Group assignments

Yes

None

Strategy Rules and Strategies

Yes

None

Other content

System Codes and System Code Tables

Yes

None

Preferences

Yes

None

UOMs and UOM Conversion Sets

Yes

None

Scheduled Items

Yes

None

Rules Library Projects

Yes

None

Initiate the Database Upgrade Process

About This Task

When you initiate the database upgrade process, the APM system will begin upgrading your database through a process that consists of the following steps:

  1. Unzipping the compressed database content folder and extracting its contents.
  2. Checking the extracted files against the list of baseline files to determine if all the expected files are available.
  3. Loading the baseline database content into your database.
  4. Processing each file and protecting your customized items according to the content protection process.

The following instructions assume that your dedicated APM Server already contains the version of the APM software that corresponds to the database version to which you want to upgrade your database, and that you are ready to upgrade your database in either a test or production environment.

Important: The database upgrade process can take several hours to complete, depending on the size of the database, available memory, and other factors. After you start the database upgrade process, you should not close the window unless you want to stop the database upgrade process.

Procedure

  1. On the dedicated APM Server machine, on the Start menu, expand the Meridium APM Applications folder.
  2. Select Database Upgrade Manager.
    The Meridium Database Upgrader window appears.

  3. Enter the following information about the database that you want to upgrade to the new version:
    1. In the Database Type box, select the database type: SQLServer or Oracle.

      Depending on the value that you select, the remaining boxes may be hidden. The behavior of each box is described in its corresponding step.

    2. The Path to Database Upgrade content box contains the folder path for the compressed database content file that was installed when the APM Server software was upgraded. For example, if you accepted the default location during the APM Server upgrade, the compressed file is installed in the folder C:\Meridium\DbUpg. In this box, select , then navigate to the compressed database content file whose file name contains MI_DB_Master, and then select it.
    3. In the User Name box, enter the user name or schema name that can be used to log in to your database.
    4. In the Password box, enter the password associated with the value in the User Name box.
    5. In the Database Server box, enter the path to the Database Server machine where your database resides. This step applies only to SQL Server database types, and is hidden if you selected Oracle in the Type list.
    6. In the Database Name box, enter the name of the database that you want to upgrade. This step applies only to SQL Server database types. If you selected Oracle in the Type list, the Database Name box will be hidden.
    7. In the Alias box, enter the database alias for the database that you want to upgrade. This step applies only to Oracle database types. If you selected SQLServer in the Database Type box, the Alias box will be hidden.
    8. In the Version box, select the version to which you want to upgrade.
  4. Select Validate.

    The Meridium Database Upgrader window expands.



    The Database Upgrade Manager performs the following checks in the following order:

    • Attempts to connect to the database.

    • Attempts to locate the compressed database content file specified in the Path to Database Upgrade content box.

      Note: Note: If the APM system encounters issues during the first two checks, corresponding messages will be displayed. If you see an error message, you should correct the issue by using the solution indicated in the message.

    When the validation is complete, the list of tasks to be executed appears.

  5. In the Pre-Upgrade Settings section:
    1. In the Trace Level box, select the value indicating the amount of detail that you want to include in the upgrade logs for each operation that occurs during the database upgrade process.
    2. For the Ignore Failed Events check box, which is, by default, cleared:
      • If you are running the database upgrade process in a test environment and want the APM system to continue processing your database even if a failure occurs, select the Ignore Failed Events check box. This will provide you with a comprehensive list of failures after the database upgrade process is complete, which you can use to review and correct the failures.
      • If you are running the database upgrade process in a test environment and want to review each failure as it occurs, accept the default selection. This means that if a failure occurs during the upgrade process, the upgrade process will pause automatically, allowing you to review and correct the failures as they occur.
      • If you are running the database upgrade process in a production environment, accept the default selection. At this point, you should have already run the database upgrade process in a test environment and resolved any errors that occurred. Therefore, you should not expect any errors to occur during the database upgrade process in your production environment. Using this option, however, will ensure that if an error does occur, the upgrade process will not continue.
  6. To initiate the database upgrade process, select Upgrade.
    The Progress section displays the progress of the upgrade process.
  7. After you have successfully upgraded your database, or if you encounter errors that you cannot resolve, send the upgrade logs associated with the upgrade process to APM. To do so:
    Note: If the following error message appears in your upgrade logs, please ignore it: Could not find the guid for the content item named: IntegrationInterfaces.
    1. On the Meridium Database Upgrader window, select Show Log.

      The log appears in a new window.

    2. Send the file to the GE Vernova Customer Support team. When you do, be sure to provide your company name and an indication that the files are database upgrade log files.

  8. After you have successfully upgraded your database and sent the upgrade logs to the GE Vernova Customer Support team, restart the APM Server.

What To Do Next

Configure the APM Server for Oracle Components

About This Task

When installing versions of Meridium APM prior to V4.0.0.0, you were instructed to modify the following files on the dedicated APM Server machine to bind the 64-bit .Net Framework to the Oracle.DataAccess component:

  • C:\WINDOWS\Microsoft.NET\Framework64\V2.0.50727\CONFIG\machine.config
  • C:\Windows\Microsoft.NET\Framework64\V4.0.30319\CONFIG\machine.config

The modifications from previous releases are no longer necessary with ODAC version 11.2.0.3 and must be removed. The following instructions provide details on removing the modifications from these files.

Procedure

  1. On the APM Server machine, open two Windows explorer windows.
  2. In one window, navigate to the folder C:\WINDOWS\Microsoft.NET\Framework64\V2.0.50727\CONFIG.

    -and-

    In the other window, navigate to the folder C:\Windows\Microsoft.NET\Framework64\V4.0.30319\CONFIG.

  3. In each folder, using a text editor (for example, Notepad), open the file machine.config.
  4. In each file, between the opening and closing <configuration> tags, delete the following content:


  5. Save the files, and then close them.

What To Do Next

Remove Database Notification Elements from the Database

About This Task

After upgrading your APM Database Server, we recommend that a Database Administrator manually remove database notification elements from the database.

Procedure

For an Oracle server, the Database Administrator should run the command REVOKE CHANGE NOTIFICATION FROM mi_connect_role. Alternatively, for an SQL server, the Database Administrator should run the command ALTER DATABASE <db_name> DISABLE BROKER.

What To Do Next