exportUsers
Category | Metadata retrieval |
Description | Returns metadata for the complete list of all users in the instance. |
Permissions Required To Invoke | User Admin |
Parameters Required On Request | Credentials |
This method's request contains only a credentials tag to identify and authorize the calling user. Once verified, the method returns an XML document describing the complete set of all users defined in the instance.
Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="exportUsers" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> </call>
credentials element | |||
Tag Name | credentials | ||
Description | All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user (any audit trail or history of actions in the system will show that this user performed the action), and therefore the user must have the required permissions to perform the action in order for the API call to succeed. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
login | Y | The login name of the user invoking the API method. This user must have the required permissions to invoke the method. | sampleuser@company.com |
password | Y | The password of the user invoking the API method. | my_password |
locale | N | Specify the locale to be used to interpret incoming numbers and dates, and to format outgoing numbers and dates (using the proper thousands separator, month names, and date formatting). The locale is also used to specify the language in which any system messages in the response should appear. If not specified, en_US (American English) is used. | fr_FR |
instanceCode | N | If the user specified in the credentials has access to more than one instance of Adaptive Planning , this attribute can be used to specify that the user is intending to access an instance other than their default instance. If not specified, the user's default instance will be used. To determine the available instance codes, use the exportInstances API. | MYINSTANCE1 |
Contents of the Element | |||
(none) | |||
include element Available in API v17 and earlier. Not available in API v18+. | |||
Tag Name | include | ||
Description | Represents a set of flags indicating what aspects of the users' information should be included or excluded from the response. This element is optional: if not present, the default values are true for ownedLevels and false for hiddenVersions. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
groups Available in API v23+. | N | Either the word true or false. Indicates if the user elements in the response includes a groupIds attribute. If true, the groupIds in the response contains a comma-separated list of all groups the user is in. If the attribute is not present, or if its value is something other than true or false, the default value of false is used. | true |
ownedLevels Available in API v17 and earlier. Not available in API v18+. | N | Either the word true or false. Indicates if the user elements in the response should include ownedLevels attributes or not. If the attribute is not present, or if its value is something other than true or false, the default value of true is used. | true |
hiddenVersions Available in API v17 and earlier. Not available in API v18+. | N | Either the word true or false. Indicates if the user elements in the response should include hiddenVersions attributes or not. If the attribute is not present, or if its value is something other than true or false, the default value of false is used. | false |
Contents of the Element | |||
(none) | |||
Response Format
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <users seqNo="55"> <user id="19" guid="B9ADBCB81AA2F9BAE040307F02092C2E" login="analytica@fakecompany.com" email="analytica@fakecompany.com" name="Anna Analyzer" permissionSetId="3" timeZone="US/Pacific"/> <user id="123" guid="AAFF5218D55ABB9234660001BEC117A9" login="randomuser@fakecompany.com" email="randomuser@fakecompany.com" name="J. Random User" permissionSetId="2" timeZone="US/Pacific"/> </users> </output> </response>
response element | |||
Tag Name | response | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
success | Y | Either true or false, indicating whether the API call was successful or not. Even successful calls may contain warning messages in their response. | true |
obsolete | N | If present on the response tag and set to true, this attribute indicates that the version of the method or API which is being invoked has become obsolete and is officially deprecated. While it continues to function at this time, it may cease functioning in a short while. Typically, this attribute is not present. | false |
Contents of the Element | |||
A single optional messages element, and exactly one required output element. | |||
output element | |
Tag Name | output |
Attributes of the Element | |
(none) | |
Contents of the Element | |
A single accounts element. This output wrapper is standard on all API responses and encloses the valid output of any successful API call. | |
users element | |||
Tag Name | users | ||
Description | Container for one or more user elements. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
seqNo Added in API v17 but reserved for future use. | |||
Contents of the Element | |||
One or more user elements. | |||
user element | |||
Tag Name | user | ||
Description | Represents a single user being returned in the response to an exportUsers API call. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | Y | The internal system ID number for the user. | 19 |
guid | Y | A globally-unique identifier for the user. This identifier will never change for this user, even if their login or name changes in the future. | B9ADBCB81AA2F9BAE040307F02092C2E |
login | Y | The login for this user. | analytica@fakecompany.com |
email | Y | The email address for this user. May be blank if the user has not configured a valid email address. | analytica@fakecompany.com |
name | Y | The name of this user. | Anna Analyzer |
position
Available in API v39+ | N | Position for user. | "CEO" |
permissionSetId Available in API v25+ Not available in API v36+ | Y | The internal system ID of the permission set assigned to this user. See also exportPermissionSets. | |
permissionSetIds
Available in API v36+ | Y | The internal system IDs of the permission sets assigned to this user. See also exportPermissionSets. | |
roleId Available in API v25 and older Not Available in API v25+ | Y | The internal system ID of the role assigned to this user. See also exportRoles. | 3 |
ownedLevels Not available in API v18 | Y | This attribute is only included if the user included in the request's credentials has Level Admin permission to the entire Organization tree and the request has indicated that ownedLevels should be included. If included, this attribute's value is a comma-separated list of internal system IDs for organization levels to which this user has been granted direct access. The user will also have access to any child levels of the levels listed here | 5,10,13 |
hiddenVersions Not available in API v18 | N (see description) | This attribute is only included if the user included in the request's credentials has Version Admin permission and the request has indicated that hiddenVersions should be included. If included, this attribute's value is a comma-separated list of internal system IDs for versions or version folders which are hidden from this user (but whose parent is either nonexistent or not hidden). The user will also not be able to see any child versions of the versions listed here. | 121 |
alternateEmail
Available in API v39+ | N | The alternate email address for this user. | "abc@greenco.com" |
samlFedId
Available in API v39+ | N | The SAMLFederation ID for this user. | "1234" |
timeZone | Y | The time zone of the user. | US/Pacific |
homepage
Available in API v39+ | N | Homepage for user. | "Welcome" |
country
Available in API v39+ | N | Country code for user (alpha-2 code). | "US" |
usState
Available in API v39+ | N | State code for user (country has to be US). | "CA" |
perspective
Available in API v39+ | N | Perspective ID for user. | "111" |
perspectiveName
Available in API v39+ | N | Perspective name of the user's perspective. | "Test Perspective" |
dashboard
Available in API v39+ | N | Dashboard ID for user - requires perspective ID to set dashboard ID, if perspective ID is specified and dashboard ID is not then dashboard ID is set to null. | "222" |
dashboardName
Available in API v39+ | N | Dashboard name of the user's dashboard. | "Test Dashboard" |
netsuiteLogin
Available in API v39+ | N | Netsuite login. | "abc@netsuite.com" |
salesforceLogin
Available in API v39+ | N | Salesforce login. | "abc@salesforce.com" |
createdDate
Available in API v39+ | N | Datetime timestamp the user was created. | "2023-08-15 08:02:16.0" |
lastLogin
Available in API v39+ | N | Datetime timestamp of the last time the user logged in. | "2023-11-13 22:22:39.0" |
failedAttempts
Available in API v39+ | N | Number of failed login attempts for this user (consecutive). | "0" |
locked
Available in API v39+ | N | Whether the user is locked/can't be logged into (due to too many failed logins). | "false" |
Contents of the Element | |||
One subscriptions element. | |||
subscriptions element | |||
Tag Name | subscriptions | ||
Description | Represents the email subscription settings for a user. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
nosubscriptions | Y | Setting to signal user has opted out of all subscriptions. 1 means user has opted out of all subscriptions. | 0 |
systemAlertsAndUpdates | Y | Setting for system alerts and updates subscription opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
customerNewsLetter | Y | Setting for the customer news letter subscription opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
localEvents | Y | Setting for the local events subscription opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
educationTraining | Y | Setting for the education and training events subscription opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
customerWebinars | Y | Setting for the customer webinar events subscription opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
newProductsAndEnhancements | Y | Setting for new product and enhancements notification opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
partnerNewsLetter | Y | Setting for the partner newsletters subscription opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
partnerWebinars | Y | Setting for the partner webinar events subscription opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
userGroups | Y | Setting for user groups events notification opted by the user. 1 means user has opted in and 0 means he has opted out. | 1 |
surveys | Y | Setting for receiving surveys opted by the user. 1 means user has opted in and 0 means he has opted out. | 0 |
Contents of the Element | |||
none | |||