.. _search_concept: Search in VOSS Automate ------------------------ .. _19.3.4-PB5|EKB-8303: .. _21.3-PB2|EKB-2620: .. _21.3-PB3|EKB-9720: Overview .......... .. rubric:: Search Methods There are two ways to run a search in the VOSS Admin Portal: * :ref:`what-would-you-like-to-do` (action/navigation search) Click the **Compass** icon, or type search criteria in the text field (from the Home page) * Quick / Global search (:ref:`advanced-search`) Click the **Search** icon (magnifier) to launch the Search dialog. .. image:: /src/images/search-icons.png .. note:: VOSS Automate 21.3 Patch Bundle 2 ships with an early field trial of its enhanced Search feature. This feature has been tested internally, has shown to have no impact on general system performance, and works for most use cases, as described on this page. Minor aspects of the functionality may not work as expected, for example, enhancements to search phrase use is reserved for future development. .. rubric:: Best Practices for Meaningful Search Results Search results are based on the menus and landing pages allowed and configured for your role. For this reason, administrators should align naming conventions and the setup of items for user navigation with terms that are familiar to users. For example: * Adjust the names of menus, landing pages, tasks, and quick actions if these prove to be unintuitive. * Configure relevant landing pages for quick actions, based on user roles. * Use the *What would you like to do?* search to quickly find actions that aren't available on landing pages. .. _what-would-you-like-to-do: What would you like to do? .............................. Search using the Compass icon or search field (What would you like to do?) is a quick way to navigate to a menu item or a landing page link. Click the toolbar **Compass** icon to run a search on 'actions' based on a search phrase or a single word, such as *add line*, *update subscriber*, or *phones*, to navigate quickly to a relevant form, view, or list. .. note:: Verbs in the search phrase return results when matching the same word in a menu or landing page, based on your access profile. You can also run this search directly from the Home page, where you can click in the Search field, fill out a search phrase or word, and press **Enter**. .. image:: /src/images/search-what-would-you-like-to-do.png The Compass search is a case-insensitive, fuzzy, free text search, with results based on the menu layout and landing page links for your access profile. All relevant items are returned. For example, including *add* in your search phrase also generates results for *create* and *add*. .. important:: At the time of writing (for 21.3-PB2): * Plural keywords may not return all relevant results. If you don't see the results you expect, change the keyword to singular, for example, *phone* instead of *phones*, or *add subscriber*, instead of *add subscribers*. * Using generic terms, such as *subscriber* or *phone*, returns all items relating to this keyword. * Avoid search phrases that include *a* or *an*. For example, use *add user* instead of *add a user*. * Search phrases that refer to a device, such as CUCM, returns all items (including device models) that have the device name in the label or description. Additionally, the phrase *add device* returns a list of results where the label starts with *device*, where the access profile allows the add operation, and (in this case), labels, descriptions, or models containing the full string, *add device*. * For best results (depending on the permissions you have on the model types), use the following verbs in search phrases: * create, add * update, edit, modify, change * delete, remove .. image:: /src/images/search-compass.png Search criteria supports abbreviations, model type keywords (such as view, relation, model), and matches for the first character of words in a string. For example, *QAS* returns *QAS - MS Teams*, as well as *Quick Add SIP Gateway*. .. note:: Including numerical digits in the search criteria only returns menus with digits in the menu name. For example, search criteria including the digits *1*, *6*, or *4* returns menus with these digits in their name, such as *E164 Inventory* (by default, a sub-menu in the **Number Management** menu). .. image:: /src/images/search-compass-digit-criteria.png Search results display in a table, including the path. .. image:: /src/images/search-compass-result.png Click on a search result to open it in the system. .. image:: /src/images/search-compass-result-path.png .. _advanced-search: Advanced Search (Quick/Global) ................................. Click the toolbar **Search** icon (magnifier) to launch an advanced search filter where you can perform a quick search of list views exposed by the menu layout, or a global search, in which you can specify the model to search on. Quick Search '''''''''''''''' Quick search allows you to select an entity from a drop-down of list views based on menu layouts for your access profile. Once you choose an entity, you can filter results to specify a search value, to choose the relevant field (related to the model) and search condition (for example, an operator such as *Contains*, *Equals*, or *Starts with*), and define whether to perform a case-sensitive search. .. image:: /src/images/search-use-search-icon.png Global Search '''''''''''''''''' Global search allows you to fill out search criteria (a search term or query), and run an advanced search that queries the API for the relevant model and search criteria. .. image:: /src/images/search-global.png For the global search results, you can select the checkbox adjacent to a search result (one or more), then click a toolbar action, such as **Delete**, or select an option from the **Action** drop-down (for example, **Export** or **Tag**. Actions allowed on search results are permissions-based, depending on your access profile. .. image:: /src/images/search-advanced-results.png Search results are permissions-based for your access profile, with caveats on number of items, relations, and device models. * Search results are returned for your current hierarchy and below. * Click on a search result to open it and view its details. * Search results for a simple string search matches the start of the text of a component. * Simple search strings match values in data and device models (relations instances are not returned). To search the relation model instances, specify the model as a part of the query. * Case-insensitive searches on field names are supported on several models. See :ref:`case-insensitive-search-fields`. * You can search on the summary attributes of any models, and for some models you can also search on a subset of their attributes. See: :ref:`searchable_fields`. * Selecting a data or device model instance returned in a search displays the full model details; that is, without a Field Display Policy applied. .. _search_syntax: Constructing Global Search Queries ..................................... Global Search Syntax '''''''''''''''''''''''' You can construct search queries to search for specific items, based on VOSS Automate search syntax filters. Search queries can contain: * Model type and model name references * Model attribute and nested model attribute references * Key words * Brackets, for grouping * Query string, using valid query string characters, as follows: * alphanumeric characters * Any of: :: !@#$%^&*-_=+<,.>/?\|[{]}~` * To search for single quote in a string, wrap the string in double quotes * To search for double quote in a string, wrap the string in single quotes Search queries are carried out on models, so you can specify the model type and the model name in a query, using the syntax ``type/name`` as the full reference to a model type (for example, relation, data, or device) and model name (for example, Countries). |search-syntax| Global Search Keyword Types '''''''''''''''''''''''''''''''' Various keywords can be used to construct a search query. Available keywords are categorized by type, either of the following: * Specification - WITH * Matching - IS, LIKE * Grouping - AND, OR .. tabularcolumns:: |p{2.5cm}|p{13cm}| +----------+-------------------------------------------------------------+ | Keyword | Description and Examples | +==========+=============================================================+ | WITH | Restricts the search to look for only specific data types. | | | In the example below we have specified the data type | | | Countries and so only countries will be returned. | | | | | | :: | | | | | | ((data/Countries WITH country_name LIKE Kingdom) AND | | | (data/Countries WITH country_name LIKE Unite )) | | | | +----------+-------------------------------------------------------------+ | IS | For a result to be returned the data attribute must match | | | exactly the 'input'. In the example below the 'input' | | | is Spain and only a Country with the attribute | | | country_name Spain will be returned. If 'North Spain and | | | South Spain existed they would not be returned. In the | | | example below we have specified the data type Countries | | | and so only countries will be returned. If we had not | | | specified a data type then the search would cover all | | | data types looking for an attribute country_name. | | | | | | :: | | | | | | country_name IS Spain | | | | | | data/Countries WITH country_name IS Spain | | | | | | Another example with a model tag as reference: | | | | | | :: | | | | | | tag IS "featurea" | | | | +----------+-------------------------------------------------------------+ | CONTAINS | Matching is done by substring and is the default parameter. | | | For a result to be returned, the data attribute must | | | contain 'input'. In the example below, the 'input' | | | is 'Sw' and the search would find both 'Sweden' and | | | 'Switzerland'. | | | | | | :: | | | | | | data/Countries WITH country_name CONTAINS Sw | | | | +----------+-------------------------------------------------------------+ .. tabularcolumns:: |p{2.5cm}|p{13cm}| +----------+-------------------------------------------------------------+ | Keyword | Description and Examples | +==========+=============================================================+ | LIKE | Matching is done by fuzzy search. | | | For a result to be returned, the data attribute must | | | nearly match 'input'. In the example below, the 'input' | | | is 'swe' and the search would find both 'Sweden' and | | | 'Switzerland'. | | | | | | :: | | | | | | data/Countries WITH country_name LIKE swe | | | | +----------+-------------------------------------------------------------+ | AND | This grouping term allows you to combine different | | | searches and only finds a result where both conditions | | | are met. The example below the search would find 'United | | | Kingdom' but not the 'Kingdom of Bhutan' as in this case | | | the second condition (LIKE Unite) is not true. | | | | | | :: | | | | | | ((data/Countries WITH country_name LIKE Kingdom) AND | | | (data/Countries WITH country_name LIKE Unite )) | | | | +----------+-------------------------------------------------------------+ | OR | This grouping term allows you to combine different | | | searches and matches a result where any one or both of | | | the conditions are met. The example search below would | | | find 'United Kingdom', 'United States' and 'Kingdom of | | | Bhutan'. | | | | | | :: | | | | | | ((data/Countries WITH country_name LIKE Kingdom) OR | | | (data/Countries WITH country_name LIKE Unite)) | | | | +----------+-------------------------------------------------------------+ Global Search Examples '''''''''''''''''''''''''' Where the attribute of a model is nested in an object, the reference to the attribute in the search query requires a model type specification. For example, for a model ``data/User`` with an attribute in a nested object called ``account_information``, the query should take the model type (``data``) specifier: :: data/User WITH data.account_information.credential_policy IS Default The following query *will not* yield results: :: data/User WITH account_information.credential_policy IS Default Brackets should be used in a query with matching and grouping operators. In a query containing no model references, brackets are evaluated first. The order of bracket evaluation is inner to outer brackets. Example Queries (line breaks added): :: (((data/Countries WITH pstn_access_prefix IS 9) AND (data/Countries WITH emergency__access_prefix IS 112)) OR (data/Countries WITH international_access_prefix IS 00)) Global Search String Format '''''''''''''''''''''''''''''''' The string to search for can be specified with the following properties: Multi-word and quotes Enclose in quotes. Single- and double quotes are supported. Example: ``'United States'`` When single word or multi-word values contain a single or double quote, the string needs to be enclosed in double or single quotes respectively, for example: ``"L'Amour"``. Case sensitivity Use the appropriate operator (LIKE) In a query containing model references, brackets and grouping keywords, the query is evaluated in the order. .. tabularcolumns:: |p{1.5cm}|p{2cm}|p{10.5cm}| +-------+----------+---------------------------------------------+ | Order | Element | Description | +=======+==========+=============================================+ | 1 | WITH | Model reference is evaluated first. | +-------+----------+---------------------------------------------+ | 2 | brackets | Brackets evaluate before grouping keywords. | +-------+----------+---------------------------------------------+ | 3 | AND | AND grouping evaluates before OR grouping. | +-------+----------+---------------------------------------------+ | 4 | OR | Evaluates last. | +-------+----------+---------------------------------------------+ A number of attributes from the meta data of a model can also be searched: * ``__device_pkid``: if a device pkid is known, then for example: ``device/cucm/Line WITH __device_pkid IS 55c32b59a6165451e04f392a`` * ``pkid``: if a pkid is known, then for example: ``data/CallManager WITH pkid IS 55c32b59a6165451e04f392a`` * ``tags`` (can also use "tag"): if the tag name is known, then for example: :: ((data/FieldDisplayPolicy WITH tag IS feature_tag_add_customer) AND (data/FieldDisplayPolicy WITH tags IS applicationendtoend)) .. note:: Only lower-case tags are searchable. Search in Drop-Down Lists .......................... On forms where you select values from pre-populated, editable drop-down lists, VOSS Automate allows you to run a case-insensitive search to filter results. .. rubric:: Run a 'Contains' search You can start typing in a drop-down field to run a **contains** search on the *first 1000* results. .. rubric:: Run a 'Starts with' search If you don't find the result you're looking for, click the magnifier icon adjacent to the drop-down to perform a **starts with** search on *all results*. .. image:: /src/images/search-drop-downs.png .. |search-syntax| image:: /src/images/search-syntax.png .. |search-compass-icon| image:: /src/images/search-compass-icon.png .. |search-magnifier-icon| image:: /src/images/search-magnifier-icon.png