Upgrade the GE Digital APM Database Server

Upgrade the GE Digital APM Database to V4.3.0.6.0

To upgrade your GE Digital APM database, you will use the GE Digital 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 GE Digital APM Server.

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

Replace all the baseline database content in your database with the updated baseline GE Digital APM database content.
Compare your public database content to the baseline GE Digital 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.
Record every event in the database upgrade log and display a status on the interface.
Report errors as they occur.
Compile the database when the upgrade is complete.
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 GE Digital 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 yourGE Digital APM Server and GE Digital APM Database Server machines meet the GE Digital 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 GE Digital APM Professional Services department.


Step	Task	Notes
1	Complete all steps before Upgrade the Meridium Enterprise APM Database Server in the upgrade GE Digital APM to GE Digital APM workflow.	This step is required. For example, if you are upgrading your system to GE Digital APM, you should upgrade your dedicated GE Digital APM Server to GE Digital APM before attempting to upgrade your database to the GE Digital 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 GE Digital 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.
4	Log 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 GE Digital APM Oracle Schema on the GE Digital 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.
6	If you are running SQL Server 2014 and you encountered the following timeout error when performing the upgrade in a test environment: `<date> - task C:\DBUMS\CONTENT\Versions\4030000\31_PostIEU_VerDepScripts\2070_ROUNDS_SEQ.MS.SQL has a staus of Failed` `<date> - Error: Microsoft.SqlServer.Management.Common.ExecutionFailureException: An exception occurred while executing a Transact-SQL statement or batch. ---> System.Data.SqlClient.SqlException: Timeout expired. The timeout period elapsed prior to completion of the operation or the server is not responding.` ...you need to reset the database compatibility level. If you encountered this error, set the compatibility level to 110.	This step is required only if you are running SQL Server 2014 and you encountered the specified timeout error.
7	Log 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 GE Digital APM version V4.2.0.0 or later.
8	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.
9	Log 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 GE Digital APM Oracle Schema on the GE Digital APM Database Server.
10	If you reset the database compatibility level in the previous workflow step, revert the database compatibility level to the original value recorded in the previous step.	This step is required only if you are running SQL Server 2014 and reset the database compatibility level in the previous workflow step.
11	If 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 GE Digital 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.
12	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.
13	Confirm 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 GE Digital APM Default site was added to the Site Reference family during the database upgrade. If the GE Digital 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 GE Digital 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 GE Digital 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 GE Digital 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.
14	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 GE Digital APM Default site was added to the Site Reference family. If the GE Digital 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 GE Digital APM Default site and one other site), then all users are assigned to the site that is not GE Digital APM Default site, and the site that is not GE Digital 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 GE Digital 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.
15	If the system from which you upgraded utilized an Oracle Database Server, then configure the GE Digital APM Server for Oracle components.	This step is required only if the system from which you upgraded utilized an Oracle Database Server.
16	Remove database notification elements from the database.	This step is not mandatory, but is recommended by GE Digital APM.
17	In GE Digital APM, build the search index.	This step is not mandatory, but is recommended by GE Digital 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 GE Digital APM database and are displayed in some form via the GE Digital 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 baselineGE Digital APM database. With the exception of rules and Catalog items, you cannot view baseline content in the GE Digital 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 GE Digital 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 GE Digital 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 GE Digital 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 GE Digital 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 GE Digital 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 GE Digital 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 GE Digital APM's changes

-or-

Apply GE Digital 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 GE Digital APM delivers for that item in a given release. In other words, if GE Digital 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 GE Digital APM Release Notes for that version. For example, if GE Digital APM changes a baseline field caption, it is possible that GE Digital 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 GE Digital APM database content that has been updated in the target version (i.e., content that includes new baseline changes from GE Digital APM).

-and-
Among the content that has been updated in the baseline GE Digital 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 GE Digital 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 GE Digital APM database for the target version and the same baseline query as it exists in your current version. For example, you could see that GE Digital 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, GE Digital 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. GE Digital 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 Type	Protected?	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 GE Digital 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 GE Digital 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 GE Digital APM system will begin upgrading your database through a process that consists of the following steps:

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

The following instructions assume that your dedicated GE Digital APM Server already contains the version of the GE Digital 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

On the dedicated GE Digital APM Server machine, on the Start menu, expand the Meridium APM Applications folder.
Select Database Upgrade Manager.
The Meridium Database Upgrader window appears.
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 GE Digital 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.
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 GE Digital 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.
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 GE Digital 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.
To initiate the database upgrade process, select Upgrade.
The Progress section displays the progress of the upgrade process.
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 GE Digital APM. To do so:
1. On the Meridium Database Upgrader window, select Show Log.
  The log appears in a new window.
2. Send the file to GE Digital APM . When you do, be sure to provide your company name and an indication that the files are database upgrade log files.
After you have successfully upgraded your database and sent the upgrade logs to GE Digital APM, restart the GE Digital APM Server.

What to do next

The next step in the GE Digital APM Database Server upgrade workflow varies, depending on whether you initiated the upgrade in a test or production environment.

Configure the GE Digital 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 GE Digital 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

On the GE Digital APM Server machine, open two Windows explorer windows.
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.
In each folder, using a text editor (for example, Notepad), open the file machine.config.
In each file, between the opening and closing <configuration> tags, delete the following content:
Save the files, and then close them.

What to do next

Refer to the GE Digital APM Database Server upgrade workflow.

Remove Database Notification Elements from the Database

About this task

After upgrading your GE Digital APM Database Server, GE Digital recommends 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

Refer to the GE Digital APM Database Server upgrade workflow.