Configuring Dependent and Controlling Fields

In this Topic

Examples

You can configure a dependent field so that entry is required, allowed, or not allowed based on the value entered in a controlling field. You customize a field to be dependent on another field by modifying the validation rules for the EntityAttribute element in the custom business metadata. Validation rules for the dependent field are modified to add the HasControllingField rule type, along with arguments that identify the controlling field and conditional requirements.

The following arguments are used with the HasControllingField rule type: FieldName, IsEqual, IsNotEqual, IsRequired, and IsAllowed. The FieldName argument identifies the controlling field, while the remaining arguments define conditions. Conditions can be constructed as either IsEqual or IsNotEqual to a null or given value. The result of this comparison makes the dependent field either IsRequired or IsAllowed. If the controlling field is a foreign key lookup, an additional argument of NavFieldName is required (see the Foreign Key Lookup example for more information).

Arguments and values are case sensitive. For boolean fields, use true or false (with no capitalization) as possible values. When multiple fields are used for a comparison, enter the field names separated by a comma with no spaces. A null value is indicated by empty brackets without a space.

A dependent field can have only one controlling field; a controlling field can control many dependent fields. Controlling and dependent fields must be displayed on the same component, and must be on the same entity.

Note: When entry in a dependent field is allowed based on entry in a controlling field and both fields are populated, removing the value from the controlling field also clears the value in the dependent field.

To edit the custom business data, navigate to the Entity Summary for the entity that contains the field you want to modify. Locate the EntityAttribute element for the desired field. Copy the appropriate section from the Base Metadata tab, paste it on the Custom Metadata tab, and modify it as needed. For general information about modifying business metadata and validation rules, see Editing the Business Metadata and Customizing Validation Rules.

Note: Some locations in the system are already configured with field dependencies either through the user interface or the business layer. You cannot configure dependencies through the custom business metadata that conflict with existing dependencies and customizations.

Examples

The following example shows modification of business metadata for the Hours field in the DWRContractor entity. The Hours field is configured to be dependent on the StartTime field. When any value is entered in the StartTime field, entry in the Hours field is required.

<Argument name="FieldName">StartTime</Argument>

</Arguments>

</Rule>

</ValidationRules>

</EntityAttribute>

</ArrayOfEntityAttribute>

The following example shows the same Hours field with a different configuration. In this example, entry in the Hours field is not allowed until a value is entered in the StartTime field.

<Argument name="FieldName">StartTime</Argument>

</Arguments>

</Rule>

</ValidationRules>

</EntityAttribute>

</ArrayOfEntityAttribute>

Multiple Comparison Values

When the controlling field has multiple possible values, such as a field using a code table or a valid values array, you can specify one or more of the values as criteria for the comparison. Multiple values should be separated by commas with no spaces.

The following example shows the AgencyProjectEngineerId field in the Contract entity configured to be dependent on the ManagingOffice field. The ManagingOffice field ValuesArray includes Agency, Local Agency, Consultant. The following shows the AgencyProjectEngineerId field configured to be required when either Agency or Local Agency is selected for the ManagingOffice field.

<Argument name="FieldName">ManagingOffice</Argument>

<Argument name="IsEqual">Agency,Local Agency</Argument>

</Arguments>

</Rule>

</ValidationRules>

</EntityAttribute>

</ArrayOfEntityAttribute>

Mutual Dependency

The following example shows two fields that are dependent on each other. A value can be entered in either the FederalProjectNumber field or the StateProjectNumber field, but not in both.

<Argument name="FieldName">StateProjectNumber</Argument>

</Arguments>

</Rule>

</ValidationRules>

</EntityAttribute>

<Argument name="FieldName">FederalProjectNumber</Argument>

</Arguments>

</Rule>

</ValidationRules>

</EntityAttribute>

</ArrayOfEntityAttribute>

Foreign Key Lookup

If the controlling field is a foreign key lookup, an additional argument of "NavFieldName" is required when configuring the dependent field. To identify whether the controlling field is a foreign key lookup, locate the controlling field in the business metadata. If the EntityAttribute element includes type="key", then the field is a foreign key lookup.

The "NavFieldName" argument requires the seed value for the controlling field, which can be found in the UI or presentation metadata for the component where the field is displayed (see Editing the Presentation Metadata). In the UI metadata, locate the element for the controlling field, and note the Seed="Value". The seed value is the actual field used for the comparison.

For example, to make Consultant Office Location be dependent on the Consultant Office field within a given contract, first check the business metadata for the controlling field, Consultant Office. The business metadata for the Contract entity includes the following element for the Consultant Office field:

The Consultant Office element includes type="key", indicating that the field is a foreign key lookup. To use the Consultant Office field as a controlling field, the "NavFieldName" argument and seed value are required.

The following UI metadata for the ContractSummaryAdditionalComponent identifies the seed value for the Consultant Office field as "ConsultantOffice.Name":

To use the Consultant Office field as a controlling field, edit the business metadata for the dependent field in the Contract entity, similar to the following:

<Argument name="FieldName">ConsultantOfficeId</Argument>

<Argument name="NavFieldName">ConsultantOffice.Name</Argument>

</Arguments>

</Rule>

</ValidationRules>

</EntityAttribute>

</ArrayOfEntityAttribute>

In the example above, entry in the Consulting Office Location field is required when the Consulting Office field contains a value.