updateLevels

最後の更新
PDFとして保存

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.