Saved searches

images/download/attachments/169632051/image-2024-3-1_12-26-53-version-1-modificationdate-1709292413212-api-v2.png

There are many possible uses for Saved searches:

  • Firstly, it can be easily used interactively in conjunction with the Search builder to save ad hoc searches for later use (as a draft, reference solution, test case, template, research tool, etc.).

  • However, Saved searches can also be accessed automatically, for example to dynamically select a prepared configuration – e.g. via a search with search criteria – whose structure is processed in a workflow.

IMPORTANTSaved searches can only be executed interactively – via the associated detailed view of the Search builder. However, execution cannot be addressed directly via Behaviours or Event actions in order to obtain automated search results. The 'examples' below illustrate how Saved searches can still be used for automation purposes.

The menu path 'Administration' → 'System' → 'Database tools' → Saved searches opens an overview for 'Searches', for which the Search builder serves as a detailed view.

In purely technical terms, searches are instances of the 'EDI > Search' entity type(de.lobster.scm.edi.SearchTask), which maps all the characteristics of a 'Search builder'.

The Saved searches menu item only appears in the menu if the Role of session has the 'Show details' authorization (or higher) for the Search builder.

The data grid of the overview only lists search builders for which access exists in the context of the session because the Company of session is defined as its 'owner' or is authorized via Company authorizations.

The overview provides the generic functionalities for overviews and the handling of entities in overviews via the ribbon:

  • Which default functions (New, Delete, Edit, Cancel, etc.) are actually visible and 'active' (=effectively selectable) depends on the permissions for the Role of session and, if applicable, the access for selected instances.

  • The data of the selected search is loaded into the Search builder, for which an additional view may be opened if 'Edit' (or 'Show details') is selected in the ribbon or an entry in the data grid is double-clicked.

  • For Saved searches, the List function in the Change history subcategory can be used to trace previous versions if the same search was saved multiple times.

  • Saved searches can be exchanged between systems (e.g. test/production system) via Meta exchange (see Meta exchange extension).

    • In this context, it should be noted that it is possible to mark searches with Tags of the Tag category 'Configuration', for which the standard data grid provides the Tag (Configuration) column.

Examples

The following application examples show how Saved searches can be used for automated processing.

Special use case: Apply condition for a Search (Event action)

In the context of event handling, a Search (Event action) determines a subset of all Guest users (in access) as a list of entities for which a data manipulation is then executed in a loop.

Since the same 'subset' – specifically: a list of all Guest users whose account in the 'Company'(companyId) property refers to the Company of session – is relevant in different contexts, the relevant Restrictions should be stored centrally in a saved search and maintained as required. The 'Where' condition for the SearchTask entity used for this is read at runtime and transferred to the Search (Event action) executed in the event handling.

Configuration:

First, a search must be configured and saved, which is primarily used to centrally manage the Where condition.

NOTE◄ If this search is fully configured to run as described below, it can also be used for tests. However, complete configuration is not absolutely necessary.

  • The arbitrarily chosen Name(GUEST_USERS_FOR_COMPANY_OF_SESSION) is later used as the key value for 'finding' the entity. It should at least be clearly defined for the session context at runtime.

  • The Description documents the purpose of the search.

  • The 'Search' option (see Search types) is selected in the Search Combo box element so that a test returns complete entities.

    NOTE◄ This selection saves the configuration of 'projections', which would be required with the other Search types in order to be able to run tests. Since only the Where condition is transferred to a Search (Event action) at runtime, the selected search type does not play a decisive role. It does not have to match the search type in the Search (Event action), as the definition of the condition is not specific to the search type.

  • A Field restriction is created as a Where condition that compares a Property projection for 'Company'(companyId) with the return value of the Company of session resolver.

NOTE◄ The default value is retained for all other settings. As long as these are not explicitly transferred to the Search (Event action) at runtime, they have no influence on the search results obtained.

images/download/attachments/169632051/image-2024-3-1_12-27-37-version-1-modificationdate-1709292457723-api-v2.png

This search must be saved, ideally after the intended function has been verified by carrying out tests with suitable data.

The Where condition can then be accessed in the context of event handling.

The screenshot on the right shows an overview of the solution:

  • First, a Search (Event action) is executed, which writes the previously defined SearchTask object to the guestSearchTask variable based on the name as the key value.

  • The second Search (Event action) takes the 'Where' condition from the guestSearchTask variable and writes the resulting subset of Guest users to the guests variable.

  • The final For each loop event action then iterates over the list of Guest users in the guests variable from the second search.

images/download/attachments/169632051/image-2024-3-1_12-28-19-version-1-modificationdate-1709292499248-api-v2.png

The screenshot on the right shows the details for the first Search (Event action):

  • A 'Search' (see Search) is executed for the Entity 'EDI >Search'(SearchTask), the First result of which (see Mode) is written to the guestSearchTask variable (see Save result as).

  • The further definition for the 'Search' is limited to the Where condition in which a Field restriction checks a match(==) between the 'Name'(name) property of the search and a static text(GUEST_USERS_FOR_COMPANY).


IMPORTANT◄ The purpose of this search is to find the 'Saved search' whose 'Where' condition is used for the following Search (Event action). Neither the data model nor the input form for Saved searches ensures that the 'Name'(name) used when saving is unique. There can therefore be several searches with the name being searched for (here: GUEST_USERS_FOR_COMPANY). If there is access to several identically named searches in the execution context of the Search (Event action), only the 'first' match (see Mode) is considered here as the return value. As long as no sorting is used, this should be the candidate with the highest value for the ID (id). This is usually the last created search that meets the Where condition.

In the following, we do not check whether a match was found at all. In practice, this is only recommended to a limited extent, as without further precautions, the subsequent Search (Event action) may be executed without restriction if the search on the right does not return a result at runtime.

images/download/attachments/169632051/image-2024-3-1_12-28-49-version-1-modificationdate-1709292529476-api-v2.png

The screenshot on the right shows the details for the second Search (Event action):

  • A 'Search' (see Search) is performed for the 'Guest user' (GuestUser) Entity, the List of results (see Mode) of which is written to the guests variable (see Save result as).

  • No Where condition is defined within the 'Search', as this is taken from the guestSearchTask variable at runtime.


NOTE◄ The 'dynamic' configuration required for this must be initiated by clicking on the 'Customize Search' button (at the very bottom of the Search (Event action))::


images/download/attachments/169632051/image-2024-3-1_12-30-16-version-1-modificationdate-1709292616725-api-v2.png

images/download/attachments/169632051/image-2024-3-1_12-30-37-version-1-modificationdate-1709292637892-api-v2.png

images/download/attachments/169632051/image-2024-3-1_12-29-39-version-1-modificationdate-1709292579948-api-v2.png

images/download/attachments/169632051/image-2024-3-1_12-31-51-version-1-modificationdate-1709292712073-api-v2.png

In the 'Customize Search' block, the 'Search' defined above – here: with entity type 'Search' (Search) – is available as a reference object so that it can be edited before execution. The Set value event action overwrites its 'Where' condition (where) property with the corresponding 'Search restriction' value from the predefined search in the guestSearchTask variable. As the data field path in the Object property value resolver (bottom right) makes clear, the 'Search' (search) property must first be read and then its 'Where' condition (where) property.

NOTE◄ A similar approach could be taken – e.g. in the context of a copy of Set values event action – with other features of the 'Search' entity. In contrast to the 'Where' condition, however, it may be necessary to take into account the peculiarities of the different Search types. Not every feature is available in every search type. For example, the 'Search' (Search) entity does not support Group by's.

Special use case: Transferring a search to a view being opened

The search for Guest users used in the previous example is used in the context of a form to open a 'Guest user overview' as a modal view when a Button is clicked, which displays the subset of Guest users defined in the search.

Configuration:

The screenshot on the right shows the 'lookup' behaviour for the Button:

  • The 'lookup' behavior is triggered by the Triggering event Click.

  • A Chained behaviour with two steps is configured as the Behaviour:

    • The first Behaviour type is a Search (Form designer) behaviour that searches for the relevant search and passes the relevant SearchTask entity as a return value if successful:

      images/download/attachments/169632051/image-2024-3-1_12-35-20-version-1-modificationdate-1709292921009-api-v2.png


      The configuration of the search corresponds to that for the first Search (Event action) in the previous example: A Field restriction checks whether the 'Name' (name) is GUEST_USERS_FOR_COMPANY_OF_SESSION.

    • The second Behaviour type is a Calculate behaviour that performs two tasks:

      images/download/attachments/169632051/image-2024-3-1_12-36-18-version-1-modificationdate-1709292978559-api-v2.png


      1. The 'Search' object in the search property is read from the return value of the search (see Label expression).

      2. The Actions on "true" should only be executed if a 'Search' has actually been found (see Check expression).

    • An Open view (Form designer) action is configured under Actions on "true", to which the 'calculated' input value – the Search data object – is transferred. The 'Where' condition contained in the search therefore applies as a restriction for the open overview (see View or menu node name). Only the Guest users that the saved search defines as a subset via 'Where' condition are listed.

images/download/attachments/169632051/image-2024-3-1_12-34-33-version-1-modificationdate-1709292873574-api-v2.png