Availability

Breeze 4

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 Adobe Connect Server or Adobe Connect 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

BIGINT

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.

Note:

Filtering on the login element is useful but slow, and reduced performance is unavoidable.

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>Pat Lee</name>  
             <login>plee@mycompany.com</login>  
             <email>plee@mycompany.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 training-group-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

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 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 Connect Central or your application displays the principal (true for not displayed and false for displayed).

manager-id

BIGINT

The principal-id of the manager the principal reports to. Returned only if you use filter-manager-id in the request.

training-group-id=

BIGINT

The ID of the training group.

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" training-group-id=""> 
             <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" training-group-id=""> 
             <name>amelie jones</name>  
             <login>amelie@example.com</login>  
             <email>amelie@example.com</email>  
         </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