.. _search_concept: Search in VOSS Automate ------------------------ .. _19.3.4-PB5|EKB-8303: The search input box in the VOSS Automate Admin Portal performs a default quick search for items across all components in the system. Results are permissions-based for your access profile, with caveats on number of items, relations, and device models (listed below). For a simple, entered string, the search matches the start of the text of a component. .. note:: * Search result lists are limited to a maximum of 1,000 items. A system message at the bottom of the list pages indicates the limit. You may need to update your search query to reduce search result. * Simple search strings match values in data and device models (relations instances will not be returned). To search the relation model instances, specify the model as a part of the query - refer to the search syntax. * For a number of models, case insensitive searching on field names are supported. For a the list of models and supported text cases, see :ref:`case-insensitive-search-fields`. * While all models can be searched for by using their summary attributes, a number of models can also be searched on by 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. .. _carry_out_a_search: Basic Search ............. #. In the VOSS Automate Admin Portal, choose a hierarchy level. Search is performed on items at this level, and down. #. In the **Search** field, enter a search string (using the search syntax). By default, sub-string matches are included; that is, searching for "Site" also shows "Site2" in the result list. #. Press the keyboard **Enter** key. View the list of search results. .. note:: * You can click on a search result in the list to open it and view its details. * Alternatively, you can select the checkbox for a search item (one or more), and 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. .. _search_syntax: 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| 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)) | | | | +----------+-------------------------------------------------------------+ 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)) 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-syntax| image:: /src/images/search-syntax.png