.. macro-mif-from-csv:

Model Instance Filters (MIF) from CSV File
--------------------------------------------

.. index:: Macro function;fn.generate_filters

*fn.generate_filters*: given input parameters:

* An uploaded CSV filename: the filename of a file uploaded to ``data/File``, e.g. using the **File Management** menu.
* Model Instance Filter (MIF) name: a name for an instance of ``data/ModelInstanceFilter``
* A model type to apply the MIF to, e.g.: ``device/msteamsonline/CsOnlineUser``.
* A filter type: ``inclusion`` or ``exclusion`` (if not provided as parameter, default is ``inclusion``)

create a MIF (``data/ModelInstanceFilter``) instance at the hierarchy where
the function is run, containing the data in the CSV file. The MIF can then be selected in data syncs
at the relevant hierarchy.

Syntax: *{{ fn.generate_filters <InputFile.csv>,<Output_MIF_Name>,<input_model>[,<filter_type>] }}*

.. note::

   The MIF ``model_parent`` will be the parent of the input model. For example, if the input model
   is ``device/msteamsonline/CsOnlineUser`` then ``device/msteamsonline`` is the ``model_parent``.

The CSV file format is interpreted as follows:

* Header row: attribute(s) of *<input_model>* (``attr_name``)
* 2nd row onwards: value(s) which have ``equals`` match to attribute(s)

.. note::

   * Each value row in the CSV file represents a model filter instance with value ``equals`` the
     ``attr_name``. Filter instances are combined with logical OR.
     Refer to the *Model Instance Filter* topic in the Core Feature Guide.
   * If the CSV file contains more than one column, i.e multiple attributes and values,
     then the ``attr_filters`` list in the MIF instance will combine these with a logical
     AND. Refer to the *Model Instance Filter* topic in the Core Feature Guide.
             
.. rubric:: Example

For example, a CSV file (``InputFile.csv``) uploaded using the **File Management** menu 
at hierarchy ``sys.hcs.CS-P.VOSS-OPS.VOSS`` with a single attribute ``UserPrincipalName``:

::

   UserPrincipalName
   Dusty.Moyer@visionoss-dev.info
   Earl.Moore@visionoss-dev.info


then the macro function run at hierarchy ``sys.hcs.CS-P.VOSS-OPS.VOSS`` called

``{{ fn.generate_filters InputFile.csv,MSOL_MIF,device/msteamsonline/CsOnlineUser }}``

will create MIF instance containing:

::

   {
    "meta": {},
    "resources": [ {
       "meta": {
         "model_type": "data/ModelInstanceFilter",
         "pkid": "...",
         "schema_version": "...",
         "hierarchy": "sys.hcs.CS-P.VOSS-OPS.VOSS",
         "tags": []
       },
       "data": {
         "filter_type": "inclusion",
         "name": "MSOL_MIF",
         "model_parent": "device/msteamsonline",
         "model_filters": [
           { "model_type": "device/msteamsonline/CsOnlineUser",
            "attr_filters": [
              { "attr_name": "UserPrincipalName",
               "condition": "equals",
               "value": "Dusty.Moyer@visionoss-dev.info"
              } ] },
           { "model_type": "device/msteamsonline/CsOnlineUser",
            "attr_filters": [
              { "attr_name": "UserPrincipalName",
               "condition": "equals",
               "value": "Earl.Moore@visionoss-dev.info"
              } ] }
         ] }
      } ]
   }