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. The optional include request parameter can determine if ownedLevels or hiddenVersions is included in the response.
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"/> <include ownedLevels="true" hiddenVersions="false"/> </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 a role containing the permissions required for the method being invoked. |
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 |
|||
|
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 |
|
ownedLevels |
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 |
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>
<user id="19" guid="B9ADBCB81AA2F9BAE040307F02092C2E" login="analytica@fakecompany.com" email="analytica@fakecompany.com"
name="Anna Analyzer" roleId="3" ownedLevels="1" hiddenVersions="4" timeZone="US/Pacific"/>
<user id="123" guid="AAFF5218D55ABB9234660001BEC117A9" login="randomuser@fakecompany.com" email="randomuser@fakecompany.com"
name="J. Random User" roleId="2" ownedLevels="5,10,13" hiddenVersions="" 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 by Adaptive Planning. 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 |
|
|
(none) |
|
|
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 |
|
|
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 |
|
roleId |
Y |
The internal system ID of the role assigned to this user. See also exportRoles. |
3 |
|
ownedLevels |
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 |
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 |
|
timeZone |
Y |
The time zone of the user. |
US/Pacific |
|
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 |
|||