userService

Provides the ability to manage user accounts (also called simply "users"). Use this service to find, create, and update user accounts. You can manage user properties and disable a user account so that the person can no longer use the application.

For SOAP services this service can be accessed at /rpc/soap/UserService. For REST services this service can be accessed at /rpc/rest/users

Method	Description
createUser	Creates a new user account from a minimum of information: username, password, and email address.
createUserWithUser	Creates a new user account from user data.
deleteUserProperty	Deletes an extended property from the specified user account.
disableUser	Disables a user account.
enableUser	Enables a user account.
getUser	Returns the user specified by ID.
getUserByEmailAddress	Returns the user account corresponding to the specified email address.
getUserByUsername	Returns the user specified by username (case-insensitive).
getUserCount	Returns the number of users in the system.
getUserNames	Returns all of the userNames in the system.
getUserProperties	Returns the extended properties for the specified user account.
getUsers	Returns the IDs of the first 1000 users.
getUsersBounded	Returns the IDs of users begining at startIndex and until the number results equals numResults.
isReadOnly	Returns true if this UserService is read-only.
setPassword	Changes the specified user's password.
setUserProperty	Sets an extended property for the specified user.
updateUser	Updates information for the specified user.

createUser

Creates a new user account from a minimum of information: username, password, and email address.

POST http://domain:port/application_context/rpc/rest/userService/users/create

Arguments

Name	Type	Description
username	xs:string	The username (not the full name) for the new user account.
password	xs:string	The password for the user account.
email	xs:string	The user's email address.

Arguments Template

<createUser> 
    <username>xs:string</username>
    <password>xs:string</password>
    <email>xs:string</email>
</createUser>

Response

Type	Description
User	The newly created user.

Response Template

<createUserResponse> 
    <return>
        <!-- Contents of User -->
    <return>
</createUserResponse>

Errors

Error	When Returned
com.jivesoftware.base.UserAlreadyExistsException	If a user with this username already exists.
com.jivesoftware.base.EmailAlreadyExistsException
java.lang.UnsupportedOperationException	If the back-end user store doesn't support this operation.

createUserWithUser

Creates a new user account from user data. The ID field in the specified data is ignored, then assigned by the system when the account is created.

POST http://domain:port/application_context/rpc/rest/userService/users

Arguments

Name	Type	Description
user	Contents of User	Data with which to create the user account.

Arguments Template

<createUserWithUser> 
    <user>
        <!-- Contents of User -->
    <user>
</createUserWithUser>

Response

Type	Description
User	The newly created user; the ID field is ignored.

Response Template

<createUserWithUserResponse> 
    <return>
        <!-- Contents of User -->
    <return>
</createUserWithUserResponse>

Errors

Error	When Returned
com.jivesoftware.base.UserAlreadyExistsException	If a user with the specified username already exists.
com.jivesoftware.base.EmailAlreadyExistsException
Unauthorized	If the caller is not the same user or system admin.
java.lang.UnsupportedOperationException	If the back-end user store doesn't support this operation.

deleteUserProperty

Deletes an extended property from the specified user account.

DELETE http://domain:port/application_context/rpc/rest/userService/properties/{userID}/{name}

Arguments

Name	Type	Description
name	xs:string	Name of the property to delete.
userID	xs:long	ID of the user account from which to delete the property.

Arguments Template

<deleteUserProperty> 
    <name>xs:string</name>
    <userID>xs:long</userID>
</deleteUserProperty>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.
Unauthorized	If the caller is not the same user or system admin.

disableUser

Disables a user account.

PUT http://domain:port/application_context/rpc/rest/userService/disable

Arguments

Name	Type	Description
userID	xs:long	ID of the user account to disable.

Arguments Template

<disableUser> 
    <userID>xs:long</userID>
</disableUser>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.
Unauthorized	If not the system admin.

enableUser

Enables a user account.

PUT http://domain:port/application_context/rpc/rest/userService/enable

Arguments

Name	Type	Description
userID	xs:long	ID of the user account to enable.

Arguments Template

<enableUser> 
    <userID>xs:long</userID>
</enableUser>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.
Unauthorized	If the caller is not the system admin.

getUser

Returns the user specified by ID.

GET http://domain:port/application_context/rpc/rest/userService/usersByID/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user to get.

Arguments Template

<getUser> 
    <userID>xs:long</userID>
</getUser>

Response

Type	Description
User	The user with the matching ID.

Response Template

<getUserResponse> 
    <return>
        <!-- Contents of User -->
    <return>
</getUserResponse>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.

getUserByEmailAddress

Returns the user account corresponding to the specified email address.

GET http://domain:port/application_context/rpc/rest/userService/usersByEmail/{emailAddress}

Arguments

Name	Type	Description
emailAddress	xs:string	The email address of the user.

Arguments Template

<getUserByEmailAddress> 
    <emailAddress>xs:string</emailAddress>
</getUserByEmailAddress>

Response

Type	Description
User	The user with the specified email address.

Response Template

<getUserByEmailAddressResponse> 
    <return>
        <!-- Contents of User -->
    <return>
</getUserByEmailAddressResponse>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.

getUserByUsername

Returns the user specified by username (case-insensitive).

GET http://domain:port/application_context/rpc/rest/userService/users/{username}

Arguments

Name	Type	Description
username	xs:string	The user's username (case-insensitive).

Arguments Template

<getUserByUsername> 
    <username>xs:string</username>
</getUserByUsername>

Response

Type	Description
User	The user matching the username.

Response Template

<getUserByUsernameResponse> 
    <return>
        <!-- Contents of User -->
    <return>
</getUserByUsernameResponse>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.

getUserCount

Returns the number of users in the system.

GET http://domain:port/application_context/rpc/rest/userService/users/count

Response

Type	Description
xs:int	The number of users in the system.

Response Template

<getUserCountResponse> 
    <return>xs:int</return>
</getUserCountResponse>

getUserNames

Returns all of the userNames in the system.

GET http://domain:port/application_context/rpc/rest/userService/userNames

Response

Type	Description
List of	An array of user names.

Response Template

<getUserNamesResponse> 
    <!-- List of ... -->
    <return>xs:string</return>
</getUserNamesResponse>

getUserProperties

Returns the extended properties for the specified user account.

GET http://domain:port/application_context/rpc/rest/userService/properties/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user account for which to get properties.

Arguments Template

<getUserProperties> 
    <userID>xs:long</userID>
</getUserProperties>

Response

Type	Description
List of Property	A list of the user's extended properties.

Response Template

<getUserPropertiesResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of Property -->
    <return>
</getUserPropertiesResponse>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.

getUsers

Returns the IDs of the first 1000 users.

GET http://domain:port/application_context/rpc/rest/userService/users

Response

Type	Description
List of User	An array of user IDs.

Response Template

<getUsersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getUsersResponse>

getUsersBounded

Returns the IDs of users begining at startIndex and until the number results equals numResults.

GET http://domain:port/application_context/rpc/rest/userService/usersBounded/{startIndex}/{numResults}

Arguments

Name	Type	Description
startIndex	xs:int	The startIndex to grab results from.
numResults	xs:int	The total number of results to be returned.

Arguments Template

<getUsersBounded> 
    <startIndex>xs:int</startIndex>
    <numResults>xs:int</numResults>
</getUsersBounded>

Response

Type	Description
List of User	An array of user IDs.

Response Template

<getUsersBoundedResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getUsersBoundedResponse>

isReadOnly

Returns true if this UserService is read-only. When read-only, users can not be created, deleted, or modified.

GET http://domain:port/application_context/rpc/rest/userService/isReadOnly

Response

Type	Description
xs:boolean	true if the user provider is read-only.

Response Template

<isReadOnlyResponse> 
    <return>xs:boolean</return>
</isReadOnlyResponse>

setPassword

Changes the specified user's password.

PUT http://domain:port/application_context/rpc/rest/userService/password

Arguments

Name	Type	Description
userID	xs:long	ID of the user whose password is being changed.
password	xs:string	The new password in plain text.

Arguments Template

<setPassword> 
    <userID>xs:long</userID>
    <password>xs:string</password>
</setPassword>

Errors

Error	When Returned
UserNotFound	If the user could not be found.
com.jivesoftware.base.UserAlreadyExistsException
Unauthorized	If the caller is not the same user or system admin.

setUserProperty

Sets an extended property for the specified user.

POST http://domain:port/application_context/rpc/rest/userService/properties

Arguments

Name	Type	Description
name	xs:string	The property's name.
value	xs:string	The property's value.
userID	xs:long	ID of the user account for which to the property.

Arguments Template

<setUserProperty> 
    <name>xs:string</name>
    <value>xs:string</value>
    <userID>xs:long</userID>
</setUserProperty>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.
Unauthorized	If the caller is not the same user or system admin.

updateUser

Updates information for the specified user.

PUT http://domain:port/application_context/rpc/rest/userService/users

Arguments

Name	Type	Description
user	Contents of User	User information to update.

Arguments Template

<updateUser> 
    <user>
        <!-- Contents of User -->
    <user>
</updateUser>

Errors

Error	When Returned
UserNotFound	If the specified user does not exist.
com.jivesoftware.base.UserAlreadyExistsException	If this update attempts to change user information to a user account that already exists.
Unauthorized	If the caller is not the same user or a system admin.