Manage references in steppers

Reference selection

When a form step contains reference fields, you can configure how these references are selected using one of two components:

  • An auto-complete field that lists selectable records filtered by a search expression as you type.

  • A reference selection dialog that displays a collection of selectable records. This option offers a detailed view of the records to select.

Auto-complete fields fetch records based on the search expression you type. To limit the number of fetched records, configure the Autocomplete Max Results property in the global applications configuration.

To configure reference selection:

  1. In the Stepper editor, scroll down to the Steps tree table.

  2. Select the form step containing the references.

  3. In the Properties view, select the Reference Selection finger tab.
    This tab displays a table of references managed in the step.

  4. Click the Refresh references Refresh References button in the table toolbar to update the list with new references.

  5. Configure the reference settings:

    • Picker Filter: restricts selection options for both the auto-complete field and reference selection dialog. For instance, when selecting a Customer entity that is referenced by a Contact entity, it can filter the results to display only those customers located in the same country as the contact’s information.

    • Reference Picker Type: choose one of the available options:

      • None if no reference should be selectable.

      • Auto-Complete to display an auto-complete component for selecting the reference.

      • Collection to display the list of selectable records in a reference selection dialog.

    • Sort Expression: orders data in the selectable records.

  6. (Optional) If you selected the Collection reference picker type, configure these additional options:

    • Picker Collection View: select the collection to display selectable records in the reference selection dialog.

    • Search Configurations: select this checkbox to choose and arrange search methods for an optional search step that appears before the collection of selectable records. If no search method is marked as Available, this search step will not be displayed.

    • User-Defined Sort: select this checkbox to allow users to customize the sorting in the reference selection dialog.

The picker filter allows creating functional dependencies between fields, ensuring only relevant options are displayed based on previous selections. However, picker filters are not applied during mass updates.

Example

When creating a product, users must specify a Family entity followed by a SubFamily entity, both of which are references. In the stepper definition, you can apply the picker filter to display only the subfamilies associated with the selected family. However, when mass-updating records that belong to multiple families, all available subfamilies will be shown.

Many-to-many relationship creation

When a collection step targets a child entity representing a many-to-many relationship (where multiple records in one entity can relate to multiple records in another entity), you can configure the selection of records from the related entity on the opposite side of the relationship.

Example

A ProductStepper stepper includes a child collection step that enables users to create ProductMarkets records. The ProductMarket entity represents the many-to-many relationship between Products and Markets. When users create ProductMarkets records, they are actually selecting specific markets to associate with the products, allowing for the creation of those relationships. This configuration provides users with the ability to perform this task effectively.

To configure many-to-many relationship creation:

  1. In the Stepper editor, scroll down to the Steps tree table.

  2. Select the collection step that manages an entity representing the many-to-many relationship.

  3. In the Properties view, select the Many-to-Many Relationship finger tab.

  4. Select the Many-to-Many Relationship checkbox and configure the many-to-many relationship creation options:

    • Target Foreign Attribute: select the foreign attribute representing the counterpart in the many-to-many relationship.

    • Picker Collection View: select the collection to use for displaying the selectable records on the opposite side of the many-to-many relationship.

    • Picker Filter: set a SemQL condition for pre-filtering the selectable records on the opposite side of the many-to-many relationship.

    • Search Configurations: choose the search type for filtering the selectable records on the opposite side of the many-to-many relationship.

    • Customized Sort: select this option to sort the selectable records according to the sort expression.

    • Sort Expression: apply a sort expression applied to the data in the selectable records.

    • User-Defined Sort: select this checkbox to allow users to customize the sort expression.

    • Default Display Type: set the default view type for the collection that displays the selectable records.

    • Allow Table, Allow List, Allow Grid: select available views for the collection. The selected view must be supported by the chosen picker collection.