Concepts

Tasks

Reference

Creating Custom States

You can use custom states to determine how attributes and relationships (data members) and views are displayed in the user interface or to determine the availability of methods. For example, you could use custom states to make an attribute read-only (that is, not editable) under one condition but mandatory under another condition.

Possible state values for attributes and relationships include:

•	Warning: This option generates a warning message when the attribute or relationship violates the condition.

•	Mandatory: This option generates an error message when the attribute or relationship violates the condition.

•	Read-only: By default, attributes and relationships are editable, but you can make them read-only for your condition.

•	Visible - irrelevant: This option is only available for custom attributes and relationships. You cannot set base APM attributes or relationships to visible - irrelevant.

•	Invisible - irrelevant: This option is only available for custom attributes and relationships. You cannot set base APM attributes or relationships to visible - irrelevant.

•	Not visible: This option hides the attribute or relationship under the specified condition.

Note: If you select Read-only or Not visible as states on APM base attributes or relationships, these states are added to any existing states on those data members. For example, if an APM attribute is shipped with a state of Mandatory and you set a custom state of Not visible, the attribute will have both states. This could result in the situation where a field on an object is not filled in (because it is invisible); however, because the field is also mandatory, users will not be able to save the object. This will not result in data corruption; however, it means that you must test your custom states thoroughly before deploying your customizations.

Note: You cannot use custom states to reduce the compulsoriness of APM base attributes and relationships or to make them irrelevant. That is, you cannot downgrade an APM attribute that is normally mandatory to a warning. You will be able to save downgraded states on data members; however, they will not be applied by the system.

Possible state values for methods include:

•

Enabled

•

Toggled

•	Grayed out

•

Hidden

Possible state values for controls include:

•

Visible

•	Not visible

•	Irrelevant

•

Warning

•

Mandatory

•

Read-only

To determine when states are applied, you will create conditions (similar to validation rules). Conditions are defined using the object model.

This topic explains how to set up custom states. There are four main steps to creating states:

•	Create the state group

•	Enter conditions for the state group

•	Select the attributes, relationships, methods, and pages affected by the state group

•	Test your states

Note: Creating custom states is an advanced customization feature. Adding custom states may change the flow of your business procedures. Custom states must be thoroughly tested to ensure that they produce the expected behavior. This type of customization should only be attempted by advanced administrator users with a strong knowledge of the APM object model.

The example used in this topic sets up states for an attribute, relationship, and page whenever an asset has the classification Maintainable.

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.

Create the state group

5.	Select the States and Validation view, States tab, State Groups tab.

6.	Click New. The State Group dialog appears.

Enter conditions for the state group

7.	Create the conditions for the states. To create a new condition, click New. The State Rule Condition dialog appears.

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

Setting Name

Description

Criterion is based on

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.

Controlling attribute

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 is based on: Based on an attribute

•	Relationship from Asset: blank

•	Controlling attribute: Classification

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

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

For this example, select:

•	Type of value: Fixed

•	Conditional operator: Is

•	Test value: Maintainable asset

•	Logical group: 0

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

Your condition will look similar to the following:

12.	Click OK to save the condition.

13.	To create more conditions, repeat steps 7 to 12.

14.	If necessary, you can change the logical operator for the condition 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)

Select the attributes, relationships, methods, and pages affected by the state group

15.	Click Browse. The Browse Object Model dialog appears.

You can select any attribute, relationship, method, or page (tab on a view) owned by the class that you are customizing (for example, the Asset class).

Note: To select an item from a contained class, enter a join path in the Contained class box. A contained class is a class that is related to the current class by a “Contains” type of relationship. For example, the Asset class contains one Manufacturer’s Info.

16.	On the Attributes tab, select one or more attributes. Then, select the appropriate state to assign to the attributes:

•

Warning

•

Mandatory

•

Read-only

•	Visible - irrelevant (only available for custom attributes and relationships)

•	Invisible - irrelevant (only available for custom attributes and relationships)

•	Not visible

For this example, select the Hierarchy code attribute and the Mandatory state.

17.	On the Relationships tab, select one or more relationships. Then, select the appropriate state to assign to the relationships:

•

Warning

•

Mandatory

•

Read-only

•	Visible - irrelevant (only available for custom attributes and relationships)

•	Invisible - irrelevant (only available for custom attributes and relationships)

•	Not visible

For this example, select the Closest warehouse relationship and the Warning state.

18.	On the Methods tab, select one or more methods. By default, selected methods are set to Disabled (grayed out); however, you can change this later if necessary.

19.	On the Controls tab, click the Pages configuration and then select one or more pages. By default, selected pages are set to Not visible; however, you can change this later, if necessary.

20.	Click OK. The selected items are added to the state group.

21.	To edit the state of any item, double-click it. Change the state and click OK.

22.	On the Summary tab, you can view a description of your conditions and the states for each of the items that you selected.

Note: If do not see a description, click Generate Description.

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

23.	To save the state group, click OK.

Test your states

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

24.	To test the states, 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 new asset and try to save it without a hierarchy code or a warehouse.