.. _model-instance-filter: Model instance filters ------------------------ .. _18.1-Patch-Bundle-3|VOSSSOL-11684: .. _19.1.1|DOC-306: .. _20.1.1|VOSS-670|EKB-4370: .. _21.2|EKB-8981: .. _21.4-PB4|EKB-16845: .. _25.3|EKB-22640: .. tip:: :ref:`use-action-search-to-navigate-automate` Overview ......... Model instance filters (MIF) allow the administrator to provide criteria to define a subset of model instances to sync in. This causes the sync to only sync in those instances matching the criteria instead of all the instances. A data sync can be set up with reference to: * The device that is the sync target * A set of data in the form of a model type list, which also defines the sync sequence of the models in this list * Model instance filters of the models in the list - to provide more specific filtering of specific instances of the models to sync .. note:: When using a model instance filter with a data sync, the ability of the sync to remove (purge) records is disabled by default to prevent the unintentional removal of records that are excluded by the model instance filter. You'll need to enable *Remove* if you intend for the sync to purge cache records that are excluded by the model instance filter. See :ref:`data-sync` If you're upgrading to 21.4-PB4 from an earlier version of Automate, a migration script disables *Remove* for any syncs that have a model instance filter applied. This is to prevent the sync from unexpectedly removing a large number of records after the upgrade. |MIF-example| Add a model instance filter ........................... 1. Log in as a Provider level administrator, then go to **Model Instance Filter** to open the list view of existing model instance filters at the corresponding administrator hierarchy. #. Click the Plus icon (+) to add a new model instance filter. #. Fill out a name for the new model instance filter. #. From the **Model Parent** drop-down, choose the device or model type. The filter will be applied to it. .. note:: A data sync will fail if the **Model Parent** of the Model Instance filter does not match the **Device Type** of the Data Sync. #. Choose the type of filter - the inclusion or exclusion of attributes: **Include Matching Instances** or **Exclude Matching Instances**. #. Add one or more filters in the **Model Filters** group: a. Choose the **Model Type** that belongs to the **Model Parent**. b. Add one or more attribute filters in the **Attribute Filters** group: * The **Attribute Name** should be selected after inspecting list request responses in the Transaction log - refer to the note below. * Choose its **Condition**. For **In** and **Not In**, if the field specified turns out to be an array, then "in" means there is an overlap between the field value and the value it is being checked against. For example, "lines in " is comparing an array to an array. The **Like** condition is a regular expression match, so in any regex should work here, but a very basic usage of regex is a "contains" type functionality, for example, "username like fred". .. note:: Automate issues a warning when it detects an ``in`` condition for ``UserPrincipalName`` used alongside other ``CsOnlineUser`` filters during sync and filtering. In Microsoft tenants with auto-filter enabled, the expected records may not be returned if your MsolUser cache is not up to date. * Provide a **Value** to filter on. It is often better (frequently faster) to try and use a built-in **Condition** rather than resorting to macros in the **Value** that needs to be matched on. Filter criteria can be set up according to your purposes: * Multiple **Model Type** entries are treated as an OR condition; creating a list of criteria. Any records matching any of the entries will result in a match. This is useful when defining criteria for different model types, for example, criteria for user records and different criteria for phone records. It is also useful for defining multiple criteria on the *same* model type and attribute, for example, multiple entries for ``device/cucm/User`` model type where the attribute of ``userid`` for example matches different macro-based conditions. * Multiple **Attribute Filters** - attribute criteria for a model type are treated as a logical AND condition and entries need to match *all* the criteria in order to meet the condition. This is useful when creating criteria that match multiple different attributes of the model type, for example, match a user that has a matching ``userid`` as well as a matching ``department``. #. Click **Save**. The filter can be selected from the **Model Instance Filter** drop-down when creating or modifying a Data Sync. .. note:: * If the filter is added at a hierarchy level *below* that of the the Data Sync, executing the Data Sync will fail, displaying a message "Model type list not found at or above the current hierarchy.". * In order to identify the **Attribute Name** of the model that can be used for a filter, inspect the transaction log for a list request of the model from the device. For example, in order to find the available Model Instance Filter attributes of ``device/cucm/UserProfileProvision``, inspect the response from a list request from the device. From the RESPONSE snippet below, it can be determined that the attributes available for filtering are: * name * description * allowProvision * limitProvision :: RESPONSE: Standard (Factory Default) User Profile Standard (Factory Default) User Profile false 10 Common use of model instance filters .................................... While model instance filters can be used on any sync type, their common uses are: * Add syncs - to retrieve a subset of records from the underlying device into Automate. For example, to limit the users pulled from LDAP, from UCM, and so on. * Remove/purge sync - to target specific records for removal in a purge or delete sync. For example, to purge a subset of users from Automate that were inadvertently pulled in. .. note:: When using a model instance filter with a data sync, the ability of the sync to remove (purge) records is disabled by default to prevent the unintentional removal of records that are excluded by the model instance filter. You'll need to enable *Remove* if you intend for the sync to purge cache records that are excluded by the model instance filter. See :ref:`data-sync` .. note:: Model instance filters do not work with CUCM Change Notification sync types. If a model instance filter is needed for a CUCM element, this model type should be excluded from the change notification sync and a separate sync should be se up for this. Macro functions in model instance filters ......................................... Macro functions can be used in the **Value** field to define matching criteria. This is particularly useful for "contains" matching, for example, using ``fn.contains`` or ``fn.containsIgnoreCase``. The value read in from the device API call can be referenced using the input context and the field name from the API call (for example, ``input.telephoneNumber``). For example, the **Value** field can have: * for ``fn.contains``: :: ((fn.contains Dublin, input.description == True)) <{{input.description}}> This ``fn.contains`` function will search as *case sensitive*, and in the example will only match where the description field contains the word "Dublin". * for ``fn.containsIgnoreCase``: :: ((fn.containsIgnoreCase +27,input.telephoneNumber == True)) <{{input.telephoneNumber}}> You can also use a named macro (e.g. ``macro.ZA-number``), that has the macro above in the **Value** field instead, so that: * **Model Type**: ``device/cucm/User`` * **Attribute Name**: ``telephoneNumber`` * **Value**: ``macro.ZA-number`` This condition will sync every user with a telephone number that includes ``+27``. Macros cannot be used in the **Value** field in conjunction with the "in" **Condition**. .. _model-instance-filter-examples: Model instance filter examples .................................. This section describes a few examples for using model instance filters. .. rubric:: Model instance filter with multiple model filter entries to match criteria on different model types: |MIF-example1| This model instance filter will result in: looking at ``device/cucm/User`` records it will match users that have a department of Marketing, Finance, or IT (due to the IN condition). When looking at ``device/cucm/Phones`` it will match phones of the type "Cisco 7940". .. rubric:: Model instance filter with multiple model filter criteria entries with the same model type and macros to create a list of records to match |MIF-example2| For this example, when looking at the ``device/cucm/User`` records it will match users that have a telephone number containing ``+1`` OR ``+27``. The macro in the value field is cut short but it's using the macro in the notes above for reference. Due to the macros in use in the value, this had to be done as multiple model filter entries instead of a attribute filter using the IN condition. .. rubric:: Model instance filter with multiple attribute filters applied to the same model type |MIF-example3| When looking at the ``device/cucm/User`` records it will match users that have a department matching Marketing, Finance, or IT, AND has the home cluster flag set to true. .. |MIF-example1| image:: /src/images/MIF-example1.png .. |MIF-example2| image:: /src/images/MIF-example2.png .. |MIF-example3| image:: /src/images/MIF-example3.png .. |MIF-example| image:: /src/images/MIF-example.png