Skip To Content

Attribute rule script expressions

When you create an attribute rule, a script expression is used as the foundation of the rule. The script expression is constructed using Arcade scripting language to control the rule behavior. Expressions can be written to update field values, restrict certain edits, return messages to the user, and much more.

When you're building a script expression, you can use the following dictionary keys during the evaluation of the rule:

  • calculationRequired and validationRequired—Marks other features as requiring evaluation as part of the result. When these keywords are used, the corresponding feature class and array of features are marked as requiring evaluation by modifying the Validation Status attribute for the features. These keywords can only be used with calculation rules and require that the Server Only option to be set to true.
  • result—Signifies a valid return from rule evaluation.
  • errorMessage—Specifies a user-defined error message for a failure during evaluation.

The script expression has Arcade requirements depending on the attribute rule type. Reference the Arcade profile for the requirements for the specific type of attribute rule.

The Arcade Getting Started guide and Function Index can be used as references when constructing script expressions for attribute rules.

Caution:
Adding attribute rules impacts backward compatibility for the dataset.
  • Datasets with attribute rules can no longer be used by ArcGIS Pro releases prior to 2.1 or ArcMap clients.
  • Datasets with attribute rules that use new Arcade functionality are not backward compatible. Reference the ArcGIS Arcade Version matrix and Release notes for more information.

Calculation attribute rule examples

The following are examples of the script expressions for calculation attribute rules.

Return a simple value

An immediate calculation rule is created on the assetid field in the transformer feature class and is triggered on insert edit operations. When you create a transformer, the NextSequenceValue Arcade function queries the database to get the next sequence value and persists this in the assetID field.

return "Tx-" + NextSequenceValue ("assetid")

Return a custom error message

There are some cases when you want a calculation rule to return a custom error message (Failure) when a condition is not met. In this example, an immediate calculation rule is created to populate the (FacilityID) field based on the intersecting substation. The rule will execute on insert and update operations. If you attempt to create a transformer in a substation, the Arcade expression will fetch the name of the substation and use the assetID of the transformer to build the full FacilityID field (SubstationName-AssetID). If the transformer is created or moved outside of a substation, the script returns a custom error message using the errorMessage keyword.

//On Insert or Update set FacilityID = SubstationName - AssetID use intersect to get the substation name
//If no substation (fail with error message dictionary,  must create in substation.) 
var fsStructureBoundary =  FeatureSetByName($datastore, "Substation", ["name"], true)
var fsSubstation = Intersects(fsStructureBoundary, Geometry($feature))
var substation = First (fsSubstation)

var subname  = ""
if (substation == null)
   return  {"errorMessage": "Transformers must be created in a substation."}
else 
   subname =  substation.name

return subname + " - " + $feature.assetid;

Mark other features requiring evaluation

You can author a calculation rule that marks other features as requiring either calculation or validation. After performing a calculation, the calculationRequired or validationRequired keyword can be used in a dictionary to reset the Validation Status attribute for one or more features. In this example, the calculation rule is created on the Substation feature class on the yearName field. When the substation name is updated, the new name and the current year are stored in the yearName field. As part of this logic, all the transformers intersecting the substation in the Transformer feature class are marked as requiring calculation. Another batch calculation rule that is assigned on the Transformer class will recalculate the Transformer new AssetID to pick up the new substation name the next time the rule is evaluated.

//Updating the substation name marks its transformers as requiring calculation and updates the yearName to the new name and year. 
//To recalculate the facility id on all transformers, mark all associated transformers as requiring calculation.
var fsDevice =  FeatureSetByName($datastore, "Transformer", ["globalid"], false)
var fsDeviceIntersects = Intersects (fsDevice, Geometry($feature))

var transformers = [];
var count = 0;

for (var i in fsDeviceIntersects)
   transformers[count++] = i.globalid;
var newName = $feature.name + " " + Year(Now())
return {
   'result': newName, 
   'calculationRequired': 
       [
          {
              'className':"Transformer",
              'globalIDs': transformers
           }
       ]
   }

Constraint attribute rule examples

The following are examples of the script expressions for constraint attribute rules.

Return a Boolean

This constraint attribute rule is created on the substation class and is triggered on insert and update operations. If the substation name is empty, fail (return false) else returns true and allows the edit to proceed.

if ($feature.name == null)
    return false;
else
    return true;

//another way of writing it
return !($feature.name == null)

Return a custom error message

There are some cases where you want to author a script expression that returns multiple error messages in different cases. The following is an example when a custom error is returned if the name or the installationDate for the substation is null.

if ($feature.name == null)
    return   {"errorMessage": "Substation must have a valid name."}
else if ($feature.installationDate == null)
    return   {"errorMessage": "Substation must have a valid installation date."}
else
    return true;

Validation attribute rule examples

The following is an example of the script expression for a validation attribute rule.

Return a Boolean

Validation rules are best for instances when you want to detect corrupt data, but you don't want to prevent the edit operation. You can evaluate rules and create errors for the features that violate your rule. This is an example of substations that exceed the maximum kva and are flagged as errors (polygon errors will be created).

var fsTransformer =  FeatureSetByName($datastore, "L1Electric_Distribution_Device", ["objectid"], true)
var fsTransformerSubset = Intersects(fsTransformer, Geometry($feature))
var totalKva = 0;
for (var t in fsTransformerSubset)
    totalKva += t.kva

if (totalKva > $feature.maxKva)
     return false
else
     return true