Concepts

Tasks

Reference

Creating Custom Validation Rules for Relationships

You can use custom validation rules that determine how lists are filtered and to enforce validation on attributes and relationships. For example, if you create a custom relationship from Asset to Employee to add a default planner reference, you could set up a validation rule to ensure that only employees who are planners can be selected in this field.

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 create validation rules for the following types of relationships:

•	Referenced by Many

•	References Many

•	Hierarchy Parent

•

Owned By

•	References One

•	Contains One

•

Scopes

•

Scoped By

You cannot create validation rules for these types of relationships:

•	Referenced By

•

Owns Many

•	In Hierarchy Of

Note: Validations for argument classes must be created on the Argument class.

You can select a custom message to be displayed when the conditions in the rule are not met. For example, you might create a message that says “<Employee name> is not a planner”.

This topic explains how to create validation rules for relationships. 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.

The example used in this topic assumes that a custom references-one relationship exists between the Work Request and Warranty classes. To follow along with the example, you should create this relationship first (for more information see Adding a Relationship). The example sets up a validation rule that states:

For Warranties referenced on Work requests, the Duration Is greater than 1.00 month

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 Work Request custom class.

Setting up the Validation Rule

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

6.	Select the By attribute and relationship configuration.

7.	Click New Rule for a Relationship. The Validation Rule dialog appears.

8.	Select a Relationship to validate. You can select any relationship that is owned by the class that you are customizing and that is one of the allowed relationship types.

For this example, select the references one relationship to Warranty (“Applicable warranty”).

9.	Select how the rule is to be used:

Setting Name

Description

Used for validation

If you clear this option, the rule is not used for validation. That is, if the rule is violated, no warning or error message is displayed. When this option is selected, you must select a message to display when the rule is violated.

Used for selection

To use the validation rule to filter a list of items, select this option. If the option is cleared, users will see non-valid items in the list; however, if they select a non-valid item, the rule will be applied (if Used for validation is selected). For example, you might clear this option to allow users to select employees who are not planners, but provide a warning message when this occurs. When this option is selected, you do not need to select a message to display.

For this example, clear Used for validation and select the Used for selection option.

Note: If you want, you can record a reason that you are not using the rule for validation in the Reason not used box.

Entering Conditions for the Rule (“If” statement)

10.	Create the conditions that the rule must meet. You do not need to add conditions; they are optional.

Note: For this example, you do not need to create any conditions. You can skip to step 17.

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

11.	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 • Hierarchy 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.

12.	Select the Type of value to test for:

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

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.

13.	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

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.

14.	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.

15.	Click OK to save the condition.

16.	To create more conditions, repeat steps 10 to 15.

Entering Rule Assertions (“Then” statement)

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

18.	Select the whether the assertion is based on an attribute or based on a relationship. Assertions based on attributes are more common.

For this example, select Attribute.

19.	If necessary, select a join path starting from the class being customized.

20.	Select the Attribute to test. For this example, select Duration.

21.	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.

22.	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 value types 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, enter the following settings:

•	Type of value: Fixed

•	Conditional operator: Is greater than

•	Test value: 1.00 month

•	Logical group: 1

23.	To save the assertion, click OK.

24.	To enter more assertions, repeat steps 17 to 23.

25.	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)

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

Duration Is greater than 1.00 month

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

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

Selecting a Message to Display

28.	On the Rule tab, you can select a message to display when the rule is violated. For example, if a user tries to select an employee who is not a planner, you might display a warning message.

To select a message, select Used for Validation. Click Browse beside the Message to post field. The Message Selector dialog appears.

29.	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:

30.	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.

31.	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 a work request and try selecting a warranty.