principal-list

Last updated on May 15, 2021

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>

Adobe

Get help faster and easier

New user?

principal-list

Get help faster and easier

Ask the Community

Contact Us