Search forms

Search forms are used to filter data in business views or search for records using the global search feature.

A search form exposes several search parameters to look for records in an entity. When a user submits the search form, a search query is issued, using these parameters as binding values.

Create search forms

To create a search form:

  1. Right-click the Search Forms node under an entity and select Add Search Form….
    The Create New Search Form wizard opens.

  2. In the wizard, enter the following values:

    • Name: internal name of the object.

    • Label: user-friendly label in this search form.

    • Description: description of this search form.

  3. Click Finish to close the wizard.
    The Search Form editor opens.

  4. Define a Search Tip text that will be displayed in the search form.

  5. Add a search parameter:

    1. In the Search Parameters table, click the Add Search Parameter button.
      The Create New Search Parameter wizard opens.

    2. In the wizard, enter the following values:

      • Name: internal name of the object.

      • Binding: binding string used in the search form SemQL query condition to refer to this parameter. Note that, as the Auto Fill checkbox is selected, the field is automatically filled in and can be modified.

      • Label: user-friendly label for this search parameter. Note that, as the Auto Fill checkbox is selected, the field is automatically filled in and can be modified.

      • Use Type, Length, Scale, and Precision to define the logical datatype of this parameter.

    3. Click Finish to close the wizard.
      The parameter appears in the Search Parameters table.

      • To edit a search parameter: select the Properties view and then select the search parameter in the table. The Properties view shows all its properties, including the Name and Definition, as well as the search parameter display properties.

      • To remove a search parameter, select the search parameter in the search parameters table, click the Delete button, and then confirm the deletion.

    4. Use the Properties view to configure the search parameter.

  6. Repeat the previous step to create all your search parameters.

  7. Reorder search parameters in the table using the Move Up and Move Down buttons.

  8. Click the Edit expression Edit Expression button to open the SemQL editor and create a SemQL condition for the search query. Note that the SemQL editor displays the search form parameters bindings in the Variables section.

    Protecting sensitive data in URLs

    When attribute values appear as clear text in URLs, sensitive data—​such as social security numbers, bank account details, or tax identification numbers—​can be exposed in browser and server logs. To avoid this security risk and protect sensitive information from unauthorized exposure, model designers should:

    • Avoid using sensitive data in search forms. Do not include sensitive data in query parameters for global search or business view filtering.

    • Avoid using sensitive data as record IDs. Use non-sensitive unique identifiers instead.

    • Avoid allowing advanced searches on business views involving sensitive data. Prevent end-users from searching using sensitive data in advanced mode.
New search forms designed for an entity are not immediately available in the business views or MDM applications using that entity. You must define a Search Configuration in a business view to enable or disable both the built-in search types and your search forms.

Search parameters display properties

The display type of a search parameter defines the component used to display this parameter in the search form. A display type is optionally configured through display properties.

The display type available for a search parameter depends on its logical datatype. For example, the date picker display type is available only for a datetime search parameter.

The display types are listed below with their properties:

  • Text Field: simple text field. This type is available for all logical data types.

  • Checkbox: simple checkbox. This type is available for the boolean logical datatype. Its default value is null.

  • Date Picker: date (and time, for a timestamp datatype) selector. This display type is available for the date and timestamp logical types.

  • Drop Down List: selectable list of elements. This display type is typically used to select a search parameter value from a list of values. It is configured using the following options:

    • Display Format: defines whether the label or code of the list of values should be displayed.

    • Sort Order: defines if the list of values should be sorted by the code or label.

  • Value Picker: auto-complete component used to select filtered values from a given entity of the model. It is configured using the following options:

    • Lookup Entity: entity from which the values are selected.

    • Filter Expression: SemQL expression used to filter the entity data. This expression can use other search parameters' values.

    • Bound Select Expression: SemQL expression defining the value returned by a value picker selection.

    • Primary Text Expression: SemQL expression defining the value displayed in the auto-complete items' first line.

    • Secondary Text Expression: SemQL expression defining the value displayed in the auto-complete items' second line.

    • Use Distinct: select this option to only display distinct values in the auto-complete component.

    • Display Count: select this option to display the count of records for each distinct value in the auto-complete. This option is available if Use Distinct is selected

    • Sort By Count: if Display Count is selected, this option allows sorting by ascending or descending record count. Note that if a value matches exactly the user input, it always appears first in the list.

    • Default Sort Expression: if Use Distinct is not selected, this SemQL expression defines the sort order of the records in the auto-complete. Note that if a value matches exactly the user input, it always appears first in the list.

Search form SemQL conditions

The SemQL condition defined for the search form can use attributes from the search entity as well as attributes from related (parent or child) entities. Refer to a search parameter with its binding prefixed by a colon (:).

Example

Consider a search form on the Customer entity with one parameter labeled Searched Name (binding: SEARCHED_NAME). The following SemQL condition filters customers by their name:

CustomerName like '%' || :SEARCHED_NAME ||  '%'

When adding a second parameter labeled Has Influencer Contact (binding: HAS_INFLUENCER_CONTACT) to this form, the following SemQL condition filters customers by their name and, possibly, whether they have one or more contacts with IsInfluencer = 1.

CustomerName like '%' || :SEARCHED_NAME ||  '%'
and
( :HAS_INFLUENCER_CONTACT is null
  or
  :HAS_INFLUENCER_CONTACT = '0'
  or
  any Contacts have (IsInfluencer = '1')
)
While a checkbox in its initial search form state appears unselected, a boolean parameter using a checkbox display type exhibits a null value by default. It changes to 1 (true) or 0 (false) only when selected or deselected by the user. Consider this original state in the SemQL condition. In the example above, the original checkbox state (null) is treated as equivalent to 0 (false) for the HAS_INFLUENCER_CONTACT search parameter.