
Cisco Evolved Programmable Network Manager API
Evolved Programmable Network Manager API Documentation

# Using Filtering

Filtering lets you limit the results of a request based on the value of specific Resource attributes. Check the documentation for each request type to see if it supports Filtering.

## Filtering Syntax

Filtering on a given attribute of a resource is simple. The documentation gives a list of all attributes for a given resource. For example, to get a device with a given IP address, you may use the following:

    	../webacs/api/v4/data/Devices?ipAddress="192.168.1.1"

Note that the double quotes should be percent-encoded, either explicitly by you or automatically by your client.

A set of operators allows you to refine the filter in many ways. For example, to get the list of all device in a given subnet, you may use the startsWith operator on the IPAddress:

    	../webacs/api/v4/data/Devices?ipAddress=startsWith("192.168.")

The results of a query can be filtered using the value of one or more attribute. These criteria can be ' ANDed' (the default) or ' ORed' together. So to get all devices in private subnets, you may use an ORed request as follows:

    	../webacs/api/v4/data/Devices?.or_filter=true&ipAddress=startsWith("192.168.")&ipAddress=startsWith("10.0.")

Note that multiple requests return nested types. To filter on a nested parameter value, you can use a "dotted" notation to each attribute name. For example, to filter InventoryDetails to reachable devices, you may use the following URL:

    	../webacs/api/v4/data/InventoryDetails?.full=true&summary.reachability=REACHABLE

### URL encoding (also known as percent-encoding)

When forming a filter URL it must comply with URL encoding rules and only contain characters from the RFC 3986 reserved and unreserved character sets.

Filter values may frequently contain characters from outside the valid character sets, for example spaces and double quotes:

    					../webacs/api/v4/data/AccessPoints?.full=true&location="default location"

These must be converted into a valid percent-encoded format. URL encoding replaces invalid characters with a "%" followed by two hexadecimal digits.

A web browser, and some other HTTP clients, will automatically encode the provided URL before sending it to the server. However, if for example you are using a client coded with cURL you will need to do the encoding yourself. So after encoding, the above API query becomes the following URL

    					../webacs/api/v4/data/AccessPoints?.full=true&location=%22default%20location%22

## Case Sensitivity

The query parameter .case_sensitive controls whether string comparisons are case sensitive or not. When .case_sensitive is present in the url and set to true, string comparisons are case sensitive. When .case_sensitive is not present in the url or is set to false, string comparisons are case IN-sensitive

For example, the four urls below are case IN-sensitive and will return the same result:

                                ../api/v4/data/Devices?deviceName=IFM&.case_sensitive=false
                                ../api/v4/data/Devices?deviceName=ifm&.case_sensitive=false
                                ../api/v4/data/Devices?deviceName=IFM
                                ../api/v4/data/Devices?deviceName=contains("IFM")
                                ../api/v4/data/Devices?deviceName=ifm

Whereas, the two urls below are case sensitive and will return different results

                                ../api/v4/data/Devices?deviceName=IFM&.case_sensitive=true
                                ../api/v4/data/Devices?deviceName=ifm&.case_sensitive=true

## Filtering Operators

Operators are allowed on attributes depending on their types. The following operators can be used in the filter definitions:

|  | AppliesTo |
--- | --- | --- | ---
Function | Name | Numeric | Enum | Boolean | String | Date | InetAddress | Comment
(literal) | equals | * | * | * | * | * | * | Same as eq()
eq(value) | equals | * | * | * | * | * | * |
ne(value) | not equals | * | * | * | * | * | * | Inverse of eq()
in(value1,value2...) | in | * | * |  | * |
gt(value) | greater than | * |  | * | * |
ge(value) | greater or equal to | * |  | * | * |
lt(value) | less than | * |  | * | * |
le(value) | less than or equal to | * |  | * | * |
between(start,finish) | between two values | * |  | * |  | Both values must be same type
notBetween(start,finish) | not between two values | * |  | * |  | Both values must be same type
contains(value) | contains |  | * |  | * |
notContains(value) | does not contain |  | * |  | * |
startsWith(value) | starts with |  | * |  | * |
notStartsWith(value) | does not start with |  | * |  | * |
endsWith(value) | ends with |  | * |  | * |
notEndsWith(value) | does not end with |  | * |  | * |
isTrue() | is true |  | * |
isFalse() | is false |  | * |
isEmpty() | collection property is empty | * | * | * | * | * | * | Applies to collection properties only
notIsEmpty() | collection property is not empty | * | * | * | * | * | * | Applies to collection properties only
isNull() | property is null |  | * |  | * | Note that this is not the same as eq("")
notIsNull() | property is not null |  | * |  | * |

## Filtering on collections of primitives

The NBI supports filtering on collections (Collection, List, Set and Map) of type String plus the 8 Java primitive types.

Some examples:

    		../webacs/api/v4/data/MyClass?myCollectionField.elements=value
    		../webacs/api/v4/data/MyClass?myMapField.elements=value
    		../webacs/api/v4/data/MyClass?myMapField.indices=key

Note, the keyword "elements" is used in filtering on the values held in any primitive collection type and that the keyword "indices" is used in filtering on the keys of a Map.

## Filtering based on Strings

When filtering based on a string, we recommend to surround the value with double quotes. It is not required if the value consists of alphanumeric characters only.

## Filtering based on Dates

When filtering based on date, you must specify the date in ISO-8601 format. Additionally, you should surround the date with double quotes.

Some examples:

    	../webacs/api/v4/data/Alarms?alarmFoundAt=gt("2012-06-20T00:01:00")
    	../webacs/api/v4/data/Alarms?alarmFoundAt=lt("2012-06-20")
    	../webacs/api/v4/data/Alarms?alarmFoundAt=between("2012-06-01","2012-07-01")

## Filtering on InetAddress and MacAddress properties

The NBI supports filtering on properties of InetAddress and MacAddress types. You must specify the actual property name instead of nested "address" or "octets" properties.

You can pass MAC address in a hexademical representation. Octets may be separated by any non-hexadecimal character. There is no need to specify a leading zero digit for separated octets. Additionally, you should surround the octets with double quotes.

Some examples:

    	../webacs/api/v4/data/Clients?deviceIpAddress=192.168.1.10
    	../webacs/api/v4/data/Clients?deviceIpAddress=startsWith(192.168)
    	../webacs/api/v4/data/WlanProfiles?hotspotGeneral.heSsid="00:00:00:00:00:00"
    	../webacs/api/v4/data/WlanProfiles?hotspotGeneral.heSsid="000000000000"

## Domain Based Filtering

In Evolved Programmable Network Manager, there is a concept of "Virtual domains" which limits a users' access to a set of network objects based on their location. The API respects this concept, in that basic requests are filtered by the users' "default" domain as defined in Evolved Programmable Network Manager. Within a session it is possible to change the domain that is being used through use of the control parameter:

    			 ?_ctx.domain=otherDomain

This changes the current domain until the session ends, or the user set the domain though another query using this control parameter. If the domain does not exist or is not accessible for the user then a 400 Bad Request error will be returned.

## Group Based Filtering

In the application, there is a concept of "Groups" which allow devices to be grouped together with like items. There are various types of groups including sites and other user defined groups. It is possible to limit the results returned using one or more of these groups.

For example:

    			 ?.group=myrouters
    			 ?.group=myrouters,boise

This will limit the results returned to those in a specific group or groups.

In the case where you have groups with duplicate relative names you can specify the filter using the fully qualified group name. These must start with the '/' character and must not have a trailing '/'". For example:

    			 ?.group=/User Defined/my group
    			 ?.group=/Location/All Locations/my group

- Home
- Filtering
- Sorting