.. _macro-functions-model-filter:

Model Filters
--------------

.. _21.1|EKB-9170:


Model filters are set up as instances of ``data/ModelFilterCriteria``
with the following properties:

=================================  ================================================================
Property                           Description
=================================  ================================================================
``name``                           The name is used by the macro function
``type``                           The model on which the filter is applied
``criteria.attribute``             attribute name of the applied model
``criteria.conditional_operator``  optional: takes a boolean AND, OR NOT to apply to next criteria
``criteria.condition``             see list below for options
``criteria.value``                 filter condition value of attribute to check against
=================================  ================================================================

``criteria.condition`` can be:

=======================  ====================================  =====================
Field Name               Description                           GUI Field Name
=======================  ====================================  =====================
``equalsIgnoreCase``     Case insensitive exact match.         **Equals**
``isexactly``            Case sensitive exact match.           **Equals Exactly**
``containsIgnoreCase``   Case insensitive substring match.     **Contains**
``contains``             Case sensitive substring match.       **Contains Exactly**
``regex_search``         Regular expression                    **Regex Search**
=======================  ====================================  =====================


The macro functions take a Model Filter name as input.



Match Model Filter Criteria
...............................

.. index:: Macro function;fn.match_model_filter_criteria

* *fn.match_model_filter_criteria*:  Given input context data and 
  a model filter criteria instance ``name``, return a dictionary
  of output that contains a ``result``.

  Syntax: *{{fn.match_model_filter_criteria <input-data>,<filter-name> }}*

  In the Model Filter Criteria:

  * The ``filter-name``, individual ``criteria`` are evaluated to a value: ``True`` or ``False`` 
  * The ``filter-name``, criteria are combined with a ``conditional_operator``
    (e.g. boolean ``AND``) to yield the ``result`` value: ``true`` or ``false``
  * Filters will evaluate each of the criteria for the specified ``type``.

  Below is an instance of ``data/ModelFilterCriteria``
  for ``type`` is ``device/msgraph/MsolUser``:

  ::

     "data": {
                "type": "device/msgraph/MsolUser",
                "description": "Multi Level Filter",
                "name": "Multi Level Filter",
                "criteria": [
                    {
                        "attribute": "City",
                        "condition": "isexactly",
                        "value": "Cape Town",
                        "conditional_operator": "AND"
                    },
                    {
                        "attribute": "Address",
                        "condition": "contains",
                        "value": "Bellville"
                    }
                 ]
              }


  
  .. tabularcolumns:: |p{6cm}|p{9cm}|
  
  +--------------------------------------+--------------------------------------------------------------------+
  |  Example                             | Output                                                             |
  +======================================+====================================================================+
  | ``data/ModelFilterCriteria`` with    |                                                                    |
  | ``name`` is "Multi Level Filter" as  |                                                                    |
  | in example above.                    |                                                                    |
  |                                      |                                                                    |
  | Input context data contains:         |                                                                    |
  |                                      |                                                                    |
  | ::                                   |                                                                    |
  |                                      |                                                                    |
  |    {"user_details": {                |                                                                    |
  |       City": "Cape Town",            |                                                                    |
  |     ...                              |                                                                    |
  |       Address": "City of Bellville", |                                                                    |
  |     ...                              |                                                                    |
  |    }                                 |                                                                    |
  |                                      |                                                                    |
  | Function call:                       |                                                                    |
  |                                      |                                                                    |
  | ::                                   | ::                                                                 |
  |                                      |                                                                    |
  |    {{fn.match_model_filter_criteria  |    {"output":                                                      |
  |      user_details.City,              |     "[City] 'Cape Town' isexactly 'Cape Town'  =  True\n           |
  |      'Multi Level Filter' }}         |      [Address] 'City of Bellville' contains 'Bellville'  =  True", |
  |                                      |     "result": true}                                                |
  +--------------------------------------+--------------------------------------------------------------------+
  
  
Instances that match Model Filter Criteria
...........................................

.. index:: Macro function;fn.instances_match_model_filter_criteria

* *fn.instances_match_model_filter_criteria*:  

  Syntax: 

  *{{fn.instances_match_model_filter_criteria <model filter criteria name>,<field name>,<direction>}}*

  Given:

  * model filter criteria name: ``name`` of ``data/ModelFilterCriteria``
  * field name: a field name from the model filter criteria instance ``type``. The match results
    will be a list of this field, with the list called ``model_match_list``.

    The model filter can contain one or multiple ``criteria`` operating on the ``type`` model -
    with multiple criteria also combined with a boolean ``conditional_operator``.
  * direction: optional search direction. Default is ``above``, which is upwards and excludes
    the current hierarchy if it is not the top hierarchy.

  Return:
 
  * Input model filter and query details and result ``model_match_list``.

  Example macro:

  ::

     {{ fn.instances_match_model_filter_criteria CityTulsa,username,up }}


  Example output:

  ::

     {
       "model_filter_criteria_field": "username", 
       "model_filter_criteria_name": "CityTulsa", 
       "hierarchy": "nnf525b7e04a4a001480cfnn", 
       "model_filter_criteria": {
           "usage": "Test", 
           "type": "data/User", 
           "name": "Demo Criteria City = Tulsa", 
           "criteria": [
               {
                   "attribute": "city", 
                   "condition": "isexactly", 
                   "value": "Tulsa"
               }
           ]
       }, 
       "model_filter_macro": "{# data.User.* || direction:up #}", 
       "model_match_list": [
           "IsaiahL@tobuild.onsoft.com", 
           "PattiF@tobuild.onsoft.com", 
           "LidiaH@tobuild.onsoft.com", 
           "pietman@tobuild.onsoft.com", 
           "HenriettaM@tobuild.onsoft.com"
       ], 
       "model_filter_criteria_direction": "up", 
       "hierarchy_friendly_path": "sys.hcs.CS-P.CS-NB.RND.East.AlterLake"
     }