Skip to main content
Adaptive Insights
Knowledge @ Adaptive Insights LLC, a Workday company.

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.
Requires a preexisting version.

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.

  • Error: An error was found in the entity 
  • Warning: A warning was found in the entity
  • Created: The entity was created successfully
  • Updated: The entity was updated successfully

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.
One attributes element if this level has one or more attributes associated with it.

 

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.

  • Error: An error was found in the entity 
  • Warning: A warning was found in the entity
  • Created: The entity was created successfully
  • Updated: The entity was updated successfully
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.

  • Error: An error was found in the entity 
  • Warning: A warning was found in the entity
  • Created: The entity was created successfully
  • Updated: The entity was updated successfully
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.

  • Error: An error was found in the entity 
  • Warning: A warning was found in the entity
  • Created: The entity was created successfully
  • Updated: The entity was updated successfully

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.
  • Was this article helpful?