Run Batch Outline Edit
/essbase/rest/v1/applications/{application}/databases/{database}/boe
Executes batch outline editing process. Based on the XML or JSON body, adds or removes members from the outline in the active cube.
Request
- application/json
- application/xml
-
application: string
Application name.
-
database: string
Database name.
Batch outline JSON/XML.
object-
editActions(optional):
array editActions
The outline editing action to perform. See example for details on each.
- otlUpdate - change outline properties
- mbrUpdate - change member properties
- mbrAdd - add a member
- mbrDelete - delete a member
- mbrRename - rename a member
- mbrMove - move a member
- mbrAssoc - make or remove member attribute associations
- dimAdd - add a dimension
- smartListAddOrUpdate - add or update a text list
- dimUpdate - change dimension name or properties
- dimAssoc - make or remove dimension attribute associations
- markForDelete - mark a dimension to be deleted
- deleteMarked - delete marked dimension
- sortChildren - sort a hierarchy
-
jsonformatLog(optional):
boolean
-
keepTransaction(optional):
boolean
Whether to keep transactions:
trueorfalse -
otlVersion(optional):
integer
-
restructOption(optional):
string
Allowed Values:
[ "ALL_DATA", "NO_DATA", "LOW_DATA", "IN_DATA" ]Restructure option.
ALL_DATAto preserve all existing data (this is the default),NO_DATAto discard all existing data,LOW_DATAto preserve existing level 0 blocks (applicable to block storage only),IN_DATAto preserve existing input-level blocks (applicable to block storage only). -
validate(optional):
boolean
Whether to validate the outline:
trueorfalse -
validateFormulas(optional):
boolean
Whether to validate formulas:
trueorfalse
arrayThe outline editing action to perform. See example for details on each.
- otlUpdate - change outline properties
- mbrUpdate - change member properties
- mbrAdd - add a member
- mbrDelete - delete a member
- mbrRename - rename a member
- mbrMove - move a member
- mbrAssoc - make or remove member attribute associations
- dimAdd - add a dimension
- smartListAddOrUpdate - add or update a text list
- dimUpdate - change dimension name or properties
- dimAssoc - make or remove dimension attribute associations
- markForDelete - mark a dimension to be deleted
- deleteMarked - delete marked dimension
- sortChildren - sort a hierarchy
objectResponse
- application/json
- application/xml
200 Response
OK
The batch outline edit completed successfully.
400 Response
Bad Request
Failed to complete batch outline editing. The output may be invalid, the sequence of metadata operations may be incorrect, or saving the outline may have failed.
Examples
The following example describes batch outline editing, which you can perform from the Essbase REST API using either JSON or XML to structure the edit request.
In batch outline editing, you submit the Essbase application and cube name as path parameters, and you submit a JSON or XML object as the request body containing the outline edit specification.
The edit actions you can specify in the request body are:
- otlUpdate - to change outline properties
- mbrUpdate - to change member properties
- mbrAdd - to add a member
- mbrDelete - to delete a member
- mbrRename - to rename a member
- mbrMove - to move a member
- mbrAssoc - to make or remove member attribute associations
- dimAdd - to add a dimension
- smartListAddOrUpdate - to add or update a text list
- smartListDelete - to remove a text list
- dimUpdate - to change dimension name or properties
- dimAssoc - to make or remove dimension attribute associations
- markForDelete - to mark a dimension for deletion
- deleteMarked - to delete a marked dimension
- sortChildren - to sort a hierarchy
Each edit action uses further syntax elements as detailed below. A JSON request body example follows after the descriptions.
otlUpdate
Use this action to make updates to the outline properties.
| Object (JSON) or Element (XML) | Details |
|---|---|
| dateFormatValue: date_format | Optional. Specification of the date format. Requires enableMemberType to be true. Example (JSON) Description Use one of the following literal strings to indicate the preferred date format.
|
| aliasTable: name | Optional. Alias tables to be added (can repeat up to 56 times). |
| removeAliasTable: name | Optional. Alias tables to be removed (can repeat for all alias tables). |
| disableDtsMbr: {mbrName: name} | Optional. Disable a pre-defined Dynamic Time Series member. |
| enableDtsMbr {mbrName: name, number: genNum} | Optional. Enable a pre-defined Dynamic Time Series member (for example, Q-T-D) at the specified generation number (for example, 2. |
| setDtsMbrAlias: {dtsAlias {aliasTable: name, alias: value}, mbrName: name} | Optional. Associate aliases for Dynamic Time Series members. |
| attributeSpec | Optional. Specifications for handling member names in attribute dimensions.The settings include:
|
| enableMemberType: true|false | Optional. If true, enables typed measures for this outline. |
| autoConfigure: true|false | Optional. If true, automatically configures the dimension storage (as dense or sparse) when a block-storage outline is saved. |
mbrUpdate
Use this action to change member properties.
| Object (JSON) or Element (XML) | Details |
|---|---|
| thisMbr: mbrName | Required. The member that is the focus of this operation. |
| mbrInfo | Member information you can update. Options include:
|
| isMbrId: true | false | Optional. If true, member specification objects for this action are passed using member IDs. A member ID is a unique key that identifes a member in an outline. |
mbrAdd
Use this action to add a member.
| Object (JSON) or Element (XML) | Details |
|---|---|
| mbrInfo | Optional. Member information, as defined in mbrUpdate. |
| mbrName: mbrName | Required. Member name. |
| parent: mbrName | Required. Parent of the member being added. |
| preSibling: mbrName | Optional. Previous sibling of the member being added. If omitted, the new member is added the first child of the parent. |
| isMbrId: true | false | Optional. If true, member specification objects for this action are passed using member IDs. A member ID is a unique key that identifes a member in an outline. |
mbrDelete
Use this action to remove members (including dimensions).
| Object (JSON) or Element (XML) | Details |
|---|---|
| thisMbr: mbrName | Required. The member that is the focus of this operation. |
| isMbrId: true | false | Optional. If true, member specification objects for this action are passed using member IDs. A member ID is a unique key that identifes a member in an outline. |
mbrRename
Use this action to rename members (including dimensions).
| Object (JSON) or Element (XML) | Details |
|---|---|
| thisMbr: mbrName | Required. The member that is the focus of this operation. |
| mbrName: mbrName | Required. New member name. |
| isMbrId: true | false | Optional. If true, member specification objects for this action are passed using member IDs. A member ID is a unique key that identifes a member in an outline. |
mbrMove
Use this action to move members.
| Object (JSON) or Element (XML) | Details |
|---|---|
| thisMbr: mbrName | Required. The member that is the focus of this operation. |
| parent: mbrName | Required. Parent of the member (in its new location). |
| preSibling: mbrName | Optional. Previous sibling of the member (in its new location). If omitted, the member is added as the first child of the parent. |
| isMbrId: true | false | Optional. If true, member specification objects for this action are passed using member IDs. A member ID is a unique key that identifes a member in an outline. |
mbrAssoc
Use this action to make or remove member attribute associations.
| Object (JSON) or Element (XML) | Details |
|---|---|
| thisMbr: mbrName | Required. The member that is the focus of this operation. |
| attrDim: dimName | Required. Name of the attribute dimension. |
| attrMbr: mbrName | Required. Name of the attribute member to associate (or disassociate) with the base member. |
| remove: true | false | Optional. If true, this action removes an attribute association instead of adding it. The default is false. |
| isMbrId: true | false | Optional. If true, member specification objects for this action are passed using member IDs. A member ID is a unique key that identifes a member in an outline. |
dimAdd
Use this action to add a dimension.
| Object (JSON) or Element (XML) | Details |
|---|---|
| properties | Optional dimension properties.
|
| dimName: dimName | Name of the dimension. |
| preSibling: dimName | Optional. Previous sibling of the dimension being added. |
smartListAdd, smartListUpdate
Use these actions to add or update a text list object. Text list objects are a way to store metrics as textual values, when your accounts dimension is designed to work with text measures. You can implement text measures when your outline is enabled to work with typed measures.
| Object (JSON) or Element (XML) | Details |
|---|---|
| smartlistitem | All elements are required.
|
| smartListName | Name of the text list to add or update. |
JSON Example
{
"editActions" :
[
{ "otlUpdate" :
{
"enableMemberType" : "true"
}
},
{
"smartListAdd" :
{
"smartListName": "Customer Satisfaction Level",
"smartlistitem": {
"smartListMissingName": "No Data",
"smartListOutOfRangeName": "Invalid Range",
"smartlistIDTextPair": [
{
"smartListID": "1",
"smartListText": "High"
},
{
"smartListID": "2",
"smartListText": "Medium"
},
{
"smartListID": "3",
"smartListText": "Low"
}
]
}
}
}
]
}smartListDelete
Use this action to remove a text list.
| Object (JSON) or Element (XML) | Details |
|---|---|
| smartListName | Name of the text list to remove. |
JSON Example
{
"editActions" :
[
{
"smartListDelete" :
{
"smartListName": "Customer Satisfaction Level"
}
}
]
}dimUpdate
Use this action to change a dimension's name or properties.
| Object (JSON) or Element (XML) | Details |
|---|---|
| properties | Dimension properties, as defined in dimAdd. |
| dimName: dimName | Name of the dimension. |
dimAssoc
Use this action to make or remove dimension attribute associations.
| Object (JSON) or Element (XML) | Details |
|---|---|
| dimName: dimName | Name of the dimension. |
| attrDim: dimName | Required. Name of the attribute dimension. |
| remove: true | false | Optional. If true, this action removes an attribute association instead of adding it. The default is false. |
markForDelete
Use this action to mark previous member additions in a dimension for deletion. They will be deleted when you use deleteMarked.
| Object (JSON) or Element (XML) | Details |
|---|---|
| dimName: dimName | Name of the dimension. |
Follow this workflow to mark and delete members in batch outline editing scripts:
- Add a new dimension, Dim1, to a sample cube.
-
To Dim1,
- Add mbrA.
- Add mbrB.
- Add mbrC.
- Add mbrD.
-
Mark all previously added members for deletion.
-
Add mbrC and mbrD again.
-
Delete marked members.
Result:
Dim1 +-mbrC +-mbrD
JSON Example
{
"editActions" :
[
{ "dimAdd" :
{
"dimName" : "Dim1"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrA",
"parent" : "Dim1"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrB",
"parent" : "Dim1",
"preSibling" : "mbrA"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrC",
"parent" : "Dim1",
"preSibling" : "mbrB"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrD",
"parent" : "Dim1",
"preSibling" : "mbrC"
}
},
{ "markForDelete" :
{
"dimName" : "Dim1"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrC",
"parent" : "Dim1",
"preSibling" : "mbrB"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrD",
"parent" : "Dim1",
"preSibling" : "mbrC"
}
},
{ "deleteMarked" :
{
"dimName" : "Dim1"
}
}
]
}deleteMarked
Use this action to delete marked member additions. See markForDelete for the workflow and example.
| Object (JSON) or Element (XML) | Details |
|---|---|
| dimName: dimName | Name of the dimension. |
sortChildren
Use this action to sort a hierarchy.
| Object (JSON) or Element (XML) | Details |
|---|---|
| mbrName: mbrName | Required. Member name. |
| sortOption | ASCENDING or DESCENDING |
| sortRecursive | Include all descendants in the sort. The default is true. |
| isMbrId: true | false | Optional. If true, member specification objects for this action are passed using member IDs. A member ID is a unique key that identifes a member in an outline. |
{
"editActions" : [
{ "dimAdd" :
{
"dimName" : "Dim1"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrA",
"parent" : "Dim1"
}
},
{ "mbrAdd" :
{
"mbrName" : "mbrB",
"parent" : "Dim1",
"preSibling" : "mbrA"
}
},
{ "sortChildren" :
{
"mbrName" : "Dim1",
"sortOption" : "DESCENDING",
"sortRecursive" : "false"
}
}
]
}Result
Dim1
+-mbrB
+-mbrAScript with cURL Command
The calling user's ID and password are variables whose values are set in properties.bat.
The cURL command submits the outline editing directives from the JSON file outline_edits.json.
call properties.bat
curl -X POST "https://myserver.example.com:9001/essbase/rest/v1/applications/Sample/databases/Basic/boe" -H Accept:application/json -H Content-Type:application/json --data "@./outline_edits.json" -u %User%:%Password%Example of JSON Object
This example shows the outline editing instructions in JSON format (the outline_edits.json file posted above).
{
"editActions" : [
{ "otlUpdate" :{
"enableMemberType" : "true",
"dateFormatValue" : "dd Month yyyy"
}
},
{ "mbrUpdate" :{
"thisMbr" : "Product",
"mbrInfo" : {
"category" : "NONE",
"solveOrder" : "5",
"consolidation" : "+",
"comment" : "Member Comment",
"twoPassCalc" : "false"
},
"isMbrId" : "false"
}
},
{ "mbrUpdate" :{
"thisMbr" : "Sales",
"mbrInfo" : {
"formatStr" : "MdxFormat(IIF(CellValue() < 0, 'Negative','Positive'))"
},
"isMbrId" : "false"
}
},
{ "mbrAdd" :{
"mbrName" : "YTDSales",
"parent" : "Margin",
"preSibling" : "COGS",
"mbrInfo" : {
"formula" : "@ACCUM(Sales);"
},
"isMbrId" : "false"
}
},
{ "mbrRename" :{
"thisMbr" : "YTDSales",
"mbrName" : "YTD_Sales",
"isMbrId" : "false"
}
}
]
}