.. _concepts-working-with-lists:

Working with Lists
--------------------

.. 20.1.1|VOSS-695|EKB-5200:

Summary views of resources and services are shown in lists in the VOSS Automate Admin Portal. For 
example, you can view a list of components in your system hierarchies, or to view a list of 
customers, sites, users, subscribers, servers, or device types. 

The lists include functionality that allows you to sort, order, and filter items, 
and to navigate across multiple pages.   

.. image:: /src/images/list-example.png


Sort and Order Lists 
.....................

Columns in the list views may contain string values or numeric values. The default 
sort order is on the first column, either alphabetically (descending) for string value 
columns, or numerically (descending) for numeric value columns. 

To sort the list based on values in a column, click on any column header. Click again to change the 
direction of the sort order. An up/down arrow in the column header indicates the sort order. 

When sorting: 

* Cells with no value move to the top or bottom of the list, depending on the 
  sort order (ascending or descending). 
* Upper case letters letters sort before lower case letters.
* Any column can be sorted, provided no filter is applied. 
* Applying a filter to two or more columns disables sort.
* Leading spaces in field values are dropped from the list view. This may affect the 
  sort order. 
* Values in the **Located At** column are sorted according to the string value, and not the hierarchy path. 




Navigate Lists
..................

Lists with many items may display across two or more pages.

* To navigate across a multiple page list, click the right/left arrow to scroll to the next/previous page, 
  or click a page number.

  .. image:: /src/images/list-navigation-2.png

* To view more items per page, specify the number of items to display on each page, from 25 to 2000. 

  .. image:: /src/images/list-navigation-1.png

* The header row displays the number of the rows you're viewing out of the total.

  .. image:: /src/images/list-row-numbers.png 


.. note::
   
   Search results that display as lists return a maximum of 1,000 items.
   A system message at the bottom of the list indicates this limitation. Change the search 
   criteria for result lists exceeding 1000 items.  
   




Filter Lists
................

The list filter functionality you'll see in VOSS Automate depends on whether you're using the 
legacy Admin GUI or the Admin Portal (introduced at v21.2). 

.. note:: 

   This topic describes filtering on resource and service summary lists. 
   For details around filtering transactions, sub-transactions, and log lists, 
   see :ref:`filtering_transactions`.


Filtering Lists in the Legacy Admin GUI
'''''''''''''''''''''''''''''''''''''''''

The legacy Admin GUI provides a filter dialog for specifying one or more search 
criteria to apply to the list. 


**To filter lists in the legacy Admin GUI**: 

1. Log into the VOSS Automate Admin GUI. 
2. Open a list view for a resource or service. For example, (default menus) **User Management > Users**. 
3. Open the **Filter** dialog. Two options are available: 

   * Click the **Filter** button located at the bottom of the list (adjacent to the **Items/Page** 
     drop-down).

     .. image:: /src/images/list-legacy-admin-filter.png
   
   * Mouseover any column header to display the **Filter** icon, then click on the icon to open the 
     **Filter** dialog. In this case, the first filter defaults to the column name, but you 
     can specify any filter you choose (one or more), and the filter applies to all data in the list. 

4. To specify filter criteria, choose a column, a filter operator, and a value. 

   .. image:: /src/images/filter.png

   Available filter operators: 

   * Contains (default)
   * Does Not Contain
   * Starts With
   * Ends With
   * Equals
   * Not Equal

5. Clear the **Ignore Case** checkbox to create a case-insensitive search. This checkbox is selected 
   by default. 

   .. note:: 

      To filter for empty rows in a specific column, you can choose any filter type, 
      select **Ignore Case**, and type ``None`` in the **Value** field of the **Filter** 
      dialog. This works for all list views except Subscriber.

5. Specify additional filters, if required. To remove any of the filters, click **Remove**.

   .. note:: 

      The combination of filters you set up creates a single filter; that is, 
      all filter rows are applied (in a logical AND) when you run the filter. 

5. Click **Apply** to run the filter. 

6. View the filtered list. 

   .. note::

      * While a filter is applied, clicking on a column header to sort data is only supported 
        for the **Starts With** operator. 

      * The **Located At** column only filters on the name of the hierarchy (for example, the site 
        name), and not on the hierarchy type itself (for example, site, or customer). 

      * You can perform additional actions on a filtered list, for example, to select a number of items 
        in a filtered list to move or delete the items. 
      
      * A filter remains active until you remove it or until your user session ends (even if you 
        navigate away from the page). If you're not 
        seeing all data on a list, clear the filter by clicking the X icon adjacent to the 
        **Filter** button, or open the dialog and remove filters. 



.. rubric:: Filter Operators and Column Value Types

* You can use all filter operators on string value columns.  
* You can use all filter operators on Boolean value columns, provided values are "True", "true", "False" or "false".
* For number value columns, you can also use *Equals* and *Not Equal* filter operators. 
* When filtering on decimals in number value columns: 

  * To filter floating point values in number value columns, specify at least one decimal digit, for example, 
    ``2.0``. 
  * Filtering can be applied to values with decimal values up to 7 decimals. For example: 
  
    Consider a list of values, and the following filter: Not Equal to ``2.00000001``

    ::

     2.2000001
     2.0000001
     2.00000001

    In this case, the filter displays only one 
    value (``2.2000001``), because the filter value exceeds 7 decimals.




.. rubric:: Filters and Model Lists 

If access is available to specific models, such as configuration templates and macros, 
filters apply to *all* the instances in the hierarchy, since the listing of instances 
in these models is not restricted to a user's hierarchy. 

Standard list view filters on model types are removed and replaced by any 
configurable filters on landing page links or menu items for the corresponding model 
type when these are used. See :ref:`menus_landing_configurable_filters`.




Filtering lists in the Admin Portal
''''''''''''''''''''''''''''''''''''''

The new VOSS Automate Admin Portal (introduced at v21.2), provides two options to filter a list view: 

* Advanced filter, via a **Filter** dialog.

* Quick filter, via **Filter** fields below the column header row.

.. image:: /src/images/filter-dialog-new-gui.png


**To filter lists in the Admin Portal**: 

1. Log into the Admin Portal. 
2. Open a list view for a resource or service. For example, (default menus) **User Management > Users**. 
3. Add filters. Two options are available:  

   * Option 1: Advanced filter
   
     Click the toolbar Filter icon (|filter|) to launch the **Filter** dialog. Specify 
     filter criteria: 

     * Select a field and a condition, and enter a filter value.
     * To run a case-insensitive search, clear **Ignore Case**, else, leave the checkbox selected (default).
     * Click **Add Filter Condition**. 
     * Repeat this step for all the filters you want to apply to the list. 
     * Click **Filter**

   * Option 2: Quick filter
     
     Click in the **Filter** field below a column header, and add filter criteria. You can add criteria to one or more 
     columns. The filter applies once you tab out of the field. 

   Column sort options may be disabled by the filters. 

4. View filter results in the list view. 

   The applied filter criteria displays at the top of the list. 
   
   To clear any filter, 
   click the red X icon at the relevant **Filter** field, or click the red X icon in the 
   first column to clear all filters. Alternatively, click on the **Filter** text link (or on the 
   toolbar Filter icon) to open the **Filter**, where you can remove one or more filters. 

   The banner above the header row displays: 

   * The number of result rows matching the filter.
   * The applied filter, as a clickable text link. Clicking on the filter opens the **Filter** dialog, 
     where you can add, modify, or remove filters. 
   * Filter values, which display in the **Filter** fields beneath the relevant column headers.


.. image:: /src/images/list-filter-new-admin-portal.png


.. |filter| image:: /src/images/filter-icon-new-gui.png