GetUsers

Description

This service returns one or more users.

Arguments

Argument	Type	Description
auth (optional)	Auth	The Auth type supplies credentials and optionally, a host name for licensing. The userId and password can be specified with HTTP BASIC or WS-SECURITY instead.
getCurrentUser	boolean	Specify true to return user info for the user specified in the auth argument of the GetUsers call. Specify false to use the other arguments to return users instead. Default value is false.
searchByName	string	Used to specify the name of the user as a search parameter.
user	UserIdentifier	Used to return a specific user or list of users. Specify multiple UserIdentifiers to return multiple users.
options	UserResponseOptions	Specifies whether the service should continue if an error is encountered or stop. Also enables you to limit the data that is returned in the response.

Response

UserHolder is returned. The UserHolder response contains one or more UserIdentifiers and additional information from the users preferences. For more specific information, see UserHolder.

Usage

The GetUsers call is useful when you need data about a user account. The GetUsers call retrieves data for a user account as it exists in the TS_USERS table of the database. To retrieve privileges for a given user account, use GetUserPrivileges. To determine if a specific user has a given privilege, use HasUserPrivilege.

Use the following arguments to determine which users are returned in the response:

getCurrentUser – Enables you to specify whether the service should only return user information for the user that is making the call. If you set getCurrentUser to true, the current user is returned, regardless of the data sent in the searchByName and user arguments.
searchByName – Enables you to enter a single string to return user accounts. For example, if you enter Joe as the searchByName value, user records with following display names are returned: Joe, Joel, Joey. You can not enter multiple strings. The searchByName argument is ignored if getCurrentUser is set to true or if a UserIdentifier is specified in the user argument.
Note: To return all user records in the database, leave getCurrentUser set to false, do not provide a value for searchByName, and do not enter specific UserIdentifiers in the user argument. If you have a large number of users in your database, consider limiting the return data using one or more arguments.
user – Enables you to specify one or more specific user accounts to be returned. If you want to return multiple users, you must specify each desired user by providing the UserIdentifier in a list of multiple user arguments. The user argument takes precedence over the searchByName argument.

Use the following elements in the options parameter to control how this call is processed and what data is returned:

multiOption – Enables you to specify whether the service should continue if an error is encountered, or stop and throw an error. If any failures occur, each successive error message is appended to the string that is returned. Multiple error messages are separated by a single newline. Failures do not result in a return before all users have been processed.
sections and specifiedSections – Enables you to specify which parts of a user record should be returned. This allows you to limit the data that is returned for a given user. The sections that aren't specified are not included in the response. For example, if you only need basic user information in the response, use the sections parameter to return only the STANDARD section.

For more information on the options elements, see UserResponseOptions.

Faults

Invalid database pointer.
The user ID is not valid.
The user lacks sufficient permission.

XML

The following XML is a snippet of the payload this is sent with GetUsers. In this example, searchByName is used to find all users with the string Joe in the user login ID.

<urn:GetUsers>
   <urn:auth>
      <urn:userId>Admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:getCurrentUser></urn:getCurrentUser>
   <urn:searchByName>Joe</urn:searchByName>
   <urn:user>
      <urn:displayName></urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
      <urn:loginId></urn:loginId>
   </urn:user>
</urn:GetUsers>

In this example, getCurrentUser is empty (or false), searchByName is left empty, and no user is provided in the user argument. This call returns all the users in the system.

<urn:GetUsers>
   <urn:auth>
      <urn:userId>Admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:getCurrentUser></urn:getCurrentUser>
   <urn:searchByName></urn:searchByName>
   <urn:user>
      <urn:displayName></urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
      <urn:loginId></urn:loginId>
   </urn:user>
</urn:GetUsers>