KACE Systems Management Appliance 14.0 Common Documents - API Reference Guide

Filtering on related data

Filtering on related data

Note that adding a filter on a sub-entity does not cause the data for that sub-entity to appear in the result set.

The filter is applied, but shaping (or sorting) is required in order to specify extra return data.

Using wildcards in filters

Using wildcards in filters

There is a special case in which a filter can be applied to match any field of the entity. To use that capability, an asterisk '*' can be used as the field name.

The wildcard filter in some cases also matches values in sub-entities, to make them more useful to the client. The Service Desk API GET /api/service_desk/tickets has special handling to include owner names and submitter names in the wildcard. To find out if this handling is available and for more information about the Service Desk API, see Service Desk API Reference.

Examples:

Return the machines in which any field contains the string ABC:

Filters can be combined. The following example retrieves the machines that have the software title DEF installed and also have fields containing the ABC string:

Sorting

Sorting

Sorting is accomplished with the sorting query parameter. Commas can be used to separate multiple sorting requests. Each sorting request must give the sort entity and field. Optionally, a sort order can be specified. If the sort order is not specified, the default sort order is ASC (ascending). Sort requests are processed from left to right.

Sorting can be performed on the base entity as well as on any sub-entities. If sorting is indicated for a sub-entity that does not appear in the shaping clause, that sub-entity is automatically included at the standard shaping level. Any given shaping level overrides that value.

Examples:

Sort the machines by their ID in a descending list, and retrieve the software for each machine. Shaping is not necessarily required here. It is assumed that since ordering was requested for the software, it is expected in the result set:

Since shaping is not specified in the above example, the standard level is applied. However, note also that shaping can still be specified, if needed:

In this example any result data is sorted by the machine name and then the ID:

Paging

Paging

To apply paging, use the paging query parameter.

To limit the number of records returned, use the limit parameter. For example:

To indicate the index of the first returned record, use theoffset parameter. For example:

To use these parameters together, separate them with a space:

These two values are useful for consumers that display the records in a paged format. The values can appear in either order.

If no limit is specified, the default is 50. To force the server to return every record, set the limit to zero '0' or ALL. For example:

If no offset is given, the default is zero '0'.