exportLevels
This API only supports user access rules in API v22 and above.
Category |
Metadata retrieval |
Description |
Returns metadata for the complete list of all organization levels in the system. |
Permissions Required To Invoke |
None (must be valid credentials for the instance) |
Parameters Required On Request |
Credentials |
This method's request contains a credentials tag to identify and authorize the calling user and an optional include tag to indicate which levels to include in the response. Once the user credentials are verified, the method returns an XML document describing the set of organization levels in the system corresponding to the request. Levels are returned in a nested tree fashion, with one level tag enclosing another if the level represented by the enclosing tag is the parent of the enclosed level.
Level Filtering
- Unavailable level/version filtering always applies when a version is specified.
- If a user specifies a user-assigned sheet in the request:
- Levels return if the user does have access to that sheet. For admin users, if
inaccessibleValues
is true, then levels will return for the sheet. - All levels on the sheet return if the user has access to the sheet, regardless of the user's level access.
- Levels return if the user does have access to that sheet. For admin users, if
- If a user specifies a level-assigned sheet in the request:
- User-access filtering applies when required by
inaccessibleValues,
which determines if the response should include levels the user has no access to. - Then, sheet filtering gets applied.
- User-access filtering applies when required by
Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="exportLevels" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <include versionID="3" inaccessibleValues="false"/> <sheet id="3" /> </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 his- tory 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 levels' information should be included or excluded from the response. This element is optional: if not present, the default value is false for inaccessibleValues, and blank (or all versions) for versionName/versionID. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
groups Available in API v23+ |
N | Indicates if the level elements in the response includes a groupIds attribute. If true, the groupIds in the response contains a comma-separated list of all groups the level 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 |
inaccessibleValues Available in API v18+. |
N |
Whether the response should include levels to which the user has no access. Either true or false. The default, if the element or its attribute is not present, is false. If set to false, the response will only include levels to which the user has data access, either direct or implied. Note that this means the response may no longer be a single rooted tree of levels, but may be a series of disjoint subtrees of the overall tree. Only users with the "Organization Structure: All Levels" or "Import to all levels" permissions may set this option to true. |
false |
inaccessibleLevels Available in API v17 and earlier. |
N |
Either true or false. Whether the response should include levels to which the user has no access. The default, if the element or its attribute is not present, is true. If set to false, the response will only include levels to which the user has data access, either direct or implied. Note that this means the response may no longer be a single rooted tree of levels, but may be a series of disjoint subtrees of the overall tree. |
true |
versionName Updated in API v18 |
N |
Indicates whether the response should only include levels which are available for the requested version name. The default, if the element or its attribute is not present, is to return all levels. If a version name is specified, only levels which are available for the specified version will be returned. If present, the inaccessibleValues attribute will also be applied, and only levels which are available in the specified version and accessible by the requesting user will be returned. If the specified version name is not found, this API returns an error. If both versionName and versionID attributes are passed, the versionID is ignored. When specifying a version, the call will succeed only if the user has access to the version. |
Engineering |
versionID Updated in API v18 |
N |
Same as versionName (above) except taking a version ID number as a parameter. Indicates whether the response should only include levels which are available for the requested version. The default, if the element or its attribute is not present, is to return all levels. If a version ID is specified, only levels which are available for the specified version will be returned. If present, the inaccessibleValues attribute will also be applied, and only levels which are available in the specified version and accessible by the requesting user will be returned. If the specified version ID is not found, this API returns an error. If both versionName and versionID attributes are passed, the versionID is ignored. When specifying a version, the call will succeed only if the user has access to the version. |
3 |
uncategorized Supported in API v22+ when the instance uses Access Rules for security. |
N | Indicates whether to include the phantom levels in the response. Defaults to false. The phantom levels are included in the response only when the user has access to them. | false |
Contents of the Element |
|||
(none) |
sheet element |
|||
Tag Name |
sheet |
||
Description |
Represents a sheet, where only levels available for that sheet will be included in the response. This element is optional: if not present, the API will return level information independent of a particular sheet. If the given sheet is a level-assigned sheet, this filtering would be applied on top of the version and user access filtering, if present. If the given sheet is a user-assigned sheet to which the current user has access, then all levels on that sheet after any version filtering will be returned. | ||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
id |
Y |
The internal system ID number for the sheet. |
234 |
Contents of the Element |
|||
(none) |
Response Format
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <levels seqNo="21"> <level id="1" name="Corporate Rollup" currency="USD" isImportable="1" workflowStatus="I"> <level id="2" name="Engineering" currency="USD" shortName="Engr" isImportable="1" workflowStatus="I"> <level id="7" name="Development" currency="USD" shortName="Dev" isImportable="1" workflowStatus="I"/> <level id="8" name="QA" currency="INR" isImportable="0" workflowStatus="L"/> <level id="9" name="Documentation" currency="PKR" shortName="Doc" isImportable="1" workflowStatus=R"/> </level> <level id="3" name="Professional Services" currency="USD" shortName="Prof.Srv" isImportable="0" workflowStatus="A"> <attributes> <attribute name="Corporate Discount" value="Available" attributeId="20" valueId="188" /> <attribute name="Transfers Restricted" value="Yes" attributeId="21" valueId="194" /> </attributes> </level> </level> </levels> </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. |
levels element |
|||
Tag Name |
levels |
||
Description |
Container for the level element. |
||
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 level elements. If the request includes inaccessible levels, there will be only one level element, which represents the top level of the organization. |
level element |
|||
Tag Name |
level |
||
Description |
Represents a single organization level being returned in the response to an exportLevels API call. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
id |
Y |
The internal system ID number for the level. |
7 |
name |
Y |
The name of the level, as it appears on reports and sheets. |
Development |
currency |
Y |
The currency code for the currency assigned to this level of the organization. The currency will be one of the configured currencies for the instance, found in the exportActiveCurrencies call. |
INR |
publishCurrency Available in API v24+ |
N | The currency code for the currency assigned to publish from this level. This property is only applicable when Power of one has been enabled for the instance. The currency will be one of the configured currencies for the instance, found in the exportActiveCurrencies call. | USD |
shortName |
N |
The abbreviation for the level, if any, as entered in Organization Administration. |
Dev |
availableStart |
N |
The start time period for the availability of level for actuals version, applicable only when ACTUALS version is specified in the request. The value can be either a time period code, such as "01/2012" or the special value "START" indicating the start of the version. |
01/2013 |
availableEnd |
N |
The end time period for the availability of level for actuals version, applicable only when ACTUALS version is specified in the request. The value can be either a time period code, such as "12/2013", or the special value "END" indicating the end of the version. |
12/2013 |
isImportable |
N |
Indicates if the associated level is importable in the specified version. '0' means it is not importable and '1' means it is importable. A level is importable if at least one timeslot in the specified version is importable. isImportable attribute is only emitted if versionName or versionID is specified in the request. Note: isImportable only indicates that a level is available for import in the specified version, not that the user making the API call has the permission to import into the version or level. Use exportVersions to see which versions are available to the user for import. |
1 |
workflowStatus |
N |
Emits the workflow status for the associated level. I for "In Progress", S for "Submitted", R for "Rejected", A for "Approved" and L for "Locked". Only included in the response if workflow is enabled for this company, and a planning versionName or versionID is specified in the request. Workflow is not available on actuals versions. |
I |
isLinked |
Y |
1 if the level is a linked level; otherwise, 0. |
1 |
isElimination |
Y |
1 if the level is an elimination level; otherwise, 0. |
0 |
hasChildren |
N |
Indicates whether the level has children. "false" for no, "true" for yes. This attribute is set for any level that has children, independent of the children being accessible or not. If a level has children but the children are not accessible, the hasChildren attribute is still set to true. |
true |
Contents of the Element |
|||
One nested level element for each direct child level of this level. |
attributes element |
|||
Tag Name |
attributes |
||
Description |
Container for one or more attribute elements. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
(none) |
|||
Contents of the Element |
|||
One or more attribute elements. |
attribute element |
|||
Tag Name |
attribute |
||
Description |
Represents a single non-blank level attribute mapping to which a level is associated. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the level attribute |
Corporate Discount |
value |
Y |
The value of the level attribute associated with the level. |
Yes |
attributeID |
Y |
The internal system id number of the level attribute. |
20 |
valueID |
Y |
The internal system id number of the level attribute value. |
188 |
Contents of the Element |
|||
(none) |