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

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 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

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy