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 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/v3/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/v3/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/v3/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/v3/data/InventoryDetails?.full=true&summary.reachability=REACHABLE
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/v3/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/v3/data/AccessPoints?.full=true&location=%22default%20location%22
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/v3/data/Devices?deviceName=IFM&.case_sensitive=false ../api/v3/data/Devices?deviceName=ifm&.case_sensitive=false ../api/v3/data/Devices?deviceName=IFM ../api/v3/data/Devices?deviceName=contains("IFM") ../api/v3/data/Devices?deviceName=ifmWhereas, the two urls below are case sensitive and will return different results
../api/v3/data/Devices?deviceName=IFM&.case_sensitive=true ../api/v3/data/Devices?deviceName=ifm&.case_sensitive=true
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 | * | * |
The NBI supports filtering on collections (Collection, List, Set and Map) of type String plus the 8 Java primitive types.
Some examples:
../webacs/api/v3/data/MyClass?myCollectionField.elements=value ../webacs/api/v3/data/MyClass?myMapField.elements=value ../webacs/api/v3/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.
When filtering based on date, you must specify the date in ISO-8601 format. Additionally, you should surround the date with quotes.
Some examples:
../webacs/api/v3/data/Alarms?alarmFoundAt=gt("2012-06-20T00:01:00") ../webacs/api/v3/data/Alarms?alarmFoundAt=lt("2012-06-20") ../webacs/api/v3/data/Alarms?alarmFoundAt=between("2012-06-01","2012-07-01")
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 quotes.
Some examples:
../webacs/api/v3/data/Clients?deviceIpAddress=192.168.1.10 ../webacs/api/v3/data/Clients?deviceIpAddress=startsWith(192.168) ../webacs/api/v3/data/WlanProfiles?hotspotGeneral.heSsid="00:00:00:00:00:00" ../webacs/api/v3/data/WlanProfiles?hotspotGeneral.heSsid="000000000000"
In Prime Infrastructure, 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 Prime Infrastructure. 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.
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