.. _model_instance_filter:
Model Instance Filter
---------------------
.. _18.1-Patch-Bundle-3|VOSSSOL-11684:
.. _19.1.1|DOC-306:
.. _19.3.2|EKB-4370:
The model instance filter (MIF) capability allows 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,
that 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
|MIF-example|
Add a Model Instance Filter
...........................
1. Log in as a Provider level administrator and choose **Administration Tools > Model Instance Filter**
to display the list view of existing filters at the corresponding administrator hierarchy.
2. Choose **Add** to open the Model Instance Filter form. Provide a **Name** for the filter.
3. Choose the device or model type from the **Model Parent** drop-down. The filter will be applied to it.
4. Choose the type of filter - the inclusion or exclusion of attributes: **Include Matching Instances**
or **Exclude Matching Instances**.
5. 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**.
* Provide a **Value** to filter 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``.
6. 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 <ModelTypeList> 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
::
</ns0:listUserProfileProvision>
</soapenv:Body>
</soapenv:Envelope>
RESPONSE:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:listUserProfileProvisionResponse xmlns:ns="http://www.cisco.com/AXL/API/11.5">
<return>
<userProfileProvision uuid="{96FA39CD-8A29-4B26-A3F5-0FF683326134}">
<name>Standard (Factory Default) User Profile</name>
<description>Standard (Factory Default) User Profile</description>
<allowProvision>false</allowProvision>
<limitProvision>10</limitProvision>
</userProfileProvision>
Common Use of Model Instance Filters
....................................
While model instance filters can be used on any sync type, their common uses are:
* On add syncs - to retrieve a subset of records from the underlying device into VOSS-4-UC.
For example, to limit the users pulled from LDAP, from UCM, and so on.
* On delete/purge sync - to target specific records for removal in a purge or delete sync.
For example, to purge a subset of users from VOSS-4-UC that were inadvertently pulled in.
.. note::
Model Instance filters do not work with Cisco UCM Change Notification sync types.
If a model instance filter is needed for a UCM element, this model type should
be excluded from the change notification sync and a separate sync should be set 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:
* **Model Type**: ``device/cucm/User``
* **Attribute Name**: ``telephoneNumber``
* **Value**: ``macro.ZA-number``
where ``macro.ZA-number``:
::
(( fn.containsIgnoreCase +27,input.telephoneNumber == True)) \
<input.telephoneNumber> \
<THIS SHOULD NOT MATCH>.
This condition will sync every user with a telephone number that includes ``+27``.
For any other user, the transaction detail log would show: "THIS SHOULD NOT MATCH".
Macros cannot be used in the **Value** field in conjunction with the "in" **Condition**.
.. |MIF-example| image:: /src/images/MIF-example.png