Concepts

Tasks

Reference

Creating Custom Validation Rules for Attributes

You can use custom validation rules that determine how lists are filtered and to enforce validation on attributes and relationships. For example, you could set up a validation rule to ensure that the hierarchy code for maintainable assets begins with a specific text string.

Rules can be defined using the object model and can take the form of complicated logical expressions. Rules can have conditions that must be met before the rule is applied (similar to an “If... Then” statement).

You can also create custom messages to be displayed when the conditions in the rule are not met. For example, you might create a message that says “The Hierarchy code for maintainable assets must begin with ‘MA’.”.

This topic explains how to create validation rules for attributes. There are five main steps to creating validation rules:

•	Setting up the validation rule

•	Entering conditions for the rule (“If” statement)

•	Entering rule assertions (“Then” statement)

•	Selecting a message to display

•	Testing the rule

Note: Creating validation rules is an advanced customization feature. Adding validation rules may change the flow of your business procedures. Rules must be thoroughly tested to ensure that they produce the expected behavior. This type of customization should only be attempted by advanced administrators with extensive knowledge of the APM object model.

This topic includes a simple example to illustrate the process of creating a validation rule for an attribute. The example creates a rule with one condition and two assertions. The rule ensures that the Hierarchy code for maintainable assets begins with the text “MA”:

If Asset.Classification Is Maintainable Then HierarchyCode Starts with MA.

When created as described, this rule applies to both new and existing assets. Therefore, if you try to save an existing maintainable asset, the system validates the Hierarchy code field and shows an error or warning message if the code does not comply with the rule.

To Create a Validation Rule for an Attribute

1.	From the Site window, click on the tool bar. The Enterprise window appears.

2.	Select the Customization Center view.

3.	Click Lock for Customization. The APM icon in your Task bar now has a key on it:

4.	Open the custom class to which you want to add a custom validation rule.

For this example, open the Asset custom class. If the Asset class is not yet customized, click New Custom Class, then select Based on APM Class, select the Asset class from the MaintenanceManagement system, and click OK. The Class Asset window appears.

Setting up the validation rule

5.	Select the States and Validation view, Validation Rules tab, then the Rules tab.

6.	Click New Rule for an Attribute. The Validation Rule dialog appears.

7.	Select an Attribute to validate. You can select any attribute that is owned by the class that you are customizing.

For this example, select the Hierarchy code attribute.

Entering conditions for the rule (“If” statement)

8.	Create the conditions that the rule must meet. Conditions are optional; you can create a validation rule without any conditions.

To create a new condition, click New. The Validation Rule Condition dialog appears.

9.	Enter the condition type, relationship (if required), and the attribute:

Setting Name

Description

Criterion type

Select whether the condition is based on an attribute or a relationship. If you are basing the condition on an attribute in either the class being customized or a related class, select Attribute. For example, Classification is an attribute of the Asset class. However, if the condition is to be based on the content of a relationship, select the Relationship option. For example, Asset Type (along with other value lists) is a separate class that is related to the Asset class.

Relationship from

The join path used to navigate to either the relationship on which the condition is based or to the related class that owns the attribute on which the condition is based. You can select any relationship that points to a single instance of the related object. This includes the following relationship types only: • References one • Owned by • Scoped by • Hierarchical parent • Contains one For example, to base the condition on an asset’s asset type, you would select the References one AssetType relationship. To select a join path, click . Expand the hierarchy until you see the relationship that you want, select it, and click OK.

Attribute to test

Select the attribute on which the condition is based. You can select any attribute from either the custom class, or the class selected in the Relationship from box. This setting only applies to conditions that are based on an attribute.

For this example, select:

•	Criterion type: Based on an attribute

•	Relationship from Asset: blank

•	Attribute to test: Classification

10.	Select the Type of value to test for:

•	Fixed: Select this option to test the condition based on a specific value that you enter.

For this example, select Fixed, and see Fixed Value Settings.

•

Variable: Select this option to test a condition using a relative value. The value used in the filter is only determined at the time the filter is used by looking up the current value of the selected attribute or relationship. You can use any attribute or relationship that can be reached through a join path starting from the class that you are customizing. A specific value cannot be selected.

For example, you may want to test that Classification attribute of the asset’s parent matches that of the current asset. To do this, you would set the join path to Hierarchy1 (which represents the relationship to the parent asset), and select Classification as the Test value attribute.

To create a variable value filter, see Variable Value Settings.

11.	Select the condition and value to use for the condition:

Fixed Value Settings

Setting Name

Description

Conditional operator

The conditions that are available in the list depend on the data type of the attribute or relationship that is selected. For example, when the attribute is a date and time, the list contains conditions such as Last week, Next week, In the last, and so on.

Test value

Select a Test value for the assertion. If are testing a fixed value, enter or select the specific value that you are testing for.

Variable Value Settings

Setting Name

Description

Conditional operator

The conditions that are available in the list depend on the data type of the attribute or relationship that is selected. For example, when the attribute is a date and time, the list contains conditions such as Last week, Next week, In the last, and so on.

Relationship from class

The join path to the value that you want to test for. This setting applies to variable conditions only. The join path always starts at the class being customized. To select a join path, click . Expand the hierarchy until you see the class that you want, select it, and click OK.

Test value attributes

Select the attribute that contains the value to be tested. For example, if you are testing a value in the Asset class, you might select the Classification attribute. This setting does not apply to fixed filter value types. The list contains attributes that are owned directly by the specified class. However, it only includes attributes that are of the same type as the attribute on which the validation rule is based. For example, if the rule is based on the asset’s Classification attribute, only the Classification attribute will appear in the Test value list.

For this example, select:

•	Type of value: Fixed

•	Conditional operator: Is

•	Test value: Maintainable asset

12.	If you are creating multiple conditions, you can organize them into logical groups in order to use “and/or” logic. To do this, enter the number of the appropriate group for each condition.

For this example, leave the Logical group at its default setting.

13.	Click OK to save the condition.

14.	To enter more conditions, repeat steps 8 to 13.

Entering rule assertions (“Then” statement)

15.	Enter one or more rule assertions. To create a new assertion, click New. The Validation Rule Assertion dialog appears.

The top part of the dialog is filled in with the attribute being validated (as set on your validation rule).

16.	Select the Type of value to test for:

•	Fixed: Select this option to test the condition based on a specific value that you enter.

For this example, select Fixed, and see Fixed Value Settings.

•

Variable: Select this option to test a condition using a relative value. The value used in the filter is only determined at the time the filter is used by looking up the current value of the selected attribute or relationship. You can use any attribute or relationship that can be reached through a join path starting from the class that you are customizing. A specific value cannot be selected.

For example, you may want to test that Classification attribute of the asset’s parent matches that of the current asset. To do this you would set the join path to Hierarchy1 (which represents the relationship to the parent asset), and select Classification as the Test value attribute.

To create a variable value filter, see Variable Value Settings.

17.	Select the condition and value to use for the condition:

Fixed Value Settings

Setting Name

Description

Conditional operator

The conditions that are available in the list depend on the data type of the attribute or relationship that is selected. For example, when the attribute is a date and time, the list contains conditions such as Last week, Next week, In the last, and so on.

Test value

Select a Test value for the assertion. If are testing a fixed value, enter the specific value that you are testing for.

Variable Value Settings

Setting Name

Description

Condition

The conditions that are available in the list depend on the data type of the attribute or relationship that is selected. For example, when the attribute is a date and time, the list contains conditions such as Last week, Next week, In the last, and so on.

Join path from class

The join path to the value that you want to test for. This setting applies to variable conditions only. The join path always starts at the class being customized. To select a join path, click . Expand the hierarchy until you see the class that you want, select it, and click OK.

Test value attributes

Select the attribute that contains the value to be tested. For example, if you are testing a value in the Asset class, you might select the Classification attribute. This setting does not apply to fixed value types. The list contains attributes that are owned directly by the specified class. However, it only includes attributes that are of the same type as the attribute on which the validation rule is based. For example, if the rule is based on the asset’s Classification attribute, only the Classification attribute will appear in the Test value list.

For this example, create an assertion with the following settings:

•	Type of value: Fixed

•	Conditional operator: Starts with

•	Test value: MA

•	Logical group: 1

18.	To save the assertion, click OK.

19.	To create more assertions, repeat steps 15 to 18.

20.	If necessary, you can change the logical operator for the rule condition and assertion groups:

Setting Name

Description

And/Or behavior

If you are grouping items to use “and/or” logic, select the and/or behavior for the groups: • ANDed within a group, ORed between groups: items within the same group are evaluated with ANDs; items in different groups are evaluated with ORs. For example, if A and B are different groups: (A>3 AND A<7) OR (B>7 AND B<10) • ORed within a group, ANDed between groups: items within the same group are evaluated with ORs; items in different groups are evaluated with ANDs. For example, if A and B are different groups: (A=3 OR A=7) AND (B=7 OR B=10)

For this example, leave the defaults.

21.	On the Validation Rule dialog, select the Description tab. This tab shows a text description of the rule. For example:

IF Classification Is Maintainable Asset THEN Mnemonic Is not blank AND Mnemonic Starts with MA

Note: If do not see a description, click Refresh.

22.	You can make notes about the validation rule in the Notes section.

Selecting a message to display

23.	You must select a message to display when the rule is violated. For example, if an employee who is not a planner tries to create an asset that is a component, you might display a warning or error message.

To select a message, on the Rule tab click Browse. The Message Selector dialog appears.

24.	Select a message and click OK. To create a new message, see Creating Custom Messages.

When you are finished creating the rule, it will look similar to the following:

25.	To save the rule, click OK.

Testing the rule

Note: You must perform a thorough test of your rule to ensure that the system behaves as you expected.

26.	To test the rule, save and close the class, unlock the system, and navigate to the object to which the rule applies. Attempt to create conditions that violate the rule and verify that the results are what you expected.

For example, create an asset with a classification of maintainable asset and try to save it with a hierarchy code that does not start with “MA”.