exportVersions
Updated in API v40. (September 21, 2024).
This API only supports user Concept: Access Rules in API v22 and above.
Category | Metadata retrieval |
Description | Once verified, the method returns an XML document describing the set of all versions defined in the instance which are not hidden from the requesting user. |
Permissions Required To Invoke | None (must be valid credentials for the instance) |
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 set of all versions defined in the instance which are not hidden from the requesting user.
Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="exportVersions" 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 | |||
Tag Name | include | ||
Description | Represents a set of flags indicating what aspects of the version' information should be included or excluded from the response. This element is optional: if not present, the API will return all version information. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
rootActuals Not supported in any API version as of 2019.3 | N | Indicates whether the root actuals version should be included when actuals are hidden from the version selector. | false |
scenarios | N | Indicates whether if private what-if scenarios should be included in the response. | false |
currencyVersions
Available in API v40+ | N | Indicates whether currency versions for translated actuals should be included in the response.
You must contact your Named Support Contact to see if your instance is eligible for this feature. | false |
Contents of the Element | |||
(none) | |||
Response Format
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <versions seqNo="32"> <version id="1" name="Actuals" shortName="" type="ACTUALS" isVirtual="false" description="Total Actuals" isDefaultVersion="false" isLocked="false" hasAuditTrail="false" isImportable="0" startVer="2012" completedValuesThru="03/2012" startScroll="01/2012" endVer="2016" lockLeading="" > <version id="5" name="Adjusted Actuals" shortName="SV-13" type="ACTUALS" isVirtual="false" description="Actuals SubVersion" isDefaultVersion="false" isLocked="false" hasAuditTrail="false" isImportable="0" > <version id="6" name="Original Import" shortName="SSV-13" type="ACTUALS" isVirtual="false" description="Values Imported from the GL" isDefaultVersion="false" isLocked="false" hasAuditTrail="false" isImportable="1" /> <version id="8" name="Manual Adjustments" shortName="SSV-14" type="ACTUALS" isVirtual="false" description="Actuals Sub-Version for Manual Adjustments" isDefaultVersion="false" isLocked="false" hasAuditTrail="true" isImportable="1" /> </version> <version id="9" name="Eliminations" shortName="ELIM" type="ACTUALS" isVirtual="false" description="Eliminating entries" isDefaultVersion="false" isLocked="false" hasAuditTrail="false" isImportable="0" /> </version> <version id="2" name="Budget 2013" shortName="" type="PLANNING" isVirtual="false" description="This is the budget for 2013 with a five-year span." isDefaultVersion="true" isLocked="false" hasAuditTrail="true" isImportable="1" leftScroll="2013" startPlan="01/2013" endPlan="2017" lockLeading="05/2013" /> <version id="10" name="Worst Case" shortName="S13-A-WC" type="SCENARIO" isVirtual="false" description="Worst Case for Budget 2013" isDefaultVersion="false" isLocked="false" hasAuditTrail="false" isImportable="0" isPredictive="false" /> </version> <version id="3" name="Budget 2014" shortName="B-14" type="PLANNING" isVirtual="false" description="This is the budget for 2014 with a five-year span." isDefaultVersion="false" isLocked="false" hasAuditTrail="false" isImportable="1" leftScroll="2014" startPlan="01/2014" endPlan="2018" lockLeading="" /> </versions> </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 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. | |
versions element | |||
Tag Name | versions | ||
Description | Container for one or more version 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 version elements. | |||
version element | |||
Tag Name | version | ||
Description | Represents a single version being returned in the response to an exportVersions API call. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | Y | The internal system ID number for the version or folder. All IDs are unique among all versions, sub-versions, and folders. | 2 |
name | Y | The name of the version or folder, as it appears in Version Administration. | Budget 2015 |
shortName | N | A short name for the version, if any, as entered in Version Administration | B2015 |
type
Updated in API v37. | Y | One of the following values:
| ACTUALS |
isVirtual Available in API v16+ | Y | true or false to indicate if this is a virtual version | false |
description | Y | The description of the version or folder, as it appears in Version Administration. | This is the budget for 2015 with a five-year span. |
isDefaultVersion | Y | Tells if the version is the default version. True if the version is the default version otherwise false. | true |
isLocked | N | Indicates if the version has been "globally locked" (has its Locked Version checkbox checked). If not present, the version is not considered to be locked. Will always be 'false' for actuals versions or for folders. | true |
hasAuditTrail | Y | Indicates if the version has Audit Trail enabled. | true |
enabledForWorkflow Available in API v17+ | N | Indicates if the version is enabled for workflow. | 1 |
isImportable | N | Indicates if the user requesting this API is allowed to import data into the version. 0 means the version cannot accept imports, and 1 means it can. A version is importable if at least one timeslot in the specified version is importable for this user. | 1 |
startVer | N | The code of the root time period in which the version starts. Equivalent to start of version in the version administration page. This attribute is shown only for the root actuals version. This attribute is required for the root actuals version. | 2015 |
endVer | N | The code of the root time period in which the version ends. Equivalent to end of version in the version administration page. This attribute is shown only for the root actuals version. This attribute is required for the root actuals version. | 2015 |
startScroll | N | The code of the leaf time period where planning begins. Equivalent to starting scroll location on the version administration page. This attribute is shown only for the root actuals version. This attribute is required for the root actuals version. | 01/2015 |
completedValuesThru | N | The code of the latest leaf time period the root actuals has data filled in for. In a standard calendar, this would be a month. Equivalent to completed values through on the version administration page. This attribute is shown only for the root actuals version. This attribute is optional for the root actuals version. | 03/2015 |
leftScroll | N | The code of the root time period in which the version starts. Equivalent to left scroll limit in the version administration page. This attribute is shown only for planning versions. This attribute is required for planning versions. | 2015 |
startPlan | N | The code of the leaf time period where planning begins. Equivalent to start of plan on the version administration page. This attribute is shown only for planning versions and is required for planning versions. | 02/2015 |
endPlan | N | The code of the root time period in which the version ends. Equivalent to end of plan in the version administration page. This attribute is shown only for planning versions. This attribute is required for planning versions. | 2015 |
lockLeading | N | The code of the leaf time period up to which version values are locked. Equivalent to lock leading months through on the version administration page. This attribute is shown only for the root actuals version and planning versions. This attribute is optional for the root actuals version and planning versions. | 05/2015 |
isPredictive Available in API v28 + | Y | Indicates if the version is a predictive version. | false |
Contents of the Element | |||
One nested version element for each direct child version of this version. | |||