principal-list-by-field

Availability

Breeze 5; Connect Enterprise Web Services 6

Description

Lists principals that have a specified value in any field.

In the value parameter, enter the value of a 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 database fields defined for the principal, including custom fields.

Request URL

http://server_name/api/xml
    ?action=principal-list-by-field
    &value=string
    &filter-definition=value
    &sort-definition=value
    &session=BreezeSessionCookieValue

Parameters

Name	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 fields.
`principal`		Container	One principal that matches the value.
	`principal-id`	Integer	The ID of the principal.
	`account-id`	Integer	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=bob

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>