Saved searches
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.
►IMPORTANT◄ Saved 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.
►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. |
|
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:
|
|
The screenshot on the right shows the details for the first Search (Event action):
►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. |
|
The screenshot on the right shows the details for the second Search (Event action):
►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))::
|
|
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. |