One powerful feature of OAS is that it embeds the MAXL interpretor inside one of it's operation java classes and allows user to configure it to execute any MAXL command. This tutorial will provide a step by step guide to creating your own MAXL operation.
Below is an example of a MAXL operation that comes installed with OAS, the RunEssbaseAdHocCalc operation. You can see this if you open any OAS xml file that you save.
MAXL operations have a maxl parameter that represents the maxl statement template that OAS uses to replace with runtime values such as the essbase app and db names. Values in the maxl parameter that will be replaced are surrounded by ##'s .
In the example below the values inputted by the user in the task for calctext, app and db will be replace in the maxl statement.
execute calculation '##calctext##' on ##app##.##db##
In the image above the xpath attribute of the parameter tells the OAS GUI to query and fill in the values for the parameter so that the user does not have to type in these values directly. Xpath is a standard xml query language. Xpath's can either return a single value or a list. When they return a list the user sees a combo box.
In this example the essbaseconnection parameter will appear in the task as combo box since the xpath query returns a list of essbase connections.
Step by Step Guide
1) Create the operations element
2) Add the a) errors and b) required parameters . The errors parameter allows for controlling error handling in the maxl output when a command is run. For now we will leave it to detect the words error and invalid.
In this example we are creating an operation for creating a location alias. The maxl parameter is the maxl syntax for creating a location alias that comes from the Essbase Technical Reference guide. Notice the ##'s surrounding the required parameter values aliasname, app, db, toapp, todb, server, user, and password. These are the properties that the user will input using the OAS task wizard and get replaced in the maxl statement when the automation is executed to generate a valid maxl statement that Essbase understands.
If we save the xml file right now and pull it up in OAS, when we create a task using the CreateLocationAlias operation we should see a task wizard screen that looks like this one below. Notice that all the required properties are list as text boxes since we did not define any xpath attributes. We will go back and add this later for the essbaseconnection, app and db parameters.
But as it is currently defined the CreateLocationAlias operation is now useable in a task for creating automations.
3) Add xpath attributes for user friendly combo boxes and automatic fill-ins for the essbaseconnection, app and db required properties.
Rather than retype the lines I just copied the xpaths from the RunEssbaseAdHocCalc operation. Notice the parameter names essbaseconnection,app, and db are the exact ones listed in the required parameter value list.
Saving the xml file and then loading it into OAS again shows this screen below when creating a task using the CreateLocationAlias operation. Notice that the essbaseconnection property is now a combo box that shows all Essbase connections previous defined. Choosing an essbaseconnection fills in the app and db automatically for the user.
The CreateLocationAlias operation we just created is now ready to give to an end user to use for creating automations. The user does not need to know maxl. They simply need to fill in the text boxes.
Taking It A Step Further
If wanted to take this a step further we can use an OAS RunSQLLoop operation to build the maxl statement at runtime. This means we can dynamic create maxl statements using data from a database table to setup location alias, create filters for users, define partitions and so on.
A final word on XPath
The XPaths xml queries used in this example look complicated but are completely optional. If you don't specify anything the OAS task wizard defaults to a plain old text box. Not very fancy but they are still better than writing maxl. A full explain of Xpath is beyond the scope of this tutorial but many good sources of Xpath information exist on the net.
