MobileMap: Business Logic
- Tyler Bax
- Jessica Burton Desrocher
- Nathan Meade
Overview
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.
ValidationRules (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.
Validation Rules
Validation Rule Examples
Rules use a very flexible format to support a wide range of validation tests. With this flexibility, however, comes complexity. To help understand the general format of MobileMap rules, consider the following examples that can be supported via Rules:
The field 'DBH' cannot have a value greater than '40'
The field 'Net Acres' cannot have a value greater than the field 'Gross Acres'
If the field 'Tree Type' has a value equal to 'Overstory', then the field 'DBH' cannot have a value less than '5'
If the field 'Component' has the value 'Live', then the field 'Snag Class' cannot have a value that is not equal to Null
If the fields 'DBH' and 'Height' both have a value not equal to 'Null', then the field 'Tally Measure' cannot have a value equal to 'T'
The field 'DBH' cannot have a value greater than '20'; If it does, warn the user but don't prevent saving the feature
The field ‘Plot Size’ on the Plot does not match the field ‘Plot Size’ on the Stand.*
Validation Rule Structure
At the highest level, Rules are broken into 3 main parts - the criteria, comparison and the test. If the criteria is met, then the test is applied. In examples 1 and 2 above, there are no criteria and the tests are always applied. The comparison phrase in all of the examples above is 'cannot have a value'. If the test passes (is true), then the validation fails due to this comparison phrase.
In example 3, the test is whether the value in the field 'Tree Type' is 'Overstory'. If the criteria is met (because value of the 'Tree Type' field is set to 'Overstory'), then the test is applied, and the DBH is assessed to determine if it is less than 5. If the test passes (because the DBH value is less than 5) then the comparison is applied. Since the comparison is 'cannot have a value', then the validation rule fails. This validation rule is an error (not a warning like in example 6), thus the user must fix this record before it can be saved.
The table below breaks down each of the six examples above into their component criteria, comparisons and the tests:
Rule | Criteria Field | Criteria Operator | Criteria Value | Test Field | Test Operator | Test Value | Comparison | Error Type | |
|---|---|---|---|---|---|---|---|---|---|
| 1 | The field 'DBH' cannot have a value greater than '40' | NA | NA | NA | DBH | > | 40 | != | Error |
| 2 | The field 'Net Acres' cannot have a value greater than the field 'Gross Acres' | NA | NA | NA | Net Acres | > | Gross_Acres | != | Error |
| 3 | If the field 'Tree Type' has a value equal to 'Overstory', then the field 'DBH' cannot have a value less than '5' | Tree_Type | = | Overstory | DBH | < | 5 | != | Error |
| 4 | If the field 'Component' has the value 'Live', then the field 'Snag Class' cannot have a value that is not equal to Null | Component | = | Live | Snag Class | != | Null | != | Error |
| 5 | If the fields 'DBH' and 'Height' both have a value not equal to 'Null', then the field 'Tally Measure' cannot have a value equal to 'T' | DBH, Height | != | Null | Tally_Measure | = | T | != | Error |
| 6 | The field 'DBH' cannot have a value greater than '20'; If it does warn the user but don't prevent saving the feature | NA | NA | NA | DBH | > | 20 | != | Warning |
| 7 | The field ‘Plot Size’ on the Plot does not match the field ‘Plot Size' on the Stand. | NA | NA | NA | Plot_Size | != | {Stands.Plot_Size} | != | Warning |
*This validation rule compares a value on the child to a value on the parent. This rule needs to be modified in AGO/ArcPro/Portal in order to add the {parentlayer.field}. Currently, MobileMap only supports a single criteria validation. Tip: Create the rule in the InventoryManager user interface and then modify it.
Managing Validation Rules
In order to assist with the mangement 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. Even if your organization is not using InventoryManager to manage your MobileMap data collection, screenshot below is still helpful to explain the process and inputs for creating and editing validation rules via ArcMap, ArcGIS Online, or ArcGIS Pro.
Following the workflow of the user interface above, the process for creating a new validation rule is the following:
If using InventoryManager:
Select the layer that the rule should act upon
Click on the desried layer in the dropdown list.
Define the criteria that must be met prior to applying the test. In the example above, the test should only be applied if the field 'Contract_or_State' has a value equal to 'Contract'. If the field 'Contract_or_State' is null or has a value that is not equal to 'Contract', the test portion of the rule will not even be assessed.
If a criteria is needed:
Enter the criteria value
Enter the text or number in the input. If the criteria value is null, enter as 'Null' (without quotes). If the value is coming from a field, enter in the field within curly brackets { } (e.g., '{Contract_or_State}' without the quotes
Select the criteria operator
Click on the desried operator in the dropdown list.
Select the criteria field.
Click on the field name in the selection box. If more than one field is needed, click on the first field name, then hold CTRL and click on additional field names
If no criteria is needed because the test should always be applied (see examples 1, 2 and 6 above):
Uncheck the 'Include criteria' checkbox
Select the test inputs
Select the test field.
Click on the field name in the 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 test operator
Click on the desried operator in the dropdown list.
Select the error type
Select 'Error' or 'Warning' from the dropdown 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
If using table capabilities of ArcMap, ArcGIS Pro, or ArcGIS Online. Example rule: If the field 'Tree Type' has a value equal to 'Overstory', then the field 'DBH' cannot have a value less than '5'
Generate a table named Rules using either ArcMap, ArcGIS Pro, ArcGIS Online. See the image below for the full data model of the Rules table. WSG can provide a sample File Geodatabase with this data model upon request. Each row in the table defines one rule. "LEFT" inputs, aggregators, and operators correspond to the criteria portion of the rule. "RIGHT" inputs, aggregators, and operators correspond to the test portion of the rule. The "MAIN_OPERATOR" corresponds to the comparison portion of the rule.
Define the criteria that must be met prior to applying the test by attributing the "LEFT" attributes of the Rules table. In the example above, the test should only be applied if the field 'Tree Type' has a value equal to 'Overstory'. If the field 'Tree Type' is null or has a value that is not equal to 'Overstory', the test portion of the rule will not be assessed.
If a criteria is needed:
LEFT_INPUT1 - Enter field name within curly brackets { } (e.g., '{Tree_Type}' without the quotes. If more than one field is needed, separate the field names using comas (e.g., '{DBH},{Height}' without the quotes).
LEFT_AGGREGATOR1 - Enter 'Value' in this field if one field is used as the LEFT_INPUT1 field. Other options include 'Sum' to sum the values in multiple fields listed in the LEFT_INPUT1 field.
LEFT_OPERATOR - Enter the appropriate operator (=, !=, >,>=, <,<=)
LEFT_INPUT2 - Enter the text or number in the input. If the criteria value is null, enter as 'Null' (without quotes). If the value is coming from a field, enter in the field within curly brackets { } (e.g., '{Overstory}' without the quotes
LEFT_AGGREGATOR2 - Enter 'Value' if one field or a number or a text is used as the LEFT_INPUT2 field.
If no criteria is needed because the test should always be applied (see examples 1, 2 and 6 above):
LEFT_INPUT1 - Enter '1'
LEFT_AGGREGATOR1 - Enter 'Value'
LEFT_OPERATOR - Select '='
LEFT_INPUT2 - Enter '1'
LEFT_AGGREGATOR2 - Enter 'Value'
Select the test inputs
RIGHT_INPUT1 - Enter the field name within curly brackets { } (e.g., '{DBH}' without the quotes). If more than one field is needed, separate the field names using comas (e.g., '{DBH},{Height}' without the quotes).
RIGHT_AGGREGATOR1 - Enter 'Value' from the dropdown list for the field or 'Sum' if multiple fields are listed.
RIGHT_OPERATOR - Enter the appropriate operator (=, !=, >,>=, <,<=)
RIGHT_INPUT2 - Enter the text or number in the input. If the criteria value is null, enter as 'Null' (without quotes). If the value is coming from a field, enter in the field within curly brackets { } (e.g., '{DBH}' without the quotes
RIGHT_AGGREGATOR2 - Enter 'Value' from the dropdown list for the field or 'Sum' if multiple fields are listed.
Select the Comparison
MAIN_OPERATOR - Enter '!='
Select the error type
ERROR_TYPE - Enter 'Error' or 'Warning' from the dropdown list
Enter the error (or warning) message to display to the user
ERROR_MESSAGE - Enter the full message that should be displayed to the user if the features does not pass the validation rule
Example rule: If the field 'Tree Type' has a value equal to 'Overstory', then the field 'DBH' cannot have a value less than '5'
Criteria
LEFT_INPUT1 | LEFT_AGGREGATOR1 | LEFT_OPERATOR | LEFT_INPUT2 | LEFT_AGGREGATOR2 |
|---|---|---|---|---|
{Tree_Type} | Value | = | {Overstory} | Value |
Test
RIGHT_INPUT1 | RIGHT_AGGREGATOR1 | RIGHT_OPERATOR | RIGHT_INPUT2 | RIGHT_AGGREGATOR2 |
|---|---|---|---|---|
{DBH} | Value | < | 5 | Value |
Comparision and Error Type
MAIN_OPERATOR | ERROR_TYPE | ERROR_MESSAGE |
|---|---|---|
!= | Error | Overstory trees cannot have a DBH less than 5 |
Complete Rules Data Model
The full data model for the Rules table is shown in the image below. can provide a sample File Geodatabase with this data model upon request.
Testing Validation Rules
Validation rules currently only apply to MobileMap. They have not yet been implemented in InventoryManager. To test your validation rules, therefore, download them to MobileMap using the standard approach (Actions > Download). Make sure to review the download results and verify that new Rules records were downloaded. Next, collect (or edit) data using the layers for which the rules were created. For example, if a new business rule was created that is a warning for trees with DBH greater than 30”, open up a plot for editing, open up the tree list, and attempt to enter and save a tree with a DBH of 35. You should see a popup message with the error. In the case of a warning, you will still be able to save and close the tree list. All errors (and warnings) that are triggered by Validation Rules (rather than domain errors) will include the phrase ‘(business rule)’ to indicate that this error is not due to a coded value or range domain error, but rather a validation rule.
Related Domains
Overview
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:
If using 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 soure 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.
If using table capabilities of ArcMap, ArcGIS Pro, or ArcGIS Online/Portal:
Enter the source field name (this is the field that should then restrict the values of the target field dropdown list)
Enter the code (NOT description) for the source value (this is the value of the source field that will restrict the values of the target field)
Enter the target field (this is the field that should be restricted based on the selected source field and value)
Enter the code (NOT description) for the target value (this is the value that should be available to users in the dropdown list for the target field when the selected soure value is chosen for the selected source field).
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 enterying 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 targe fields exist, even if that layer is not the same as the layer that was defined in InventoryManager when creating the Related Domains record.
Related Domains Data Model
The full data model for the Related_Domains table is shown in the image below. WSG can provide a sample File Geodatabase with this data model upon request.
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.