Contingent values are a data design feature that allow you to make values in one field dependent upon values in another field. In other words, contingent values are how you define a set of attribute values that are specifically valid in the context of other feature attribute values. For example, a power pole dataset might use contingent values to specify what values are appropriate for poles based on other attributes. The voltage level
for a pole determines what material
values are valid; each material
might have a set of appropriate heights
from which to choose. Contingent values let you define all valid combinations of values for two or more attribute fields within a dataset.
What contingent values look like
You can author contingent values using ArcGIS Pro and save them in a mobile map or scene package, standalone geodatabase, web map, web scene, or feature service.
Contingent values are defined in one or more field groups. A field group is a named collection of attribute fields in your dataset that have contingent values. Each field in a field group must have an associated domain. Contingent values are based on the field's domain and represent a subset of the values the domain defines. See Introduction to attribute domains in the ArcGIS Pro documentation for more information about domains.
For each field group, contingent values define all combinations of appropriate values for the participating fields. The value you provide for each field depends on the type of domain associated with it (coded value or range). You can also provide special values to indicate that any value in the domain is considered valid or that a null value is valid (for fields that accept null values). Note that the any value also includes null.
The following image shows a field group that defines a set of contingent values for power poles. The fields Voltage
, Material
, and Height
use coded value domains for their values, while Diameter
uses a range domain. Poles that have a value of Wood
for the Material
field can have any value for Height
that's in the associated domain (or null
) without violating the contingent values.
Contingent values in ArcGIS Runtime
ArcGIS Runtime provides classes and helper methods for reading contingent value definitions for a dataset and for determining contingent value violations for a specific feature, allowing your ArcGIS Runtime app to incorporate contingent values into editing workflows. You might use drop down lists, for example, to provide the appropriate list of values based on other attributes that have been specified. Your app can also validate against contingent values to find violations before saving edits for a feature.
Contingent values can be read from an
AGSArcGISFeatureTable
. Here are some of the classes used to represent contingent values in ArcGIS Runtime API.
-
AGSContingentValuesDefinition
—Contains all the field groups that define contingent values for the dataset. The contingent values definition is exposed as a property onAGSArcGISFeatureTable
.
-
AGSFieldGroup
—Defines all possible contingent values for a set of fields. The contingent values definition contains a collection of field groups. -
AGSContingency
—Defines a set of contingent values for a field group. -
AGSContingentValue
—A base class that defines a possible value for a field participating in a field group. A contingent value can be one of the following:-
AGSContingentCodedValue
—A value from a coded value domain. -
AGSContingentRangeValue
—Defines a minimum and maximum range of values. -
AGSContingentAnyValue
—Indicates that any value in the field's domain is considered valid (as well asnull
). -
AGSContingentNullValue
—Indicates that anull
value is valid for the field.
-
In addition to these classes, the API provides the following helper methods on
AGSArcGISFeatureTable
. In many cases, these helper methods are all you need to provide contingent value support when editing the table.
-
AGSArcGISFeatureTable.contingentValuesWithFeature()
—Returns contingent values for a provided feature and attribute field. -
AGSArcGISFeatureTable.validateContingencyConstraintsWithFeature()
—Validates a feature against contingent values defined for the dataset.
Edit with contingent values
Contingent values do not enforce data integrity or attribute rules for the data. However, you can design your app to guide the user through an edit workflow where contingent values provide appropriate choices and validation checks before edits are saved. For example, you could enforce ordered steps in your editing workflow to ensure that the current set of values you display for the editor are based on the previous inputs.
Get contingent values
Contingent values are derived from values in an attribute domain for the dataset. Since domains can either be a list of coded values or a range of acceptable numeric values, the same is true for contingent values. Each set of contingent values is defined from a subset of the domain. If your domain for pole diameter defines a range of 6 to 18 inches, for example, any contingent values must be within this range, for example 7 to 10 inches. Likewise, coded value domains define a set of acceptable values and the contingent values must contain a subset of those items.
To get the contingent values for a field, use the
AGSArcGISFeatureTable.contingentValuesWithFeature()
helper method and pass the current feature and the field name. The helper method looks at the current values defined for other attributes of the feature to return a set of the appropriate contingent values for the specified field.
The following code gets all contingent coded values for the specified field based on the other attribute values for the provided feature.
// Store a list of values from the contingent values definition.
var availableValues = [AGSCodedValue]()
// Get all contingent values defined for a specified field name.
// The attribute values of the feature determine which contingent values are returned.
let contingentValuesResult = polesFeatureTable.contingentValues(with: feature, field: "Material")
// Get contingent values for a specified field group.
guard let contingentValues = contingentValuesResult.contingentValuesByFieldGroup["voltage_material"] else {
return
}
// You can use code like this to get contingent values for all field groups if this field participates in more than one.
// let allContingentValues = contingentValuesResult.contingentValuesAllGroups
// Loop through the contingent values and add the coded values to an array.
contingentValues.forEach({ contingentValue in
if let contingentCodedValue = contingentValue as? AGSContingentCodedValue {
availableValues.append(contingentCodedValue.codedValue)
}
})
If the contingent values are from a range domain, you can return the minimum and maximum values for the valid range.
if let contingentRangeValue = contingentValue as? AGSContingentRangeValue {
let rangeTuple = (contingentRangeValue.minValue as? Int, contingentRangeValue.maxValue as? Int)
// ...
}
If an
AGSContingentAnyValue
is defined for the field, you can provide all values from the field's domain as valid edit choices.
// Check for ContingentAnyValue (which means any value in the domain is valid).
if (contingentValue as? AGSContingentAnyValue) != nil {
// Add all values from the field's domain.
if let domain = featureTable.field(forName: fieldName)?.domain as? AGSCodedValueDomain {
availableValues.append(contentsOf: domain.codedValues)
}
}
Validate edits against contingent values
To see if a feature's attribute values conform to the defined contingent values, call the
AGSArcGISFeatureTable.validateContingencyConstraintsWithFeature()
helper method and pass a feature. The method returns a collection of
AGSContingencyConstraintViolation
that you can use to enforce edit restrictions or provide warnings to the user.
Each contingency constraint violation will indicate if it is a warning or an error, and which field group contained the violated contingent value. A violation is considered an error if the field group is marked as restrictive
. A restrictive field group means that edits to any of the participating fields should conform to previously defined contingent values. If a field group is not restrictive
, then a violation alert is considered a warning.
let contingentValueViolations = editFeatureTable.validateContingencyConstraints(with: feature)
// If there are no violations, allow user to save the feature
if contingentValueViolations.isEmpty {
saveFeatureButton.isEnabled = true
return
}
// Loop through contingency violations and show messages for errors and warnings.
// Include the name of the field group that has the violation.
contingentValueViolations.forEach { violation in
// Get the violation type and field group name
let violationType = violation.type == .error ? "Error" : "Warning"
let message = "Contingency value violation for field group \(violation.fieldGroup.name)"
// Display alert to user
let alert = UIAlertController(title: "Violation: \(violationType)", message: message, preferredStyle: .alert)
let ok = UIAlertAction(title: "OK", style: .default, handler: nil)
alert.addAction(ok)
self.present(alert, animated: true, completion: nil)
}