Name
Last updated on
May 15, 2021
Use principal-list-by-field to query the custom fields and find principals that have a specific value in a custom field.
Availability
Breeze 5
Description
Lists principals that have a specified value in a custom field. Use this action to query custom fields for principals. Use principal-list to get a list of custom fields that are defined for the principal.
In the value parameter, enter the value of a custom database field. The name element returned by principal-list, for example, is a full name concatenated from the first-name (bob) and last-name (jones) database fields. If you search on bob jones, principal-list-by-field does not return a value, unless the full name is defined as a database field (in this case, a custom field defined on principals).
The search is case insensitive, and the query string can contain spaces.
Wildcards are not allowed in the query string. For example, if you enter t*, principal-list-by-field searches for the exact string t*.
The principal-list-by-field action searches in all custom database fields defined for the principal; it does not search principal fields.
Request URL
http://server_name/api/xml ?action=principal-list-by-field &value=string &filter-definition=value &sort-definition=value &session=BreezeSessionCookieValue
Parameters
|
|
Type |
Required |
Description |
|
value |
String |
Y |
The value for which you want to search all fields. You do not need to enter a field name. |
|
filter-definition |
Filter definition |
N |
A filter to reduce the volume of the response. |
|
sort-definition |
Sort definition |
N |
A sort to return results in a certain sequence. |
|
session |
String |
N |
The value of the BREEZESESSION cookie. Use this parameter if you do not use a client-side cookie management library. |
Filters
You can filter or sort the response on any element or attribute it contains.
Response structure
<?xml version="1.0" encoding="utf-8" ?> <results> <status code=allowedValue /> <principal-list> <principal account-id=integer principal-id=integer type=allowedValue has- children=boolean is-primary=boolean is-hidden=boolean> <name>string</name> <login>string</login> </principal> </principal-list> </results>
Response values
Element |
Attribute |
Type |
Description |
|---|---|---|---|
| results | Container |
All results the action returns. |
|
| status | Empty, with attributes |
The status of the response. |
|
| code | Allowed value |
A code indicating the response status (see status). |
|
| principal-list | Container |
The entire list of principals that match the value in one or more custom fields. |
|
| principal | Container |
One principal that matches the value. |
|
| principal-id | BIGINT |
The ID of the principal. |
|
| account-id | BIGINT |
The ID of the account the principal belongs to. |
|
| type | Allowed value |
The type of principal (see type for values). |
|
| has-children | Boolean |
Indicates whether the principal has children. Groups have children and users don’t, so this attribute indicates whether the principal is a group. |
|
| is-primary | Boolean |
Whether the principal is a built-in group (true) or not (false). |
|
| is-hidden | Boolean |
Whether the principal is hidden in the user interface (true) or not (false). |
|
| name | String |
The principal’s full name, concatenated from the first-name and last-name fields. |
|
| login | String |
The principal’s login ID, often an e-mail address. |
Sample request
https://example.com/api/xml?action=principal-list-by-field&value=inactive
Sample response
<?xml version="1.0" encoding="utf-8" ?> <results> <status code="ok" /> <principal-list> <principal account-id="624520" principal-id="2616099" type="user" has-children="false" is-primary="false" is-hidden="false"> <name>Bob Jones</name> <login>bjones@acme.com</login> </principal> </principal-list> </results>
See also
