InventoryManager: Validation Rules And Related Domains
Validation Rules And Related Domains
MobileMap uses business rules to enforce business logic when creating and editing feature data. Esri data models already support some business rules through the data type, domains and nullable status of a field. MobileMap business rules extend the Esri data model by adding support for more complex business logic including validation rules and field relationships.
Validation Rules (Rules) utilize “if/then” logic (e.g., "if a tree has a broken top, a height measurement is required"). Rules implemented by creating records in a specific table named 'Rules' which is included in the feature service used by MobileMap when collecting data. See the Data Model section below for a description of the fields in the Rules table.
Field relationships (Related Domains) restrict choices in one attribute field based on the values selected in a related attribute field (e.g., if Plot Type is 'Variable Radius', Plot Size options should only include variable radius plot sizes and NOT fixed area plot sizes). Related Domains are implemented by creating records in a specific table named 'Related_Domains' which is included in the feature service used by MobileMap when collecting data. See the Data Model section below for a description of the fields in the Rules table.
For a detailed description of rule format, examples, and the full rules data model, please see the Business Logic MobileMap documentation page. For details on how MobileMap handles these business rules when collecting tree and log data please see https://woodlandsg.atlassian.net/wiki/spaces/MD/pages/229833 .
Managing Validation Rules in Inventory Manager
In order to assist with the management of Validation Rules, InventoryManager provides a dedicated interface for creating and editing validation rules. The screenshot below shows this user interface in a typical InventoryManager implementation.
Following the workflow of the user interface above, the process for creating a new validation rule is the following:
Select the layer that the rule should act (required).
In the example above the rule is applied to the Trees table.
Selecting the desired layer from the dropdown list.
Define the criteria that must be met prior to applying the test (optional).
In the example above, the test should only be applied if the field 'Species' has a value equal to 'HWD' for hardwoods. If the 'Species' has a value that is null or not equal to 'HWD', the test portion of the rule will not even be assessed.
Many rules do not require criteria because they should always be true
If a criteria is needed:
Select the field(s) from the field selection box. If more than one field is needed, click on the first field name, then hold CTRL and click on additional field names.
Select the criteria operator from the dropdown list.
Enter the text or number in the value which will be evaluated.
Typically this value is simply typed in with no punctuation (e.g., LP).
When testing if a field or fields have a null value, enter as 'Null' (capitol N, without quotes).
If the value is coming from another field (uncommon), enter in the field within curly brackets { } (e.g., '{Saw_Stopper}' without the quotes.
If the operator is ‘in’ enter multiple values in a comma separated list (e.g., 1,2,3,4). Do not include spaces. Do not add parenthesis around the list.
If the value is a Date, use the Unix time stamp (in milliseconds). For example, if assessing if a date is before Jan 1, 2020 the value would be 1577836800000. To convert between a human-readable date and Unix time stamp see https://www.epochconverter.com/ .
If no criteria is needed because the test should always be applied (see examples 1, 2 and 6 above):
Uncheck the 'Include criteria' checkbox
Define the main rule logic
Select the field(s) from the field selection box. If more than one field is needed, click on the first field name, then hold CTRL and click on additional field names.
Select the criteria operator from the dropdown list.
Enter the text or number in the value which will be evaluated.
Typically this value is simply typed in with no punctuation (e.g., LP).
When testing if a field or fields have a null value, enter as 'Null' (capitol N, without quotes).
If the value is coming from another field (uncommon), enter in the field within curly brackets { } (e.g., '{Saw_Stopper}' without the quotes.
If the operator is ‘in’ enter multiple values in a comma separated list (e.g., 1,2,3,4). Do not include spaces. Do not add parenthesis around the list.
If the value is a Date, use the Unix time stamp (in milliseconds). For example, if assessing if a date is before Jan 1, 2020 the value would be 1577836800000. To convert between a human-readable date and Unix time stamp see https://www.epochconverter.com/ .
Select the error type
Select 'Error' or 'Warning' from the dropdown list
Errors will prevent the user from saving the record (or closing the tree list)
Warnings will be displayed once to the user, then will allow save (and close of tree list)
Enter the error (or warning) message to display to the user
Enter the full message that should be displayed to the user if the features does not pass the validation rule
This should be a short message that will help the user address the problem. It is best to reference field Aliases (rather than field names) so it matches what the user sees on their screen. Providing the expected value helps users enter correct values.
As of January 2023, InventoryManager supports up to 3 criteria for Rules. This allows for more complex business rules and enables a more flexible approach to using multiple Cruise Specs with a single data model. To take advantage of this, your Rules data model will need to be extended by adding additional attribute fields. Please reach out to Woodland Solutions Group for more information regarding upgrading your Rules table to support additional criteria if you believe this would be helpful for your organization.
The image below shows an example of this new capability, in which a Rule is being created that includes three criteria. In this example, the goal is to ensure that pine sawtimber trees are at least 8” DBH if cruising for company A. There is a cruise spec called ‘Spec_A’ and an attribute field for Cruise_Spec at the Stand, Plot and Tree level. This value is set on the Stand, and inherited down to the Plot and Tree, but is hidden on the Tree List. When collecting data in MobileMap and you select the save or back buttons, MobileMap will first assess if the cruise spec is ‘Spec A’, then if the product is sawtimber (coded 'S' in this data model) and finally if the species is a pine species. If it meets all three criteria, it will assess if the DBH is less than 8”. If it is, it will throw an error telling the user that pine sawtimber must be at least 8” for this cruise spec.
Related Domains
Related domains define the relationship between two fields that each use coded value domains to provide a list of allowed values for that field. Related domains restrict the choices in one attribute field based on the values selected in a related attribute field (e.g., if Plot Type is 'Variable Radius', Plot Size options should only include variable radius plot sizes and NOT fixed area plot sizes). To achieve this, a set of related domains records are added to the Related_Domains table. Each Related Domains record lists a value in the second field (target) dropdown list that should be available only if the specified value in the first field (source) dropdown list has been selected. To do this, related domains utilize a source field, source value, target field and target value. If the specified source value is selected for the source field, then the specified target value will be in the dropdown list for the target field.
Managing Related Domains
In order to assist with the management of Related Domains, InventoryManager provides a dedicated interface for creating and editing validation rules. The screenshot below shows this user interface in a typical InventoryManager implementation. Even if your organization is not using InventoryManager to manage your MobileMap data collection, the screenshot below is still helpful to explain the process and inputs for creating and editing Related Domains.
Following the workflow of the user interface above, the process for creating a new Related Domains is the following:
In InventoryManager
Select the layer that the rule should act upon (this will populate the list of available fields for the source and targe fields)
Select the source field (this is the field that should then restrict the values of the target field dropdown list)
Select the source value (this is the value of the source field that will restrict the values of the target field)
Select the target field (this is the field that should be restricted based on the selected source field and value)
Select the target value (this is a value that should be available to users in the dropdown list for the target field when the selected source value is chosen for the selected source field).
Click Add to create the new feature
When editing a record, click the 'Edit' button to the right of that record in the list of related domains, then update the values as described above and finally click 'Update' and review the updated record in the list of related domains.
Note that while the InventoryManager Related Domains user interface includes a Layer, this is not actually stored in the Related_Domains table and is not required when entering manually via ArcMap, ArcGIS Pro, or ArcGIS Online/Portal. This means that once a Related_Domain record has been created and downloaded to MobileMap, it will be applied to ALL layers where both the source and target fields exist, even if that layer is not the same as the layer that was defined in InventoryManager when creating the Related Domains record.
Disabling Validation Rules and Related Domains
MobileMap does not download data that have been deleted from the feature service. This means that if a Validation Rule and Related Domain record are no longer valid, they cannot be simply deleted from the service. In order for MobileMap devices to become aware that a Validation Rule and Related Domain record is not longer valid, it must be set to 'Archived' rather than actually deleted. When MobileMap downloads updated data by pressing the Download button (Actions > Download), it will update that rule to a status of Archived, and will no longer apply the rule when validating features or applying related domains to subset related field dropdown lists.