Form Data Sources are used for selection based form controls. This includes:
- Select box
- Combo-box (like select box but allowing user-provided values)
- Radio List
- Checkbox List
Data sources may be in the Shared Data sources section, which makes them available to all forms, or they may be defined inline with the form.
Data sources are re-evaluated on each step of the form, so it is possible for a Rule or Query based data source to reference data provided by the user on a previous form step.
When working with combo-boxes it may be necessary to define either an empty data source or a data source that only contains the current values of an attribute. This may be done with the Rule type data source.
The items in a data source will always be alphabetized for presentation to the user.
For large data sources (e.g. over 10 entries), it is preferable to use autocompletes as the Select box is not filterable. and radio or checkbox lists may grow quite long.
All data sources must have a unique name which identifies it to the form engine. If a form defines a data source with the same name as a shared data source, it will not be able to access the shared data source definition.
The available data source types are List, Rule, and Query.
Some of the input types (Autocomplete, Select, Checkbox List, Radio) are able to produce values that differ from what is displayed. This feature may be used with any rule source provided the rule source generates pipe-separated values in the format:
Additionally, the select and autocomplete boxes allow adding a photo or icon avatar to the selection option with the format:
The above formatting may also be generated using the helper function:
text, avatarOpt). If no avatar is required simply omit that argument.
List Data Source
The List data source consists of a simple multi-tagging box to allow creation of a static list of values.
If a large number of values must be entered, it is easier to download the entire Service Panel settings JSON, search the file for the name of the data source, and add the list directly using a capable text editor such as Visual Studio Code or Notepad++.
If a value is wrapped in square braces with no leading or trailing characters it will be treated as a Rule Engine template value executed in the context of the Service form.
Rule Data Source
The rule data source executes a rule in the context of the Service Form to produce a list of values.
The rule data source can be used like the List source by using the List() method. More commonly a Rule Data source will be used to return existing values off a virtual identity, or to convert data entered on one step of a form into a source for a subsequent step. For example:
Query Data Source
The most advanced data source (and also the one with most potential performance impact) is the Query data source. It is used to retrieve options from an Identity Panel data collection. Most commonly it will be used to produce values from simple lookup tables like a database managed list of locations, departments, or job codes.
The query source has two primary parts to it:
The Map Rule is a rule engine rule applied to each object returned by the query. This rule should return a string formatted appropriately for binding to a selection control.
The second part is a Database query. builder with select-able data type and query filters. This query section is identical to that found in the Identity Panel reporting engine, and in MIM DevTest Rule Helper.
The most common query filter rules will be to produce a list from a lookup table.
NOTE: The filter clause of a query source is generally executed in the context of the Service form, which means that attributes from a bound virtual identity, or user data entered earlier on the form may be used to filter data in the query. However, if the filter clause evaluates to null, it will be re-evaluated by the query engine in the context of the query filter itself. For this reason, when using user provided data it is advisable to write the rule as to guarantee a value. This is especially important because Data sources are evaluated with each step of the form, so any field pulled off the form data will be null on the first step.
FirstNotNull(Data.General.location, "won't match")