Family Policy Examples

Policy Model Basic Principles

A policy model is made up of nodes and connections that define the policy logic. In order to build a functioning policy model, you must understand several basic principles.

Configuring a Policy Model

The following principles apply to working with a policy model:

Policy models do not reference specific records. Rather, they contain nodes that reference families. You must use policy instances to identify the individual records whose values are evaluated when the policy is executed.
The initial nodes in a policy model, that is, nodes with no predecessors, must be Input nodes other than Query nodes.
A family policy must contain one Current Entity node for entity families, or one Current Relationship node for relationship families.
A node can use an input from any predecessor node in the same logic path, even if the nodes are not directly connected.
Any number of nodes can use an input from the same predecessor node.
With the exception of the Or node and the Case node, a node will be executed only when all necessary preceding nodes have been successfully executed.
A policy model can often be arranged in various configurations without impacting the execution results. You may want to arrange the policy model in the configuration that provides the best visual representation of the policy.
Connections that start at a Condition or Logic node can be configured to create separate logic paths in a policy model. Specifically:
- If the connection property is Yes, the corresponding path will be followed when the logical result of the Condition of Logic node is yes. If you do not configure a logic path for a connection, a Yes path is assumed but does not appear on the model.
- If the connection property is No, the corresponding path will be followed when the logical result of the Condition or Logic node is no.

Configuring Node Properties

Most nodes have outputs that successor nodes can use as inputs. You must specify inputs for each successor node using the Properties window that appears when you select the node in the policy model.
Note: Outputs and inputs may represent either a single value or a collection of values. The types of outputs that each node generates and the types of inputs that each node accepts is different for each node. When building a policy model, you must use corresponding input and output types.
Any numeric values entered in Calculation nodes should be entered in the format matching the user's culture setting. For example, a user with German culture would enter 4,5 to represent four and a half, whereas a user with US-English culture would enter 4.5.
There are specific formats in which you can enter dates and times and amounts of time (that is, time spans). Refer to the respective topics for details.
When using a policy node to update values in a record:
- If a field has complex behavior defined by field-level rules (for example, rules for valid values) and field-level behaviors, this behavior will not be reflected in the Properties window or detected by policy validation. Therefore, you are responsible for ensuring that the values you specify are valid according to any baseline or custom field-level rules for the corresponding field.
- If a field value is defined by a system code, the value that you specify in the corresponding section must be the system code, not the value that is displayed to the end user.

Policy Model Principles Illustrated

The principles for working with a policy model can be illustrated through the following example model:

In this example model, the node named Temperature is an OT Connect Tag node which represents a process historian tag. When this policy is executed, if the Latest Reading Value that is associated with the process historian tag is greater than or equal to 200, the APM system will send an email message to the email address that is specified in the Human Resource record that is associated with the Analyst User node.

The following table describes each of the policy model basic principles in the context of this example:


Policy Model Principle	Example
Policy models do not reference specific records. Rather, they contain nodes that reference families. You must use policy instances to identify the individual records whose values are evaluated when the policy is executed.	The Temperature and Analyst nodes represent families. The specific records whose values are evaluated are determined by policy instances.
The initial nodes in a policy model, that is, nodes with no predecessors, must be Input nodes other than Query nodes. A family policy must contain one Current Entity node for entity families, or one Current Relationship node for relationship families.	The Reading in Error node is a Current Entity node, which is a type of Input node. The Current Entity node is required for an entity family policy.
Most nodes have outputs that successor nodes can use as inputs. You must specify inputs for each successor node using the Properties window that appears when you select the node in the policy model. Note: Outputs and inputs may represent either a single value or a collection of values. The types of outputs that each node generates and the types of inputs that each node accepts is different for each node. When building a policy model, you must use corresponding input and output types.	The output Latest Reading Value from the Temperature node is used as an input to the Condition node. This output represents a single value, which corresponds to the type of input that the Condition node accepts. The value 200 is used as the second input to the Condition node, but it is not an output from another node. Instead, it is a constant value that is specified directly in the Properties window for the Condition node.
A node can use an input from any predecessor node in the same logic path, even if the nodes are not directly connected.	The Email Contact node can use an input from the Temperature node even though the two nodes are not directly connected.
Any number of nodes can use an input from the same predecessor node.	The Email Contact node and the Condition node can both use inputs from the Temperature node.
With the exception of the Or node and the Case node, a node will be executed only when all necessary preceding nodes have been successfully executed.	The Email Contact node will be executed only when all of the nodes preceding it have been successfully executed. If, for example, the condition defined in the Condition node was not met or if an error occurred when executing the Analyst node, the Email Contact node would not be executed.
A policy model can often be arranged in various configurations without impacting the execution results. You may want to arrange the policy model in the configuration that provides the best visual representation of the policy.	The execution results of the policy would be identical even if the Analyst node were connected to the Temperature node or the Condition node. The current configuration, however, provides a clear visual representation of the policy because the Email Contact node is the only node in the model that uses an input value from the Analyst node.
Connections that start at a Condition or Logic node can be configured to create separate logic paths in a policy model. Specifically: If the connection property is Yes, the corresponding path will be followed when the logical result of the Condition of Logic node is yes. If you do not configure a logic path for a connection, a Yes path is assumed but does not appear on the model. If the connection property is No, the corresponding path will be followed when the logical result of the Condition or Logic node is no.	A property is not defined for the connection between the Condition node and the Email Contact node, therefore, a value of Yes is assumed. This means that an email message is sent only if the preceding condition is true. If the condition is false, policy execution will not continue.

Family Policy Examples

You can use family policies to accomplish tasks in a wide variety of scenarios. These examples illustrate a few of these scenarios.

Tip: Refer to the Policy Designer documentation for additional policy examples.

Sending an Email When a Reading in Error Record is Created

In the Rounds application, a Reading in Error is created when a new Reading record cannot be linked successfully to a Measurement Location during the process of uploading the reading from a mobile device. Suppose that you want to be alerted every time that a Reading in Error record is created in the database so that you can immediately address the issue. You could create family policy for the Reading in Error family that would be executed every time a new Reading in Error record is created.

Policy Model:
Policy Logic Summary:
This family policy is configured for the Reading in Error family using the After Insert trigger. If a Reading in Error record is added to the database with a comment other than test, an email message will be sent to the responsible user.

Individual Node Descriptions:


Node Name	Node Type	Description
Reading in Error	Current Entity	Represents the Reading in Error record that triggered the policy. Values associated with this record are evaluated by the policy.
Comment not equal to test	Comparison	Determines whether the value in the Comment field of the new Reading in Error record contains the value test. If it does not, the policy logic continues (i.e., an email message will be sent).
Email Contact	Email Contact	Represents an action to send an email message. The email message will be sent to the email address defined in the Properties window for the Email Contact node.

Monitoring Work History Records

Suppose that the Work History records you use in APM are imported from an external Enterprise Asset Management system on a regular schedule. Changes made to the Work History records in the external system may require action within APM. This example family policy, which is triggered before a Work History record is updated in the APM database, uses the Field Value Changing node to determine what actions should be taken based on whether the value of certain fields is being changed by the transaction.

Policy Model:
Policy Logic Summary:

This family policy is configured for the Work History family using the Before Update trigger. This policy is designed to take two distinct actions. The first action is to check whether the Equipment ID specified in a Work History record is changing. If it is changing, the existing relationship between the Work History record and the Equipment record is deleted and a new relationship is created between the Work History record and the newly specified Equipment record.

The second action is to check whether the Request System Status code specified in the Work History record is changing. If it is changing, and the new value is TECO (i.e., technically completed), the status of any related recommendations is set to Implemented. This automates the process of reconciling completed work with the recommendation that originated the work request.

Individual Node Descriptions:


Node Name	Node Type	Description
Current Entity	Current Entity	Represents the Work History record that triggers the policy. Values associated with this record are evaluated by the policy.
Equipment	Field Value Changing	Identifies whether the Equipment ID specified in the Work History record is changing.
Query Original Equip Enty Key	Query	Returns the record whose Equipment ID was previously specified in the Work History record.
Delete Has Work History Relationship	Delete Relationship	Deletes the existing relationship between the Work History record and the previously specified Equipment record.
Query New Equip Enty Key	Query	Returns the record whose Equipment ID is now specified in the Work History record.
Create Has Work History Relationship	Create Relationship	Creates a new relationship between the Work History record and the newly specified Equipment record.
Request System Status	Field Value Changing	Identifies whether the value in the Request System Status field in the Work History record is changing.
Request System Status = TECO	Comparison	Determines whether the new value in the Request System Status field contains the value TECO. If it does, the policy logic continues.
Query Related Rec	Query	Returns recommendations whose value in the Work Request Reference field matches the value in the Request ID field of the Work History record.
Edit Entity	Edit Entity	Updates the returned Recommendation records to change the recommendation status to Implemented.