principal-list

Availability

Breeze 4 and Breeze 5; Connect Enterprise Web Services 6

Description

Provides a complete list of users and groups, including primary groups.

This call is useful for getting a principal-id when you don't have one. However, be aware that it returns a list of all principals on your Enterprise Server or in your Enterprise Hosted account, unless you use a filter to limit the response.

You can also use principal-list to get a list of groups in an account by filtering on the type and is-member fields:

https://example.com/api/xml?action=principal-list&filter-type=group
        &filter-is-member=true

However, filter-type=group returns groups you have created, not built-in groups predefined on the server. Built-in groups have type values other than group, such as admins and authors (see type for a list of the values).

You can filter the response with a filter-type parameter set to the type of group you want, then parse the response for a principal-id, then pass the principal-id as a group-id on another request to principal-list.

Request URL

http://server_name/api/xml
    ?action=principal-list
    &group-id=integer
    &filter-definition=value
    &sort-definition=value
    &session=BreezeSessionCookieValue

Parameters

Name	Type	Required	Description
`group-id`	Integer	N	The ID of a group. Same as the `principal-id` of a principal that has a `type` value of `group`.
`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.

You can also filter on a special field name, manager-id, to return a list of principals who report to a given manager, for example:

https://example.com/api/xml?action=principal-list
        &filter-manager-id=2006282569

When you use filter-manager-id, each principal element in the response has a manager-id attribute:

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code="ok" /> 
    <principal-list>
        <principal principal-id="2006258745" account-id="624520" type="user" 
                has-children="false" is-primary="false" is-hidden="false" 
                manager-id="2006282569">
            <name>Suzanne Alexandra</name> 
            <login>suzannea@adobe.com</login> 
            <email>suzannea@adobe.com</email> 
        </principal>
    </principal-list>
</results>

Response structure

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code=allowedValue /> 
    <principal-list>
        <principal principal-id=integer account-id=integer type=allowedValue 
                has-children=boolean is-primary=boolean is-hidden=boolean
                manager-id=integer>
            <name>string</name> 
            <login>string</login> 
            <email>string</email> 
        </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.
`principal`		Container	Details about one principal.
	`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 do not, so when `has-children` is `true`, the principal is a group.
	`is-primary`	Boolean	Whether the principal is a built-in group (`true`) or not (`false`).
	`is-hidden`	Boolean	Whether Enterprise Manager or your application displays the principal (`true` for not displayed and `false` for displayed).
	`manager-id`	Integer	The `principal-id` of the manager the principal reports to. Returned only if you use `filter-manager-id` in the request.
`name`		String	The principal's full name.
`login`		String	The principal's login ID, often an e-mail address.
`email`		String	The principal's e-mail address.
`principal-custom-field-values`		Container	The entire list of custom field values defined for the principal.
`field`		Container	Details about one custom field defined for the principal (see field for contents).

Sample request

https://example.com/api/xml?action=principal-list

Sample response

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code="ok" /> 
    <principal-list>
        <principal principal-id="624526" account-id="624520" type="user" 
                has-children="false" is-primary="false" is-hidden="false">
            <name>ned mack</name> 
            <login>nmack@acme.com</login> 
            <email>nmack@acme.com</email> 
        </principal>
        <principal principal-id="624550" account-id="624520" type="user" 
                has-children="false" is-primary="false" is-hidden="false">
            <name>amelie jones</name> 
            <login>amelie@example.com</login> 
            <email>amelie@example.com</email> 
        </principal>
        ...
    </principal-list>
</results>