Variable	Description
api2_filter (boolean)	This variable is the switch to enable filtering. To enable filtering, you must set this variable to `1`.
api2_filter_column (string)	The filter's column allows you to specify the field on which you wish to perform an operation.
api2_filter_term (string)	The filter's term allows you to specify a value against which the field (column) will be checked.
api2_filter_type (string)	This value allows you to pick an operation to perform against the filter's column. See Available filter types below for more information.

Available filter types

Filter Type	Description
eq	Isolates results that are equal to the filter's term.
lt	Isolates results that are less than the filter's term. This operator does not handle unlimited values.
lt_handle_unlimited	Isolates results that are less than the filter's term. This operator will handle unlimited values.
gt	Isolates results that are greater than the filter's term. This operator does not handle unlimited values.
gt_hnadle_unlimited	Isolates results that are greater than the filter's term. This operator will handle unlimited values.
contains (default)	Isolates results whose field (column) contains a given string. This is the default value for `api2_filter_type`.

Examples

Using filters with XML API fast mode

For example, if you were going to filter the results of the listpopswithdisk call made via XML API's fast mode, you could use the following:

https://example.com:2083/xml-api/cpanel?cpanel_xmlapi_apiversion=2&cpanel_xmlapi_user=user&cpanel_xmlapi_module=Email&cpanel_xmlapi_func=listpopswithdisk&api2_filter=1&api2_filter_column=diskquota&api2_filter_term=350&api2_filter_type=lt_handle_unlimited

This call will execute listpopswithdisk and filter the results to only show email accounts with disk quotas under 350 MB.

In the example above:

Variable and Value	Description
api2_filter=1	Enables the filter.
api2_filter_column=diskquota	Ensures that the operator (set by the filter's type) is performed on the `diskquota` field (column).
api2_filter_term=350	Sets the filter's term value to 350. This is the value against which the operator will check the field's (column's) value.
api2_filter_type=lt_handle_unlimited	Sets the operator to `less than` with the ability to handle unlimited values.

Click to see an example of the function's output... Hide...

<data>
   <_diskquota>262144000</_diskquota>
   <_diskused>0</_diskused>
   <diskquota>250</diskquota>
   <diskused>0</diskused>
   <diskusedpercent>0</diskusedpercent>
   <diskusedpercent20>0</diskusedpercent20>
   <domain>example.com</domain>
   <email>cora@example.com</email>
   <humandiskquota>250 MB</humandiskquota>
   <humandiskused>None</humandiskused>
   <login>cora@example.com</login>
   <mtime>1283966437</mtime>
   <txtdiskquota>250</txtdiskquota>
   <user>cora</user>
</data>
<data>
   <_diskquota>157286400</_diskquota>
   <_diskused>23035598</_diskused>
   <diskquota>150</diskquota>
   <diskused>21.97</diskused>
   <diskusedpercent>14</diskusedpercent>
   <diskusedpercent20>20</diskusedpercent20>
   <domain>example.com</domain>
   <email>jane@example.com</email>
   <humandiskquota>150 MB</humandiskquota>
   <humandiskused>21.97 MB</humandiskused>
   <login>jane@example.com</login>
   <mtime>1283966451</mtime>
   <txtdiskquota>150</txtdiskquota>
   <user>jane</user>
</data>

Using filters with <?cp tags

We have selected to use the listpopswithdisk function in the following example:

<?cp Email::listpopswithdisk([strong]%[/strong] - %[br], email, diskquota) api2_filter=1, api2_filter_column=diskquota, api2_filter_term=350, api2_filter_type=unlimited  ?>

This call will execute listpopswithdisk and filter the results to only show email accounts with disk quotas under 350 MB. It will also filter the output (using the <?cp tag) so that it will only show the email and diskquota fields.

In the example above:

Variable and Value	Description
api2_filter=1	Enables the filter.
api2_filter_column=diskquota	Ensures that the operator (set by the filter's type) is performed on the `diskquota` field (column).
api2_filter_term=350	Sets the filter's term value to 350. This is the value against which the operator will check the field's (column's) value.
api2_filter_type=lt_handle_unlimited	Sets the operator to `less than` with the ability to handle unlimited values.

The output for this function should resemble the following:

user0@example.com - 150
user1@example.com - 250
user2@example.com - 300

Note: We have also filtered the results in this example by using <cp? tags. For more information about using <cp? tags, visit our documentation.

Using filters with <?cptt tags

We have selected to use the listpopswithdisk function in the following example:

<?cptt Email::listpopswithdisk(template.tmpl) api2_filter=1, api2_filter_column=diskquota, api2_filter_term=350, api2_filter_type=unlimited  ?>

This call will execute listpopswithdisk and filter the results to only show email accounts with disk quotas under 350 MB. It will also filter the output using the template specified (template.tmpl) so that it will only show the email and diskquota fields.

In the example above:

Variable and Value	Description
api2_filter=1	Enables the filter.
api2_filter_column=diskquota	Ensures that the operator (set by the filter's type) is performed on the `diskquota` field (column).
api2_filter_term=350	Sets the filter's term value to 350. This is the value against which the operator will check the field's (column's) value.
api2_filter_type=lt_handle_unlimited	Sets the operator to `less than` with the ability to handle unlimited values.

The output for this function should resemble the following:

user0@example.com - 150
user1@example.com - 250
user2@example.com - 300

Note: We have also filtered the results in this example by using <cptt? tags. For more information about using <cptt? tags, visit our documentation.

Using multiple filters

You can use multiple filters on a single API2 call. You will need to append an underscore and a number to the end of each filter variable, beginning with _0. You will need to increment the trailing number of each variable by 1 for each new filter you wish to use. For example:

https://example.com:2083/xml-api/cpanel?cpanel_xmlapi_apiversion=2&cpanel_xmlapi_user=user&cpanel_xmlapi_module=Email&cpanel_xmlapi_func=listpopswithdisk&api2_filter=1&api2_filter_type_0=gt_handle_unlimited&api2_filter_column_0=quota&api2_filter_term_0=100&api2_filter_type_1=contains&api2_filter_column_1=email&api2_filter_term_1=com

From the example above:

Incremented Variable Name and Value	Description
api2_filter=1	Enables the filter.
api2_filter_type_0=gt_handle_unlimited	Set's the first filter's operator to `greater than`.
api2_filter_column_0=quota	Set's the first filter's column value to `quota`.
api2_filter_term_0=100	Set's the first filter's term value to `100`.
api2_filter_type_1=contains	Set's the second filter's operator to `contains`.
api2_filter_column_1=email	Set's the second filter's column to `email`.
api2_filter_term_1=com	Set's the second filter's term to `com`.

In this example, we can see that the first filter isolates results having a quota that is greater than 100, while the second filter isolates results having an email field that contains com.

Topic revision: r6 - 08 Sep 2010 - 21:09:31 - Main.JustinSchaefer

AllDocumentation/AutomationIntegration.Api2Filtering moved from Sandbox.Api2Filtering on 08 Sep 2010 - 21:09 by Main.JustinSchaefer