updateLevels
Supported in API v19 +
Category |
Metadata modification |
Description |
Update a set of existing levels or create new levels and their properties. Multiple levels with multiple values can be updated in one call. If successful, the API returns details for the levels that were updated/created. If the API fails, a comprehensive list of errors and their causes returns. |
Permissions Required To Invoke |
Model and permissions on each level |
Parameters Required On Request |
Credentials |
This method's request contains a credentials tag to identify and authorize the calling user. User must have the "Model" permission and the permission required to administer the levels being updated.
Best Practice: Invoke exportLevels to retrieve the Adaptive Insights level IDs needed for your updateLevels request. No changes should be made to the planning levels via the Adaptive Insights UI or APIs by others before you submit your updateLevels request.
HTTP | Description |
---|---|
Method |
Post |
Content-Type |
text/xml |
Curl Example
curl -H "Content-Type: text/xml" -d @C:/temp/updateLevels.xml -X POST https://api.adaptiveinsights.com/api/v19
updateLevels.xml contents
Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="updateLevels" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <levels> <level id="1" name="HQ"> <level id="2" name="Engineering" currency="USD" shortName="Engr"> <level id="8" name="Development" currency="USD" shortName="Dev" inWorkflow="0"/> <level id="9" name="QA" currency="INR" eliminationTradingPartner="1"/> <level id="10" name="Documentation" currency="PKR" shortName="Doc" actualsStart="05/2013" actualsEnd="12/2018" inWorkflow="1" propagateToDescendants="1"> <version name="Budget 2011" available="1"/> <version name="Budget 2012" available="0"/> <version name="Budget 2013" available="1"/> </level> </level> <level id="3" name="Professional Services" currency="USD" shortName="Prof.Srv" eliminationLevel="1"> <attribute name="Corporate Discount" value="Available"/> <attribute name="Transfers Restricted" value="Yes"/> <dimension name="Region" value="C-US"/> </level> </level> </levels> </call>
For large payloads, you can post compressed XML files (zipped). Find out how here.
The following conditions apply to updateLevels:
-
Levels are identified for update via their internal ID number.
-
To create new levels, give them a blank or missing ID property.
-
You can move an existing (non-new) item so that it becomes a child of a new item. Doing so creates the new item and moves the existing item under it as a child.
-
-
Sheet availability and user access cannot be updated through
updateLevels.
Request Format for Creating a New Level
To create a new level, include its parent by its ID. For example, to add a new child level below the Engr
value which has id 7
, you can use:
<?xml version='1.0' encoding='UTF-8'?> <call method="updateLevels" callerName="Steve C"> <credentials login="stevec@greenco.com" password="password"/> <levels> <level id="7"> <level id="" name="Documentation" description="docs" shortName="" > </level> </level> </levels> </call>
This method does not change anything about level id 7
. It creates a new child named Documnentation
for id 7
. All unmentioned children of Engr
move to the end of the child list. This is the equivalent of "setting the parent" for the new level.
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) |
levels element |
|||
Tag Name |
levels |
||
Description |
Only 1 levels element request is allowed per payload. It contains one or more level elements. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
Contents of the Element |
|||
Contains one or more level elements. |
level element |
|||
Tag Name |
level |
||
Description |
Specifies a level to create. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
id |
Y |
The id of the level being updated. |
34 |
name |
N |
The name of the level. The name must be unique. |
NewLevelName |
shortName |
N |
Displayable title of the column, as seen on the sheet. |
NewLevelShortName |
currency |
N |
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. |
USD |
inWorkflow |
N |
Indicates if this level participates in a workflow. |
1 |
eliminationLevel |
N |
Indicates if this level is an elimination level for use in intercompany eliminations. A level can be an elimination level or a elimination trading partner, but not both. |
1 |
eliminationTradingPartner |
N |
Indicates if this level is an elimination trading partner. A level can be an elimination trading partner or an elimination level, but not both. |
0 |
actualsStart |
N |
Indicates the start of the actuals for this level. Must be an existing time code from Time Administration at the default time stratum. |
May-2013 |
actualsEnd |
N |
Indicates the end of actuals for this level. Must be an existing time code from Time Administration at the default time stratum. |
Dec-2018 |
Contents of the Element |
|||
One or more attribute elements if you want to set one or more level attributes associated with the level. |
version element |
|||
Tag Name |
version |
||
Description |
Specifies the version availability of a level. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the version or folder, as it appears in Version Administration. |
Budget 2015 |
available |
Y |
If 1 this version is available in this level. |
1 |
Contents of the Element |
|||
One or more version elements for each level |
attribute element |
|||
Tag Name |
attribute |
||
Description |
Specifies an attribute to update. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the attribute. |
Location |
value |
Y |
The attribute value for this attribute |
170 |
Contents of the Element |
|||
(none) |
dimension element |
|||
Tag Name |
dimension |
||
Description |
Specifies the level dimension value assignments. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the dimension. |
Budget 2015 |
value |
Y |
The dimension value available in this level. |
Lahore |
Contents of the Element |
|||
(none) |
Response Format
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <levels> <level id="1" name="HQ" currency="CAD" shortName="" eliminationLevel="1" eliminationTradingPartner="0" inWorkflow="0" status=""> <level id="2" name="Engineering" currency="USD" shortName="Engr" eliminationLevel="0" eliminationTradingPartner="1" inWorkflow="0" status="updated"> <level id="8" name="Development" currency="USD" shortName="Dev" eliminationLevel="0" eliminationTradingPartner="0" inWorkflow="0" status="updated" /> <level id="9" name="QA" currency="INR" shortName="" eliminationLevel="0" eliminationTradingPartner="0" inWorkflow="0" status="updated" /> <level id="10" name="Documentation" currency="PKR" shortName="Doc" eliminationLevel="0" eliminationTradingPartner="0" inWorkflow="1" propagateToDescendants="1" actualsStart="05/2013" actualsEnd="12/2018" status="updated"> <version name="Budget 2011" available="1" status="" /> <version name="Budget 2012" available="0" status="updated" /> <version name="Budget 2013" available="1" status="" /> </level> </level> <level id="3" name="Professional Services" currency="USD" shortName="Prof.Srv" eliminationLevel="1" eliminationTradingPartner="0" inWorkflow="0" status="updated"> <attribute name="Corporate Discount" value="Available" status="" /> <attribute name="Transfers Restricted" value="Yes" status="" /> <dimension name="Region" value="C-US" status="" /> </level> </level> </levels> </output> </response>
output element |
|
Tag Name |
output |
Attributes of the Element |
|
(none) |
|
Contents of the Element |
|
A single required level 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 one or more level elements. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
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 updateLevels 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 |
shortName |
N |
The abbreviation for the level, if any, as entered in Level Administration. |
Dev |
eliminationLevel | N | Indicates whether the level is an elimination level. 0 for no, 1 for yes. | 1 |
eliminationTradingPartner | N | *description* | 1 |
inWorkflow | N | Indicates whether the level is in a workflow. 0 for no, 1 for yes. | 1 |
propogateToDescendants | N |
Indicates if changes propagate to the children of this level. 0 for no, 1 for yes. See more about propogateToDescendants behavior here. |
1 |
actualsStart | N | The time code as defined in Time Administration for the start of the actuals version for this level. | 05/2013 |
actualsEnd | N | The time code as defined in Time Administration for the end of the actuals version for this level. | 12/2018 |
status | Y |
The status of the level following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.
|
Updated |
message | N | The error message for invalid level input | The level UKregion2 is either duplicated in the payload or already exists in the system with ID 6. |
Contents of the Element |
|||
One nested level element for each direct child level of this level. |
attribute element |
|||
Tag Name |
attribute |
||
Description |
Container for one level attribute element. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the level attribute |
Education Type |
value |
Y |
The value of the level attribute. |
Tech1 |
status | Y |
The status of the attribute following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.
|
updated |
message | N | The error message for an invalid attribute input. | |
Contents of the Element |
|||
(none) |
version element |
|||
Tag Name |
version |
||
Description |
Specifies the version availability of a level. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the version or folder, as it appears in Version Administration. |
Budget 2015 |
value |
Y |
If 1 this level is available in this version. |
1 |
status | Y |
The status of the version following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.
|
updated |
Contents of the Element |
|||
One or more version elements for each dimension value. |
dimension element |
|||
Tag Name |
dimension |
||
Description |
Represents a single custom dimension being returned in the response to an updateLevels API call. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the dimension, as it appears on reports and sheets. |
Region |
value |
N |
The dimension value available for this level. |
C-USA. |
status |
N |
The status of the version following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.
|
Updated |
Contents of the Element |
|||
(none) |
Error and Warning Message Descriptions
Type | Message | Example/Description |
---|---|---|
Error | A system error occurred contact support for more information. | System error |
Error | Unable to find content.xml file. | Already exists in updateDimensions API |
Error | Provided input does not contain any level tags. | Payload is missing level tag. |
Error | {0} is not recognized as a defined {1}. | Used when version name or value is unknown. |
Error | The {0} can not be empty. | Version name is empty. |
Error | Version availability cannot be changed for actuals. | When the user attempts to modify version visibility for the actuals version. |
Error | Version availability cannot be changed for the root level {0}. | When the user attempts to modify version visibility for the root level. |
Error | The visibility of version {0} on the level {1} is not compatible with parent of {1}. | When the provided version visibility of the level is not compatible with the parent level. |
Error | You do not have access to update one or more of the levels or versions specified in the request. | When the user attempts to update non-accessible level information. |
Error | {0} is not recognized as a defined {1}. | Used when dimension name or value is unknown. |
Error | The {0} can not be empty. | Dimension name is empty. |
Error | List Dimension cannot be used in Level. | User attempts to map a flat dimension value for a level. |
Error | The dimension {0} is disabled for the level. | The dimension is disabled for this level. |
Error | The dimension value {0} is not compatible with the parent's dimension value. | When the provided dimension mapping of level is not compatible with the parent level. |
Error | {0} is not recognized as a defined {1}. | Used when attribute name or value is unknown. |
Error | The attribute value {0} is not compatible with the parent's attribute value. | When the provided level attribute value of the level is not compatible with the parent level. |
Error | The {0} can not be empty. | Attribute name is empty. |
Error | Exception occurred when processing updateLevels API request. | System error |
Error | Id {0} does not exist. | Nonexistent level id provided in the request payload. |
Error | A {0} cannot have the same id as its parent. | Child and parent level have the same ID. |
Error | {0} cannot be the child of {1}. | A specific level can't be the child of another specific level. |
Error | Root level id is missing. | The ID for the root level was not provided. |
Error | The root level Id {0} with level name {1} cannot become a child level. | The root level can't become a child level. |
Error | The root level currency cannot be changed. | Currency can not be changed for the root level. |
Error | The currency {0} is not valid. | Unknown currency name provided in the level tag. |
Error | The level {0} is duplicated for IDs {1}. | Duplicate level name provided. |
Error | The level {0} is duplicated in the payload {1} {2}. | Multiple new levels contain the same name. |
Error | The root level workflow cannot be changed. | InWorkflow status can not be changed for the root level. |
Error | The attribute assignment of level {0} is not compatible with the parent's attribute value. | The provided level attribute value of the level is not compatible with the parent level. |
Error | The level with ID {0} does not exist. | No level with the provided ID exists in Planning. |
Error | You do not have access to update one or more of the levels or versions specified in the request. | User permission missing for a level mentioned in payload. |
Error | The version visibility of the level {0} is not compatible with {0} parent {1}. | Provided version visibility of the level is not compatible with the parent level. |
Error | The level {0} has an actuals availability containing more time periods than its parent {1}. | The current level actuals range has been changed. The modified actuals range makes it smaller than one of its descendant's actuals range. |
Error | You cannot disable workflow for the level ({0}) if deleteWorkflowSilently, 0. If you set deleteWorkFlowSilently, 1, all of your workflow tasks associated with this level will be deleted. | When delete workflow silently is off, you cannnot disable workflow. If delete workflow silently is turned on, all workflow tasks for the level get deleted. |
Error | Could not update the Actuals Start and End date for {0} since the date range is smaller than the start and end dates defined for the Actuals version, and deleteActualsSilently is set to false preventing actuals from being deleted for {1}. | User attempts to shrink actuals range without deleteActualsSilently flag set. |
Error | Workflow cannot be enabled for the level {0} as its parent has workflow disabled. | Workflow cannot be enabled for the level because its parent has workflow disabled. |
Error | TradingPartner or eliminationLevel cannot be enabled for the level {0} as its parent has tradingPartner enabled. | When trading partner is already enabled for a parent, its children cannot have trading partner or elimination level enabled. |
Error | A parent with id {0} does not exist. | A nonexistent ID was provided for a parent level. |
Error | Parent node {0} is becoming child of its current direct/indirect child node {1}. | A cyclic relationship between a parent and children is being created. |
Error | A level cannot be its own parent. | A level cannot become its own parent in a payload. |
Error | A level with id {0} does not exist. | The provided entity does not exist in Planning. |
Error | Elimination and TradingPartner cannot be true at the same time. | A level can be an elimination level, or a trading partner, but not both at the same time. |
Error | You can only modify Elimination on this level while its parent has TradingPartner disabled. | Modifying elimination for a level can only happen when that level's parent has trading partner disabled. |
Error | A sub-level beneath this level is an elimination level, so this level cannot be marked as a trading partner. | The current level cannot be marked as a trading partner because a level underneath it is an elimination level. |
Error | You cannot enable workflow on this level while its parent has workflow disabled. | The parent of the level has workflow disabled. |
Error | {0} can only be enabled together for a node and its descendants. To make changes to them , set propagateToDescendants=1. | See more about propogateToDescendants behavior here. |
Error | Cannot make level ''{0}'' an elimination level since it has data in one or more intercompany accounts. | A level can't become an elimination level if it contains data in intercompany accounts. |
Error | actualsStart or actualsEnd cannot be changed for root level {0}. | The user attempts to change actuals range for root level. |
Error | You cannot add children to a linked level. | The user attempts to add a child level for a linked level. |
Error | A timecode {0} does not exist. | The provided time code does not exist. |
Error | The actuals start date {0} cannot be greater than the actuals end date {1}. | The provided actuals start time is after the end time. The actuals start time needs to be before the end time. |
Error | Invalid time code "{0}". Time codes set for actualsStart and actualsEnd must match the lowest strata available in Time Administration. | Provided time code is not at lowest strata level. |
Error | Invalid time code "{0}". The actualsStart {0} is before parents actualsStart {1}. | The actualsStart time provided is before parent level's actuals start time. |
Error | Invalid time code "{0}". The actualsEnd {0} is after parents actualsEnd {1}. | The actualsEnd time provided is going beyond parent level's actuals end time. |
Error | The actualsStart of {0} is before the Actuals version start of {1}. The actualsStart should come after {1}. | The actualsStart time provided is before Actuals version start time. |
Error | The actualsEnd of {0} is after the Actuals version end of {1}. The actualsEnd should come before {1}. | The actualsEnd time provided is going beyond Actuals version end time. |
Error | Invalid "{0}" value "{1}". The value must be "1" or "0". | The user provided something other than "0" or "1" as a value for a boolean property. |
Error | Invalid {0} {1}. | The user provided an invalid value. |
Error | {0} is NOT allowed as name. | Reserved word "this", word ending with "(+)" or "(-)" has been provided as level name. |
Error | Id "{0}" does not exist. | Provided entity does not exist in Planning. |
Warning | The level {0} cannot be moved to another parent while proceedWithWarnings=0. | User attempts to move level without proceedWithWarning="1". proceedWithWarning="1" means version visibility, attribute mapping and data will be adjusted to match with new parent level. |
Warning | The actuals availability range was reduced for level {0}. The actuals data excluded from the range has been deleted. | Actuals availability range was reduced. Data outside of the range gets deleted. |
Warning | deleteWorkflowSilently is a global flag. It should be in the levels tag. | Delete workflow silently is a global flag. It belongs in the levels tag, not in another tag. |
Warning | deleteActualsSilently is a global flag. It should be in the levels tag. | Delete actuals silently is a global flag. It belongs in the levels tag, not in another tag. |
Warning | Levels can not be modified because there are unpublished changes. | Planning has pending changes for admin publishing. |