Policy Designer Upgrade

Upgrade or Update Policy Designer to V5.2.1.0.0

The following table provides you the reference to procedures to upgrade from an earlier APM version to the latest version.

Note: If your APM database contains a large number of Policy Execution History records, the upgrade may take a long time or may time out. To avoid this issue, only the most recent 3,000,000 records are upgraded. You can choose to remove some or all the Policy Execution History records before the upgrade. For information, refer to Improve Upgrade Performance.


Upgrade from	Upgrade to	Procedure
V5.2.x	V5.2.1.0.0	Upgrade from any version V5.2.0.0.0 through V5.2.0.1.0
V5.1.x	V5.2.1.0.0	Upgrade from any version V5.1.0.0.0 through V5.1.3.1.0
V5.0.x	V5.2.1.0.0	Upgrade from any version V5.0.1.0.0 through V5.0.6.0.0
V4.6.2 or a later V4.6.x release	V5.2.1.0.0	Upgrade from any version V4.6.2.0.0 through V4.6.10.0.0 Upgrade from any version V5.0.1.0.0 through V5.0.6.0.0
V4.6.1.x or earlier	V5.2.1.0.0	Upgrade from any version V4.6.1.x or earlier to V4.6.2.0.0 or a later V4.6.x release Upgrade from any version V4.6.2.0.0 through V4.6.10.0.0 Upgrade from any version V5.0.1.0.0 through V5.0.6.0.0 Note: For more information on upgrading to APM V4.6.2.0.0 or a later V4.6.x release, refer to the Upgrade documentation for the corresponding version.

Upgrade from any version V5.2.0.0.0 through V5.2.0.1.0

This module will be upgraded to V5.2.1.0.0 automatically when you upgrade the components in the basic APM system architecture. No additional steps are required.

Upgrade from any version V5.1.0.0.0 through V5.1.3.1.0

This module will be upgraded to V5.2.1.0.0 automatically when you upgrade the components in the basic APM system architecture. No additional steps are required.

Upgrade from any version V5.0.1.0.0 through V5.0.6.0.0

This module will be upgraded to V5.2.1.0.0 automatically when you upgrade the components in the basic APM system architecture. No additional steps are required.

Upgrade from any version V4.6.2.0.0 through V4.6.10.0.0

The following tables outline the steps that you must complete to upgrade this module to V5.2.1.0.0. These instructions assume that you have completed the steps for upgrading the basic APM system architecture.

These tasks may be completed by multiple people in your organization. We recommend, however, that the tasks be completed in the order in which they are listed.


Step	Task	Notes
1	Configure the time limit for the Policy Execution Service.	This step is optional. You can perform this step if you want to modify the policy execution time limit for the Policy Execution Service. By default, the policy execution time limit is 15 minutes per policy instance.
2	Configure the time limit for the execution of the Math node.	This step is optional. You can perform this step if you want to modify the Math node execution time limit for the Policy Execution Service. By default, the Math node execution time limit is 5 minutes.
3	Configure the SubPolicy Node for Policy Execution	This step is optional.
4	Configure the alternative query for the Policy Designer Overview page.	This step is optional. You can perform this step if you are facing performance issues with the Policy Designer Overview page.
5	Configure the settings for the Policy Execution Service.	This step is optional. You can perform this step if you want to modify the default retries, concurrency, or duplicate trigger timeout settings.
6	On the APM Server, stop and restart the Meridium Policy Execution service.	This step is required. If your system architecture contains more than one APM Server, you must complete this step for every server that you want to use for policy execution. You can review the log files for this service at C:\ProgramData\Meridium\Logs.
7	Configure the settings for the Policy Trigger Service.	This step is optional. You can perform this step if you want to modify the default retries or concurrency settings.
8	On the APM Server, stop and restart the Meridium Policy Trigger service.	This step is required. If your system architecture contains more than one APM Server, you must start the Policy Trigger Service on at least one APM Server. You can review the log files for this service at C:\ProgramData\Meridium\Logs.
9	On the APM Server, reset IIS.	This step is required only if you have modified the time out value for the Math node execution or Policy Execution in the appSettings.json configuration file.
10	Review and upgrade the following items: Baseline Policies Relationship Nodes Delete Entity Nodes Nodes in Sub Policies Policies and Queries referencing Content GUIDs Query nodes Policy Instances	This step is required. For more information, refer to About Upgrading Policy Designer and Family Policies.

About the Asset Health Services

When you deploy the Asset Health Manager, OT Connect, and Policy Designer modules together, the services used by each module interact with each other in various ways. This topic summarizes those services and describes a standard system architecture containing the components used by all three modules.

Services Summary

The following services are used by the Asset Health Manager, OT Connect, and Policy Designer modules:

Asset Health Indicator Service: Automatically updates the following field values in a Health Indicator record when reading values related to the health indicator source record (for example, an OT Source Tag or Measurement Location record) change:
- Alert Level
- Last Reading Date
- Last Char Reading Value (for records that accept character values)
- Last Numeric Reading Value (for records that accept numeric values)
This service also facilitates the automatic creation of Health Indicator records for configured sources.
Policy Trigger Service: When an input to a policy (that is, an associated record in the APM database or reading value in the process historian) changes, when a policy schedule is due, or a user submits an Execute Now request, a message is added to the policy trigger queue. The Policy Trigger Service monitors the trigger queue. When it receives a message, it determines which policy instances should be executed for the message, and then it sends corresponding messages to the policy execution queue. Even if your APM system is configured with multiple Policy Execution servers, only one policy execution queue is used.
Policy Execution Service: The Policy Execution Service handles the execution of policies. Specifically, the Policy Execution Service monitors the policy execution queue and executes the policy instances that are added to it. If the APM system is configured with multiple Policy Execution servers, when each Policy Execution Service completes the execution of a policy instance, it will execute the next instance from the shared policy execution queue. In this way, the policy execution load is automatically balanced across all available Policy Execution Services.
OT Connect Service: Monitors the subscribed tags (that is, tags that are used in policies and health indicators) and when data changes occur on these tags adds messages to the appropriate queues. This service also facilitates the automatic import and synchronization of tags from a configured OT Source. For more information, refer to the OT Connect section of the documentation.

Standard System Architecture Configuration

The following diagram illustrates the machines in the APM system architecture when the Policy Designer, OT Connect, and Asset Health Manager (AHM) modules are used together. This image depicts the standard configuration, where the OPC Server software and the OT Connect Adapter Service are on the same machine.

Note: In this example configuration, only one machine of each type is illustrated. Your specific architecture may include multiple APM Servers, multiple OPC Servers, or multiple APM Servers used for policy executions.

The following table summarizes the machines illustrated in this diagram and the software and services that you will install when you complete the first-time deployment steps for Asset Health Manager, OT Connect, and Policy Designer.


Machine	Software Installed	Service Installed with APM Software
APM Server	APM Server software	Asset Health Indicator Service
		Policy Trigger Service
		Policy Execution Service
		OT Connect Conductor Service
OPC Server	GE Vernova OT Connect Adapter software	OT Connect Adapter Service
OPC Server	OPC Server software	N/A
Process Historian	Process historian software	N/A

About Policy Execution

Policy designers can configure a policy to be executed on a schedule or automatically when records or reading values associated with the policy are updated. Policies may also be executed on demand. This topic describes the ways that the items configured in the first-time deployment workflow facilitate each type of policy execution.

Note: Only the active instances of active policies are executed.

Automatic Execution

When any record or reading value is updated by the APM Server, or when a reading value for a tag associated with one or more policies is updated on the process historian, a message is added to the policy trigger queue. The Policy Trigger Service monitors the trigger queue. When it receives a message, it determines which policy instances should be executed for the message, if any. Only active policy instances associated with the record or reading update will be executed. The Policy Trigger Service then sends corresponding messages to the policy execution queue for each relevant policy instance. Finally, a Policy Execution Service executes each policy instance that was added to the policy execution queue in turn.

Scheduled Execution

When a scheduled policy is due, a scheduled job adds a message to the policy trigger queue. The Policy Trigger Service monitors the trigger queue and sends messages to the policy execution queue for each active instance of the policy. Finally, a Policy Execution Service executes each active instance that was added to the policy execution queue in turn.

On Demand Execution

When you request a policy or policy instance execution from the Policy Designer user interface, or select a hyperlink configured to execute a policy or policy instance, a message is added to the policy trigger queue. The Policy Trigger Service monitors the trigger queue and sends messages to the policy execution queue for each active instance of the policy. Finally, a Policy Execution Service executes each active instance that was added to the policy execution queue in turn.

Configure Queue Settings for Policy Execution Service

About This Task

The Policy Execution Service processes messages from queues, which are managed by ActiveMQ. The Policy Execution Service provides the following queue configuration options:

Retries
Redelivery attempts and interval
Concurrency limit

Increasing the concurrency limit allows the policy execution service to process more messages in parallel, resulting in higher throughput of policy executions, provided that the system has available resources. Reducing the concurrency limit reduces the policy execution throughput and the system resources used by policy execution. APM recommends that the concurrency limit be less than or equal to the number of logical processors on the APM Server used for policy executions.

Procedure

On the APM Server, access the folder that contains the Policy Execution Service files.

Note: If you have installed APM in the default location, you can locate the folder in C:\Program Files\Meridium\ApplicationServer\policy-execution.
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).

In the file, locate the following text:

"triggerMessageSettings": {
    "concurrencyLimit": 8,
	    "retries": 5,
	    "redeliveryAttempts": 3,
	    "redeliveryMinInterval": 1,
	    "redeliveryMaxInterval": 2440,
	    "redeliveryDelta": 5
	  },
	  "executionMessageSettings": {
	    "concurrencyLimit": 8,
	    "retries": 5,
	    "redeliveryAttempts": 3,
	    "redeliveryMinInterval": 1,
	    "redeliveryMaxInterval": 2440,
	    "redeliveryDelta": 5
	  }

Update the key values as desired.
Save and close the file.
The updated settings will be applied when the Meridium Policy Execution service is stopped and restarted.

Configure Queue Settings for Policy Trigger Service

About This Task

The Policy Trigger Service processes messages from queues, which are managed by ActiveMQ. The Policy Execution Service provides the following queue configuration options:

Retries
Redelivery attempts and interval
Concurrency limit
Duplicate Measurement Location reading trigger elimination timeout

Procedure

On the APM Server, access the folder that contains the Policy Trigger Service files.

Note: If you have installed APM in the default location, you can locate the folder in C:\Program Files\Meridium\ApplicationServer\policy-trigger.
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).

In the file, locate the following text:

"DuplicateTriggerTimeout": 5000,
  
"notificationMessageSettings": {
	"concurrencyLimit": 16,
	"retries": 10,
    "redeliveryAttempts": 3,
    "redeliveryMinInterval": 1,
    "redeliveryMaxInterval": 2440,
    "redeliveryDelta": 5
  }

Update the key values as desired.
Save and close the file.
The updated settings will be applied when the Meridium Policy Trigger service is stopped and restarted.

Configure the Time Limit for Policy Execution

About This Task

The Policy Execution Service limits the amount of time allocated to execute each policy instance. This ensures that the Policy Execution Service queue is not backlogged when a poorly designed policy takes too long to execute. If a policy execution is canceled as a result of the time limit, an error message appears in the policy execution history indicating that the time limit was exceeded. By default, the policy execution time limit is set to 15 minutes per policy instance. The minimum time limit is 1 minute, and the maximum time limit is 1 hour. This topic describes how to modify the Policy Execution Service configuration to change the time limit for policy execution.

Procedure

On the APM Server, access the folder that contains the Policy Execution Service files.

Note: If you have installed APM in the default location, you can locate the folder in the following directory:
C:\Program Files\Meridium\ApplicationServer\policy-execution
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).
In the file, locate the following text:
```
"PolicyExecutionTimeoutMs": 900000
```
Replace 900000 with the time limit value in milliseconds, that you want to apply to policy executions.

Note: The value you enter should be between the minimum time limit of 60000 milliseconds (that is, 1 minute) and the maximum time limit of 3600000 milliseconds (that is, 1 hour).
Save and close the file.
The modified settings are applied when the Policy Execution Service is restarted. If the execution time of a policy instance exceeds the time limit that you have specified, the execution is canceled, and an error message is added to the policy execution history.
On the APM Server, access the folder that contains the Meridium configuration files.

Note: If you have installed APM in the default location, you can locate the folder in the following directory:
C:\Program Files\Meridium
Go to C:\Program Files\Meridium\ApplicationServer\api.
Access the appsettings file in an application that can be used to modify JSON files (for example, Notepad++).
Repeat steps 3 through 5.
The modified settings are applied when Meridium Policy Execution service is stopped and restarted on each policy execution server and IIS is reset on the APM Server.

Configure Execution Time Out Value for Math Node

About This Task

If the execution of a Math node in a policy takes a very long time, the execution times out after a pre-defined duration. By default, the execution times out after 1 minute. However, you can configure the interval after which the execution must time out for the Math node.

Procedure

On the Policy Execution Server, go to C:\Program Files\Meridium\ApplicationServer\policy-execution.
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).
In the file, locate the following text:
```
"MathNodeExecutionTimeout": 60000
```
Replace 60000 with the interval value in milliseconds at which the execution of the Math node must time out.
Save and close the file.
On the APM Server, go to C:\Program Files\Meridium\ApplicationServer\api.
Access the appsettings file in an application that can be used to modify JSON files (for example, Notepad++).
Repeat steps 3 through 5.
The updated settings will be applied when the Policy Execution Service is stopped and restarted on the Policy Execution Server and IIS is reset on the APM Server.

Configure the Default Historical Readings Time Range for the OT Connect Tag node

About This Task

During policy execution, if a specific time range to retrieve the historical data for the OT Connect Tag node cannot be determined. For example, if there is no collection filter applied to the Historical Readings output from the node, by default, two years of data will be added. However, you can change the default time range by modifying the settings on the Policy Execution Server and APM Server.

Procedure

On the Policy Execution Server, go to C:\Program Files\Meridium\ApplicationServer\policy-execution.
Access the appsettings.json file in an application that can be used to modify JSON files (for example; Notepad++).
In the file, locate the following text:
```
"DefaultHdaTimeRangeYrs": 2
```
Replace 2 with the number of years for which you want to retrieve the historical data of the OT Connect Tag node.
On the APM Server, go to C:\Program Files\Meridium\ApplicationServer\api.
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).
Repeat steps 3 through 5.
The updated settings will be applied when the Policy Execution Service is restarted on the Policy Execution Server and IIS is reset on the APM Server.

Configure Alternative Query for the Policy Designer Overview Page

About This Task

To optimize the performance of the Policy Designer Overview page in the systems with a large volume of policy execution history records, the Policies tab displays a simplified view which does not display the latest policy execution results. If you want to see the latest results in the Policies list, you can configure the Policy Designer Overview page to use the alternative query (Policy Overview – Policies Alternate Query) that is provided in the APM Catalog.

Note: When you configure an alternative query for Policy Designer Overview page, you might face some performance issues.

Procedure

Access APM using the super user account.
Access the Catalog page.
In the Catalog section, select Public > Meridium > Modules > Policy Manager > Queries.
The Queries workspace appears, displaying the catalog items of the Queries folder in a table.
Select the check box corresponding to the Policy Overview – Policies query.
In the same row, select .
The Catalog Item Properties window appears, displaying the properties of the Policy Overview – Policies query.
In the Name box, modify the value to rename the query.
Select Done.
The Policy Overview – Policies query is renamed.
Select the check box corresponding to the alternative query (Policy Overview – Policies Alternate Query).
In the same row, select .
The Catalog Item Properties window appears, displaying the properties of the alternative query.
In the Name box, delete the existing value, and then enter Policy Overview – Policies.
Select Done.
The alternative query is configured for the Policy Designer Overview page.

Configure Multiple APM Servers for Policy Execution

Depending on the number of policies that you need to manage in your system, you may have multiple APM Servers to process policy executions. Based on your company preference for server load balancing, you can configure these servers using global load balancing or isolated load balancing.

Regardless of the approach you use, you must fully configure each APM Server according to the steps for deploying the basic APM system architecture. In addition, each APM Server must be configured to use the same instance of Redis and ActiveMQ.

Global Load Balancing

In global load balancing, you configure all APM Servers to process policy executions in a single load-balanced cluster. In this scenario, an increase in policy execution demand can be absorbed across all servers in your system architecture.

In this scenario, you must:

Configure and start the Policy Trigger Service on at least one APM Server.
Configure and start the Policy Execution Service on all APM Servers.

Isolated Load Balancing

In isolated load balancing, you configure designated APM Server(s) to process policy executions. In this scenario, the policy execution processes are isolated from other APM Server processes, therefore preventing an increase in policy execution activity from negatively impacting other processes.

In this scenario, you must:

Configure and start the Policy Trigger service on at least one APM Server.
Configure and start the Policy Execution Service on only the APM Servers that you want to use to process policy executions.

Configure the SubPolicy Node for Policy Execution

About This Task

If the policies contain recursive sub policies in them, the policy does not execute. If the sub policy nesting is more than 10 levels, the policy does not get executed. This topic describes how to modify the Policy Execution Service configuration to change the recursion limit for policy execution.

Procedure

On the APM Server, access the folder that contains the Policy Execution Service files.

Note: If you have installed APM in the default location, you can locate the folder in the following directory:
C:\Program Files\Meridium\ApplicationServer\policy-execution
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).
In the file, locate the following text:
```
"MaxSubPolicyDepth": 10
```
Replace 10 with the MaxSubPolicyDepth that you want to apply to policy executions.
Save and close the file.
The modified settings are applied when the Policy Execution Service is restarted. If the execution of a sub policy instance exceeds 10, the execution is canceled, and an error message is added to the execution log and execution history.
On the APM Server, access the folder that contains the Meridium configuration files.

Note: If you have installed APM in the default location, you can locate the folder in the following directory:
C:\Program Files\Meridium
Go to C:\Program Files\Meridium\ApplicationServer\api.
Access the appsettings file in an application that can be used to modify JSON files (for example, Notepad++).
Repeat steps 3 through 5.
The modified settings are applied when Meridium Policy Execution service is stopped and restarted on each policy execution server and IIS is reset on the APM Server.

Configure Policy Reference Clean Up Batch Size

About This Task

When policies and policy instances are inserted, modified or deleted, this may result in changes to very large numbers of related records. In order to optimize the performance for the end user, the related record clean-up is completed in batches by a background task. You can configure the batch size and the frequency for this task. The batch size must be less than 1000 in order to avoid database table locks.

Procedure

On the APM Server, access the folder that contains the Policy Execution Service files.

Note: If you have installed APM in the default location, you can locate the folder in C:\Program Files\Meridium\ApplicationServer\policy-execution.
Access the appsettings.json file in an application that can be used to modify JSON files (for example, Notepad++).

In the file, locate the following text:


    "PolicyRefCleanupBatchSize": 500,
    "PolicyRefCleanUpFreqSeconds": 15,

Update the key values as desired.
Save and close the file.
The updated settings will be applied when the Meridium Policy Execution service is stopped and restarted.

About Upgrading Policy Designer and Family Policies

This topic provides some of the significant changes in Policy Designer and Family Policies modules in the current version, along with the impact and action items for each change.

Most of the existing policies, policy instances, policy execution history, family policies, and queries are upgraded automatically. However, due to the complexity of the changes introduced in the current version, some of the records are not upgraded automatically. In that case, errors or warnings appear, and policies and policy instances are deactivated. You must follow the instructions in this document to complete the upgrade.

Deprecation of the MI_ENTITIES table: The number of references to the MI_ENTITIES table in the product cause the table and the number of joins to that table grow very large. To enhance scalability, this dependency has been removed. As a result of this change, Delete Entity, Create Relationship, and Delete Relationship nodes require an additional Family ID or Family Key input.
The upgrade process attempts to automatically upgrade policies and family policies that use these nodes to add the required Family IDs. However, due to the complexity of the changes introduced in the current version, some of these records are not upgraded automatically (for example, policies or family policies that use queries referencing the MI_ENTITIES system table, queries that contain Union statements). In that case, errors or warnings appear, and policies and policy instances are deactivated. If that happens, you must review the upgrade logs, identify the family IDs, and then upgrade the following items:
Deprecation of the CONTENT_GUID field: The Content GUID output has been removed from all applicable policy nodes. In the Policy Instance and Policy Event families, the Content GUID foreign key fields have been replaced with the entity key foreign key fields. Therefore, before you upgrade, you must identify the Policies, Family Policies, and queries that reference Content GUID. After the upgrade, you must verify that they work as expected.
In addition, the Policy has Policy Instance relationship family has been created to relate the Policy and Policy Instance entity families. Similarly, the Policy Instance has Policy Event relationship family has been created to relate the Policy Instance and the Policy Event entity families.
JSON data changes: The JSON data stored in the Instance Mappings field in Policy Instance records includes the family ID in addition to the entity key of the mapped records.
Hyperlinks changes: Some of the hyperlinks in the execution history include the family ID in addition to the entity key of the linked records.
Scheduler changes: The new Scheduler upgrade utility creates scheduled jobs for active scheduled policies. You may be required to recreate schedules for policies that were deactivated during the upgrade.

Note: For a complete list of changes in the Policy Designer and Family Policies modules, refer to the Family Policies and Policy Designer sections of the APM V5.0.0.0.0 Release Notes.

Limitations:

If you import Policies or Family Policies from a previous version, and if they use a Create Relationship, Delete Relationship, or Delete Entity node, you may have to modify the policy model. For instructions, refer to Upgrade Relationship Nodes and Upgrade Delete Entity Nodes.

Similarly, if the Policies or Family Policies that you import use query nodes, you may have to modify the policy model. For instructions, refer to Upgrade Query Nodes.

Note: If you run the post-upgrade utility multiple times, the Upgrade Log will contain multiple conflicting log entries for each policy node. In most cases, this indicates that a policy node was successfully upgraded during the first run of the utility, and no changes were made in subsequent runs.

Access Upgrade Logs

About This Task

Most of the existing policies, policy instances, policy execution history, family policies, and queries are upgraded automatically. The new Scheduler upgrade utility creates scheduled jobs for these active scheduled policies.

However, due to the complexity of the changes introduced in the current version, some of these records are not upgraded automatically (for example, policies or family policies that use queries referencing the MI_ENTITIES system table, queries that contain union statements). In that case, errors or warnings appear, and policies and policy instances are deactivated. If that happens, you must review the upgrade logs to identify the required changes and then manually modify the policy models and queries.

These upgrade logs appear in a new field, Upgrade Log, in the Policy and Family Policy records. This field contains information on the upgrade steps that you have performed, including any errors or warnings.

This topic describes how to access these upgrade logs.

Procedure

Access the Policy or the Family Policy for which you want to review the logs.
Select Upgrade Logs.
The Upgrade Logs workspace appears, displaying the upgrade steps, errors, and warnings, as applicable.

What To Do Next

Resolve any errors in the upgrade logs by modifying the policy model.
As needed, update queries referenced by the policy.
Reactivate each Policy.

About Identifying Family IDs

During the upgrade, one of the following methods is used to identify the family IDs used in a Create Relationship, Delete Relationship, or a Delete Entity node:

If an entity key input to the node is sourced from an input node (for example, an entity node or a Health Indicator node), the family ID is normally identified, and the upgrade will happen automatically, except in the following cases:
- The entity key input is sourced from an entity node where the family is not configured.
- The entity key input is sourced from a Point Value node, where the entity key is defined in a policy instance.
- The family referenced by the node does not exist.
- The family referenced by the node is not licensed in the APM database.
If an entity key input to the node is sourced from a query node, the upgrade process attempts to identify the family ID based on the query definition. This process considers entity key fields (that is, <family ID>.ENTY_KEY) as well as other system fields that contain entity keys of related records, including predecessor and successor key fields for relationships, created or updated by user key fields, site key fields, and so on. This process attempts to ascertain the relevant family ID even if the entity key field is defined in a sub query. However, it is not possible to determine the family ID if the query contains a union (among other reasons).

For Create Relationship and Delete Relationship nodes, if the predecessor family ID cannot be determined, the upgrade process will not attempt to determine the successor family ID. If it is not possible to identify the family IDs to use in a Create Relationship, Delete Relationship, or Delete Entity node, a warning message appears in the Upgrade Log field, and the policy is deactivated. Family policies cannot be deactivated, therefore, only the warning message appears in the Upgrade Log field. You must then review these error messages and manually modify the policy models and queries. For instructions on accessing the upgrade log, refer to Access Upgrade Logs.

To upgrade Create Relationship, Delete Relationship, and Delete Entity nodes where an entity key input is sourced from a Point Value node input in a sub policy, refer to Upgrade Nodes in SubPolicies.

Note: If the entity key input is sourced from a Point Value node where the entity key is defined in the policy instance, the Upgrade Logs field may contain a warning message indicating that the Point Value node is not mapped to any calling policy. The most common use case for this policy instance configuration is to test a sub policy independently from the calling policy. If the family ID can be determined from the calling policy, the sub policy can be successfully upgraded.

Upgrade Baseline Policies

About This Task

If you modified a baseline Policy or Family Policy, after the upgrade, the changes to the Policy or Family Policy are retained. This topic describes how to ensure that the Policy or Family Policy works as expected after the upgrade.

Procedure

Review the upgrade logs to check if the upgrade has failed for the modified baseline Policy or Family Policy.
If there is a warning message in the upgrade log, correct the policy model, and reactivate the Policy.

Note: A Family Policy is not deactivated if upgrade fails; therefore, you need not reactivate it.
If you cannot correct the policy model, revert the Policy or Family Policy to baseline, and then reapply your changes from the previous version.
The baseline Policy or Family Policy is upgraded.

Upgrade Create Relationship and Delete Relationship Nodes

About This Task

For each Create Relationship and Delete Relationship node, the upgrade process attempts to identify the IDs of the predecessor and successor entity families. If, however, the upgrade process fails to identify the predecessor or successor entity families, a warning message is logged, and the Policies are deactivated. This topic describes how to upgrade the nodes in such scenarios.

Note: Family Policies are not deactivated; only a warning message is logged in the upgrade logs in case of a failure.

Procedure

Review the upgrade logs to identify the nodes for which the upgrade has failed.
For each node, modify the policy model to provide any of the following details as applicable.
- If all the records belong to the same family, provide the family ID.
- If all the records do not belong to the same family, provide the family keys of all the associated families.
If applicable, modify the underlying queries in each node.
Reactivate the Policy (not required for a Family Policy).
The Create Relationship and Delete Relationship nodes are upgraded.

Upgrade Delete Entity Nodes

About This Task

For each Delete Entity node, the upgrade process attempts to identify the ID of the family whose records must be deleted. If, however, the upgrade process fails to identify the ID of the family, and the Policies are deactivated. This topic describes how to upgrade the nodes in such scenarios.

Note: Family Policies are not deactivated; only a warning message is logged in the upgrade logs in case of a failure.

Procedure

Review the upgrade logs to identify the nodes for which the upgrade has failed.
For each node, modify the policy model to provide any of the following details as applicable.
- If all the records belong to the same family, provide the family ID.
- If all the records do not belong to the same family, provide the family keys of all the associated families.
- If the families are included in the Asset Hierarchy, provide all Asset Families.
If applicable, modify the underlying queries used in each node.
Reactivate the Policy (not required for a Family Policy).
The Delete Entity nodes are upgraded.

Upgrade Create Relationship, Delete Relationship, and Delete Entity Nodes in Sub Policies

About This Task

If a Create Relationship, Delete Relationship, or a Delete Entity node is used in a Sub Policy, and if entity keys are passed to this node via Point Value nodes representing inputs to the Sub Policy node, the upgrade process attempts to identify the ID of the relevant families from the related query or entity nodes in the calling Policy. This process supports multiple levels of Sub Policies as well.

If, however, the Sub Policy is used by more than one calling Policy, the Create Relationship, Delete Relationship, and Delete Entity nodes in the Sub Policy are upgraded automatically only if all the calling Policies specify entity keys of the same family. If the calling Policies specify entity keys from multiple families, the related node in the Sub Policy is not upgraded; an error message appears in the upgrade log of each calling Policies and Sub Policies, and they are deactivated.

Note: Family Policies are not deactivated; only an error message is logged in the upgrade logs in case of a failure.

Important: The upgrade fails if there is a circular reference between the calling Policies and Sub Policies. In this case, remove the circular reference before the upgrade process is restarted.

This topic describes how to upgrade the nodes in such scenarios.

Procedure

Review the upgrade logs to identify the nodes for which the upgrade has failed.
If there is a circular reference between the calling Policies and Sub Policies, modify the policy model (and queries as applicable).
If the calling Policies specify entity keys from multiple families, modify the policy model to specify the entity keys of the families.
Reactivate the Policy (not required for a Family Policy).
The Create Relationship, Delete Relationship, and Delete Entity nodes in the Sub Policy are upgraded.

Upgrade Policies and Queries Referencing Content GUID Fields

About This Task

The Content GUID system field is no longer supported. As a result, the Policy Designer data model has been modified as follows:

The Content GUID foreign key fields in the Policy Instance and Policy Event families have been replaced with the entity key foreign key fields.
The Policy has Policy Instance relationship family has been created to relate the Policy and Policy Instance entity families. Similarly, the Policy Instance has Policy Event relationship family has been created to relate the Policy Instance and the Policy Event entity families.

During the upgrade, the fields that have been removed are replaced as specified in the following table.


Fields in Previous Versions	Fields in Current Version
[MI_PCYEVENT].[MI_PCYEVENT_POLICY_INST_GUID]	[MI_PCYEVENT].[MI_PCYEVENT_POLICY_INST_KEY]
[MI_POLICY_INST].[MI_POLICY_INST_POLICY_GUID]	[MI_POLICY_INST].[MI_POLICY_INST_POLICY_KEY]
[MI_POLICY_INST].CONTENT_GUID	[MI_POLICY_INST].ENTY_KEY
[MI_POLICY].CONTENT_GUID	[MI_POLICY].ENTY_KEY

If a Create Entity or Edit Entity node is configured to modify one of the fields in the aforementioned table, the node is modified to reference the new field.

Similarly, if the Content GUID output from a predecessor node is used in a policy node, it is replaced with the entity key output of the predecessor node. This will resolve the scenarios where the Content GUID output from an Entity or Current Entity node referencing the Policy or Policy Instance family was used to update a related Policy Instance or Policy Event record, respectively.

Procedure

Before the upgrade, identify the Policies and Family Policies that reference Content GUID, along with queries that reference the fields used in previous versions (as listed in the preceding table).
After the upgrade, verify that all the Policies, Family Policies, and queries work as expected. If not, modify the policy models and queries as needed.

Upgrade Query Nodes

About This Task

If query nodes in Policies and Family Policies use Catalog queries that are no longer valid (for example, queries referencing the MI_ENTITIES system table), during the upgrade, an error message appears in the upgrade log.

In addition, if a query column is referenced from a sub query, the column alias may contain extra quotation marks. During the upgrade, these extra quotation marks are removed from the column alias.

Procedure

Review the upgrade logs to identify the queries for which the upgrade has failed.
For each query, modify the query, and if required, the policy model.
Reactivate the Policy (not required for a Family Policy).
The query nodes are upgraded.

Upgrade Policy Instances

About This Task

The Mappings fields of a Policy Instance defines the APM records and other input values that must be evaluated when the Policy Instance is executed. During the upgrade, family IDs for input nodes that represent APM entity records are specified in the Mappings field.

For example, suppose a Policy contains the following input nodes:

n1: An entity node that references the Equipment family
n2: A Measurement Location node
n5: A Health Indicator node
n6: A Point Value node, which can reference a different family in each Policy Instance
n7: A User node

The following image shows the configuration of these nodes:

The following table describes the Mappings field before and after the upgrade.

Before the Upgrade After the Upgrade

Before the Upgrade	After the Upgrade
[ { "nodeId": null, "entityKey": null, "familyId": null, "fieldId": null, "constant": null }, { "nodeId": "n1", "entityKey": "64262245942", "fieldId": null, "constant": null }, { "nodeId": "n2", "entityKey": "64251802979", "fieldId": null, "constant": null }, { "nodeId": "n4", "entityKey": null, "fieldId": null, "constant": "TS-ASSET-TYPE1.TS-TAG14" }, { "nodeId": "n5", "entityKey": "64251807817", "fieldId": null, "constant": null }, { "nodeId": "n6", "entityKey": "64251874565", "fieldId": "MI_FNCLOC00_FNC_LOC_DESC_C", "constant": null }, { "nodeId": "n7", "entityKey": "64251959752", "fieldId": null, "constant": null } ]	[ { "nodeId": null, "entityKey": null, "familyId": null, "fieldId": null, "constant": null }, { "nodeId": "n1", "entityKey": "64262245942", "familyId": "MI_EQUIP000", "fieldId": null, "constant": null }, { "nodeId": "n2", "entityKey": "64251802979", "familyId": "MI_MEAS_LOC", "fieldId": null, "constant": null }, { "nodeId": "n4", "entityKey": null, "familyId": null, "fieldId": null, "constant": "TS-ASSET-TYPE1.TS-TAG14" }, { "nodeId": "n5", "entityKey": "64251807817", "familyId": "MI_HLTH_IND", "fieldId": null, "constant": null }, { "nodeId": "n6", "entityKey": "64251874565", "familyId": "MI_FNCLOC00", "fieldId": "MI_FNCLOC00_FNC_LOC_DESC_C", "constant": null }, { "nodeId": "n7", "entityKey": "64251959752", "familyId": "MI Security User", "fieldId": null, "constant": null } ]

[
  {
    "nodeId": null,
    "entityKey": null,
    "familyId": null,
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n1",
    "entityKey": "64262245942",
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n2",
    "entityKey": "64251802979",
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n4",
    "entityKey": null,
    "fieldId": null,
    "constant": "TS-ASSET-TYPE1.TS-TAG14"
  },
  {
    "nodeId": "n5",
    "entityKey": "64251807817",
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n6",
    "entityKey": "64251874565",
    "fieldId": "MI_FNCLOC00_FNC_LOC_DESC_C",
    "constant": null
  },
  {
    "nodeId": "n7",
    "entityKey": "64251959752",
    "fieldId": null,
    "constant": null
  }
]

[
  {
    "nodeId": null,
    "entityKey": null,
    "familyId": null,
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n1",
    "entityKey": "64262245942",
    "familyId": "MI_EQUIP000",
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n2",
    "entityKey": "64251802979",
    "familyId": "MI_MEAS_LOC",
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n4",
    "entityKey": null,
    "familyId": null,
    "fieldId": null,
    "constant": "TS-ASSET-TYPE1.TS-TAG14"
  },
  {
    "nodeId": "n5",
    "entityKey": "64251807817",
    "familyId": "MI_HLTH_IND",
    "fieldId": null,
    "constant": null
  },
  {
    "nodeId": "n6",
    "entityKey": "64251874565",
    "familyId": "MI_FNCLOC00",
    "fieldId": "MI_FNCLOC00_FNC_LOC_DESC_C",
    "constant": null
  },
  {
    "nodeId": "n7",
    "entityKey": "64251959752",
    "familyId": "MI Security User",
    "fieldId": null,
    "constant": null
  }
]

If, however, the upgrade process fails to identify the family ID of an input node in the policy model, or the family ID of the record specified in a point value input in the Policy Instance, a warning message appears in the upgrade log, and the Policy Instance is deactivated. This can happen if the family does not exist or it is not licensed.

Note: If the APM system contains Policies, Family Policies, or custom Data Loaders that update the value of the Mappings field in Policy Instance records, you must modify them to add the family ID. For assistance, please contact GE Vernova Support.

This topic describes how to upgrade Policy Instances if the upgrade fails.

Procedure

Review the upgrade logs to identify the Policy Instances for which the upgrade has failed.
For each Policy Instance, modify the policy model or instance to provide the correct family ID.
Reactivate the Policy Instance.
The Policy Instances are upgraded.

About the Policy Execution History Upgrade

About This Task

During the upgrade, the hyperlinks in the policy execution history are now updated to use the family ID of records as applicable. In some cases, the upgrade process fails to identify the family ID. This can happen if the record was deleted or the family is not licensed. This may result in broken links in the policy execution history summary or node-level execution history details.

Note: You cannot correct the broken links.