principal-update

Availability

Breeze 4 and Breeze 5; Connect Enterprise Web Services 6

Description

Creates or updates a user or group. The user or group (that is, the principal) is created or updated in the same account as the user making the call.

To create a new principal, call principal-update without specifying a principal-id. To update, add the principal-id. Before you update metadata about a principal, call principal-info to get the existing version.

If a principal's information has custom fields, use acl-field-update to update them, rather than principal-update.

You need Administrator privileges to create or update a principal.

Request URL

http://server_name/api/xml
    ?action=principal-update
    &description=string
    &email=string
    &first-name=string
    &has-children=boolean
    &last-name=string
    &login=string
    &name=string
    &password=string
    &principal-id=integer
    &send-email=boolean
    &type=allowedValue
    &session=BreezeSessionCookieValue

Parameters

Name	Type	Required	Description
`description`	String	N	The new group's description. Use only when creating a new group.
`email`	String	N	The user's e-mail address. Can be different from the `login`. Be sure to specify a value if you use `send-email=true`.
`first-name`	String	Y/N	The user's new first name. Use only with users, not with groups. Required to create a user.
`has-children`	Boolean	Y	Whether the principal has children. If the principal is a group, use `1` or `true`. If the principal is a user, use `0` or `false`.
`last-name`	String	Y/N	The new last name to assign to the user. Required to create a user. Do not use with groups.
`login`	String	Y/N	The principal's new login name, usually the principal's e-mail address. Must be unique on the server. Required to create or update a user. Do not use with groups.
`name`	String	Y/N	The new group's name. Use only when creating a new group. Required to create a group.
`password`	String	N	The new user's password. Use only when creating a new user.
`principal-id`	String	Y/N	The ID of the principal that has information you want to update. Required to update a user or group, but do not use to create either.
`send-email`	Boolean	N	A flag indicating whether the server should send an e-mail to the principal with account and login information.
`type`	String	Y/N	The type of principal. Use only when creating a new principal (see type for values).
`session`	String	N	The value of the `BREEZESESSION` cookie. Use this parameter if you do not use a client-side cookie management library.

Filters

Results cannot be filtered or sorted.

Response structure

<?xml version="1.0" encoding="utf-8" ?> 
<results> 
    <status code=allowedValue /> 
    <principal principal-id=integer account-id=integer 
            has-children=integer type=integer> 
        <login>string</login> 
        <ext-login>string</ext-login> 
        <name>string</name> 
    </principal> 
</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`		Container	Information about the newly created principal.
	`principal-id`	Integer	The ID of the newly created user.
	`account-id`	Integer	The ID of the account the new user belongs to. Same as the account of the current user.
	`has-children`	Boolean	Whether the principal has children, which indicates whether the principal is a user or group (`1` if a group, or `0` if a user).
	`type`	Allowed value	The type of principal (see type for values).
`login`		String	The principal's login ID, often an e-mail address.
`ext-login`		String	The principal's external authentication ID. By default, the value is the same as login, unless you explicitly set the value to an authentication ID from your network.
`name`		String	The principal's name. If the principal is a user, concatenated from the `first-name` and `last-name` parameters in the request.

Sample request

https://example.com/api/xml?action=principal-update&first-name=jake
        &last-name=doe&has-children=0&login=jakedoe@example.com&type=user

Sample response

<?xml version="1.0" encoding="utf-8" ?> 
<results> 
    <status code="ok" /> 
    <principal principal-id="2006403978" account-id="624520" type="user"
            has-children="0"> 
        <login>jakedoe@example.com</login> 
        <ext-login>jakedoe@example.com</ext-login> 
        <name>jake doe</name> 
    </principal> 
</results>