updateLevels

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.adaptiveplanning.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). See Metadata Bulk Update.

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.

Input Format 1: Payload Includes Whole Tree

The updateLevels API works best when a caller wants to provide the new tree state without worrying about changes.

The updateLevels API figures out changes in the level structure and only the newly added or changed levels update. Notice that the

levels

element contains only 1 direct child

level

element. That child element then contains the rest of the hierarchy.

<?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" />
      </level>
      <level id="3" name="Professional Services" currency="USD" shortName="Prof.Srv" eliminationLevel="1" />
   </level>
</levels>
</call>

Input Format 2: Payload Includes Level Subtree Structure

This format supports use cases when changes are limited to only 1 portion of the level tree structure.

For example, changes are within the Engineering level. Again, the

levels

element only contains 1 direct child

level

element. That level contains the rest of the subtree structure levels. The smallest subtree for this format includes only a parent and 1 child.

<?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="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" />
   </level>
</levels>
</call>

Input Format 3: Updating a Single Level

This format supports handling the use case when changes are limited to only 1 level. The

levels

element only contains 1 direct child

level

element.

Only use input format 3 when updating a single level. Input format 3 isn't the preferred format for updating multiple levels. You can't create a new level with this format. Use input format 2 for adding new child levels.

<?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="10" name="Documentation" currency="PKR" shortName="Doc" actualsStart="05/2013" actualsEnd="12/2018" inWorkflow="1" propagateToDescendants="1" />
</levels>
</call>

Input Format 4: Flat Format Containing All Level Tags Under the Levels Tag

This format contains

level

tags beneath the

levels

tag in a flat format without a hierarchy. You only update the properties of each listed level, without altering the level hierarchies.

Only use the flat format for deltas, or incremental changes to very small portions of the hierarchy. Input format 1 provides the best performance for loading the entire hierarchy of levels.

<?xml version="1.0" encoding="UTF-8"?>
<call method="updateLevels" callerName="a string that identifies your client application">
<credentials login="steve@steveco.com" password="" />
<levels>
   <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>
</levels>
</call>

Handling Multiple Renames in a Single updateLevels Call

Multiple renames of the same entity can take place in a remote system between

updateLevels

calls. The names of entities on the remote system can swap for the same entity IDs. When

updateLevels

calls take place after the name swap, the

updateLevels

call manages these changes by tracking the IDs across name changes. The call can also handle the introduction of a new ID that uses an existing name.

For each of the examples to succeed, the full swap of IDs must take place with the unique values.

Example 1: A simple name swap in the remote system.


ID     Unique Value   New Unique Value
1      AA             BB
2      BB             AA

Example 2: A sequence of 3 renames in the remote system.


ID     Unique Value   New Unique Value
1      AA             BB
2      BB             CC
3      CC             AA

Example 3: A new entity using an existing unique value.


ID     Unique Value   New Unique Value
4                     AA
1      AA             BB
2      BB             Old BB

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)

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
retainExisitingOrder Available in API v26+	N	retainExistingOrder="1" indicates updateLevels API should ignore the order of elements in the XML payload and the existing defined order will be retained. retainExistingOrder="0" indicates updateLevels API should update the order of elements based on the tag position relative to other siblings in the XML payload. The retainExistingOrder attribute is ignored in API version prior to API v26. The default value for retainExistingOrder is "0" for v26. For API version v27 and later, the default value for retainExistingOrder is "1".	1
displayNameEnabled Only available in API v30+ for instances that enable display name.	N	displayNameEnabled=1 indicates updateLevels should respect display name properties of code , displayNameType , and description when Enable Display Name is ON for the instance. displayNameEnabled=0 indicates the updateLevels API should continue following the pre-v30 API contract even when Enable Display Name is ON for the instance. The updateLevels API ignores the display name properties code , displayNameType and description . The default value for displayNameEnabled is "0".	1
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
code Only available in API v30+ for instances that enable display name.	N	The unique code of the level. This property is only available when Enable Display Name is ON for the instance.	NewLevelName
name	N	The name of the level. When Enable Display Name is ON for an instance with API v30 or higher, name allows duplicate values. When Enable Display Name is OFF for an instance, code is not available and name must be unique.	NewLevelName
shortName updated in API v30	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
publishCurrency Available in API v24+	N	PublishCurrency sets the Workday Company currency when publishing a Financial Plan. The Publish Currency loads through the Planning Level Loader in Workday Adaptive Planning integration as an additional currency attribute for a level. PublishCurrency indicates one of the configured currencies for the instance, found in the exportActiveCurrencies call and the Levels Admin UI. Only available when you set up Adaptive Planning for Workday. See the Publish Plans section of Steps: Configure Adaptive Planning for HCM and Financials.	CAD
inWorkflow	N	Indicates if this level participates in a workflow.	1
propagateToDescendants	N	Indicates if changes propagate to children of this level. 0 for no, 1 for yes. Not all of the level properties are covered under propagateToDescendants. For a list of the properties affected by propagateToDescendants , see propagateToDescendants behavior during UpdateLevels requests.	0
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
description Only available in API v30+ for instances that enable display name.	N	The description of the level. This property is only available when Enable Display Name is ON for the instance.	The top-most department.
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?		Example
name	Y	The name of the version, 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 updated in API v30	Y	The name of the attribute.	Location
value updated in API v34	Y	The attribute value for this attribute. For API v32 and v33, this attribute is only meaningful when the Display Name setting is OFF for the instance. For API v34 and newer: Supported when Effective Display Name setting is ON. The presence of valueCode and valueName will error out. When Level Import Automatically Creates Attribute Values is enabled in the Attribute Admin UI, the value string becomes the code and name if the value doesn't already exist. Set value="" to remove this attribute tagging.	170
valueCode Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34.	Y	The attribute value code for this attribute. The valueCode input is meaningful only when displayNameEnabled=1 and the Display Name setting is ON for the instance in API v32 and API v33. Set valueCode="" to remove this attribute tagging.	SFO
valueName Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34.	N	The attribute valueName is meaningful only when: valueCode holds a non-existing attribute value. The Display Name setting is ON for the instance. displayNameEnabled=1 Calling API v32 and API v33. valueName is ignored when the valueCode holds an existing attribute value.	San Francisco
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 updated in API v30	Y	The name of the dimension.	Budget 2015
value updated in API v34	Y	The dimension value for this dimension available in this level. For API v32 and API v33, value is only meaningful when the Display Name setting is OFF for the instance. For API v34 and newer: Supported when Effective Display Name setting is ON. The presence of valueCode and valueName will error out. When Data Import Automatically Creates Dimension Values is enabled in Dimension Admin UI, the value string becomes the code and name if the value doesn't already exist.	Lahore
valueCode Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34.	Y	The dimension value code for this dimension available in this level. For API v32 and API v33, valueCode is only meaningful when: The Display Name setting is ON for the instance. displayNameEnabled=1	LHE
valueName Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34.	N	The name for a newly auto-created dimension value. For API v32 and API v33, valueName is only meaningful when valueCode holds a non-existing dimension value. The Display Name setting is ON for the instance. displayNameEnabled=1	Lahore
Contents of the Element
(none)

Top to Bottom Payload Processing

Attributes for levels logically group values and tag levels. Because the updateLevels API processes the XML payload from top to bottom, assign a level attribute for the parent level before changing the child attribute level values. Child levels can be tagged with any attribute value when the parent level attribute value is blank. If level attributes fail to align with the parent attribute, a compatibility validation error occurs.

Consider the tree structure below where the parent "California" has 2 child levels "Palo Alto" and "Pleasanton". The level attributes "Palo Alto" and "Pleasanton" are siblings.


Location
|__USA                              
|__California
   |__Palo Alto
   |__Pleasanton

Sample Original Request XML with Level Attributes

Notice that the location attribute value "Palo Alto" is assigned to both "Engineering" and "Development".


<levels deleteWorkflowSilently="0" deleteActualsSilently="0">
<level id="1" name="HQ" proceedWithWarnings="0">
   <attribute name="Location" value="" />
   <level id="2" name="Engineering">
      <attribute name="Location" value="Palo Alto" />
      <level id="8" name="Development">
         <attribute name="Location" value="Palo Alto" />
      </level>
   </level>  
</level>
</levels>

Example of Incorrect Order for Payload Processing

The XML payload below generates an error, "

The attribute value Pleasanton is not compatible with the parent's attribute value

". The top-to-bottom payload processing considers the parent level "Engineering" to have the location attribute value "Palo Alto" from the previous code block and processes "Pleasanton" as the child of "Palo Alto". The error is generated because the child level "Development" can only have the location attribute as "Palo-Alto" as indicated in the tree structure.


<levels deleteWorkflowSilently="0" deleteActualsSilently="0">
<level id="1" name="HQ" proceedWithWarnings="0">
   <level id="2" name="Engineering">
      <level id="8" name="Development">
         <attribute name="Location" value="Pleasanton" />
      </level>
      <attribute name="Location" value="California" /> <!-- Level Attribute change ignored due to placement order-->
   </level>
   <attribute name="Location" value="" />
</level>
</levels>

Example of Valid Order for Payload Processing

Re-arranging the placement order of the attribute "California" below "Engineering" enables the API to process the parent level attribute first, allowing the child level "Development" to have the location attribute value of either "Palo Alto" or "Pleasanton".


<levels deleteWorkflowSilently="0" deleteActualsSilently="0">
<level id="1" name="HQ" proceedWithWarnings="0">
   <attribute name="Location" value="" /> <!-- Level Attribute change processed due to correct placement order-->
   <level id="2" name="Engineering">
      <attribute name="Location" value="California" />
      <level id="8" name="Development">
         <attribute name="Location" value="Pleasanton" />
      </level>
   </level>
</level>
</levels>

Version availability of a level works the same way. Set the version availability of a level before altering the child levels to avoid compatibility errors.

Sample Original Request XML with Versions

Notice that the availability of the "Budget 2020" version for the levels "Engineering" and "Development" is set to "0".


<levels deleteWorkflowSilently="0" deleteActualsSilently="0">
<level id="1" name="HQ" proceedWithWarnings="0">
   <version name="Budget 2020" available="0" />
   <level id="2" name="Engineering">
      <version name="Budget 2020" available="0" />
      <level id="8" name="Development">
         <version name="Budget 2020" available="0" />
      </level>
   </level>
</level>
</levels>

Example of Incorrect Order for Payload Processing

The XML payload below generates an error since the top-to-bottom payload processing considers the parent "Engineering" to be unavailable ("

available=0")

for the "Budget 2020" version from the previous code block, and processes the availability of the child level "Development" as "1". The child level "Development" cannot be available when the parent level "Engineering" is unavailable.


<levels deleteWorkflowSilently="0" deleteActualsSilently="0">
<level id="1" name="HQ" proceedWithWarnings="0">
   <level id="2" name="Engineering">
      <level id="8" name="Development">
         <version name="Budget 2020" available="1" />
      </level>
      <version name="Budget 2020" available="1" /><!-- Parent version availability change ignored due to placement order-->
   </level>
   <version name="Budget 2020" available="1" />
</level>
</levels>

Example of Valid Order for Payload Processing

Re-arranging the placement order for the "Budget 2020" version below the parent level "Engineering" enables the API to process the parent availability first, allowing "Development" to have the version availability value of "1" or "0".


<levels deleteWorkflowSilently="0" deleteActualsSilently="0">
<level id="1" name="HQ" proceedWithWarnings="0">
   <version name="Budget 2020" available="1" />
   <level id="2" name="Engineering"><!-- Parent Version availability change processed due to correct placement order-->
      <version name="Budget 2020" available="1" />
      <level id="8" name="Development">
         <version name="Budget 2020" available="1" />
      </level>
   </level>
</level>
</levels>

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
retainExisting Order	N	0 updateLevels API should update sort order based on the XML payload content. 1 updateLevels API should retain existing sort order.	1
displayNameEnabled Only available in API v30+ for instances that enable display name.	N	displayNameEnabled=1 indicates updateLevels should respect display name properties of code , displayNameType , and description when Enable Display Name is ON for the instance.	1
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
code Only available in API v30+ for instances that enable display name.	N	The unique code of the level. This property is only available when Enable Display Name is ON for the instance.	HQ
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	PublishCurrency sets the Workday Company currency when publishing a Financial Plan. The Publish Currency loads through the Planning Level Loader in Workday Adaptive Planning integration as an additional currency attribute for a level. The Publish Currency indicates one of the configured currencies for the instance, found in the exportActiveCurrencies call and indicated in the Level Admin UI. Requires Workday Power of One enabled by Provisioning.	CAD
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
propagateToDescendants	N	Indicates if changes propagate to the children of this level. 0 for no, 1 for yes. To learn more about propagateToDescendants behavior, see propagateToDescendants behavior during UpdateLevels requests.	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
description Only available in API v30+ for instances that enable display name.	N	The description of the level. This property is only available when Enable Display Name is ON for the instance.	The top-most department.
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	Location
value	Y	The value of the level attribute.	SFO
valueCode Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34.	Y	The attribute value code for this attribute. For API v32 and newer, valueCode is only meaningful when: The Display Name setting is ON for the instance. displayNameEnabled=1	SFO
valueName Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34.	N	The name for a newly auto-created attribute value. The attribute valueName is meaningful only when: valueCode holds a non-existing attribute value. The Display Name setting is ON for the instance. displayNameEnabled=1value Name is ignored when the valueCode holds an existing attribute value.	San Francisco
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.	The level UKregion2 is either duplicated in the payload or already exists in the system with ID 6.
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, 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
valueCode Only available in API v32+ for instances that enable display name.	Y	The dimension value code for this dimension. For API v32 and newer, valueCode is only meaningful when: The Display Name setting is ON for the instance. displayNameEnabled=1	CUS
valueName Only available in API v32+ for instances that enable display name.	N	The name for a newly auto-created dimension value. For API v32 and newer, valueName is only meaningful when: valueCode holds a non-existing dimension value. The Display Name setting is ON for the instance. displayNameEnabled=1 valueName is ignored when the valueCode holds an existing dimension value.	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.	To learn more about propagateToDescendants behavior, see propagateToDescendants behavior during UpdateLevels requests.
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.

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