updateLevel
Not supported in API v20 +. Use updateLevels.
Category |
Metadata modification |
Description |
Update a level. If successful, the API returns details for the level that has just been updated. |
Permissions Required To Invoke |
Organization Structure |
Parameters Required On Request |
Credentials |
This method's request contains a credentials tag to identify and authorize the calling user. User must have Organization Structure permission to create the level.
This method returns an error if there are unpublished changes.
Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="updateLevel" callerName="fred"> <credentials login="sampleuser@company.com" password="my_pwd" /> <level id="41" name="New Level Name" shortName="NewLvlName" > <attributes> <attribute attributeId="20" valueId="199" /> </attributes> </level> </call>
credentials element |
|||
Tag Name |
credentials |
||
Description |
All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user (any audit trail or history of actions in the system will show that this user performed the action), and therefore the user must have the required permissions to perform the action in order for the API call to succeed. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
login |
Y |
The login name of the user invoking the API method. This user must have 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 Insights, 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) |
level element |
|||
Tag Name |
level |
||
Description |
Specifies a level to update. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
id |
Y |
The ID of the level to be updated. |
34 |
name |
Y |
The name of the level. The name must be unique. |
New Level Name |
shortName |
N |
The short name of the level. |
NewLvName |
proceedWithWarnings |
N |
Indicates whether the user wants to ignore warning messages and go ahead with the create operation. 0 for no, 1 for yes. If there are warnings and proceedWithWarnings=0, then the level will not be created. Set proceedWithWarnings=1 to create the level when there are warnings. |
1 |
Contents of the Element |
|||
One optional attributes element if you want to set one or more level attributes associated with the level. |
attributes element |
|||
Tag Name |
attributes |
||
Description |
Container for one or more level attribute elements. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
(none) |
|||
Contents of the Element |
|||
One or more attribute elements. |
attribute element |
|||
Tag Name |
attribute |
||
Description |
Container for one level attribute element. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
attributeID |
Y |
The id of the level attribute generated by system. |
20 |
valueID |
Y |
The unique id of the level attribute value generated by system. If this value is 0 then this attribute is removed from the account. |
170 |
Contents of the Element |
|||
(none) |
Response Format
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <levels> <level="41" name="New Level Name" shortName="NewLvlName" currency="USD"> <attribute attributeId="20" name="Regional Code" valueId="199" value="A-145" /> </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 exportLevels 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 Organization Administration. |
Dev |
availableStart |
N |
The start date for the availability of the level for actuals verion, applicable only when the Actuals version is specified in the request. he value can be either a time period code, such as "01/2012" or the special value "START" indicating the start of the version. |
01/2012 |
availableEnd |
N |
The end date for the availability of the level for actuals verion, applicable only when the Actuals version is specified in the request. The value can be either a time period code, such as "12/2013", or the special value "END" indicating the end of the version. |
12/2013 |
isImportable |
N |
Indicates if the associated level is importable in the specified version. '0' means it is not importable and '1' means it is importable. A level is importable if at least one timeslot in the specified version is importable. isImportable attribute is only emitted if versionName or versionID is specified in the request. isImportable only indicates that a level is available for import in the specified version, not that the user making the API call has the permission to import into the version or level. Use exportVersions to see which versions are available to the user for import. |
1 |
workflowStatus |
N |
Emits the workflow status for the associated level. I for "In Progress", S for "Submitted", R for "Rejected", A for "Approved" and L for "Locked". Only included in the response if workflow is enabled for this company, and a planning versionName or versionID is specified in the request. Workflow is not available on actuals versions. |
I |
isLinked |
Y |
Indicates whether the level is a linked level. 0 for no, 1 for yes. |
1 |
isElimination |
Y |
Indicates whether the level is an elimination level. 0 for no, 1 for yes. |
0 |
Contents of the Element |
|||
One nested level element for each direct child level of this level. |
attributes element |
|||
Tag Name |
attributes |
||
Description |
Container for one or more attribute elements. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
(none) |
|||
Contents of the Element |
|||
One or more attribute elements. |
attribute element |
|||
Tag Name |
attribute |
||
Description |
Represents a single non-blank level attribute mapping to which a level is associated. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
name |
Y |
The name of the level attribute |
Corporate Discount |
value |
Y |
The value of the level attribute associated with the level. |
Yes |
attributeID |
Y |
The internal system id number of the level attribute. |
20 |
valueID |
Y |
The internal system id number of the level attribute value. |
188 |
Contents of the Element |
|||
(none) |