Background & About

Jessub (Java Essbase Substitutions) is a small, simple, and free utility for use in Essbase automation routines. Although there is nothing specific to Essbase in the files (i.e., it could be used with any process in which you want to replace a certain token in a file), it is a small evolution of a concept that has served me well in many instances.

Simply put, Jessub will read in a template file that you create, search for certain tokens, then write a new file with those tokens replaced with different values. Generally speaking, the tokens will be the contents of a MaxL script statement to update a substitution variable. In effect, we are generating a new MaxL script on the fly and running it against the target Essbase server.

There are numerous ways that updating substitution variables can be achieved: you can login to EAS and update them yourself. You could write a Java program using the Essbase Java API and update them. You can use a MaxL script to update them.

Generating a MaxL script is kind of a hybrid approach with a few useful characteristics. By not using the Java API, we don't have to worry about the version of the Java Essbase JAR file, we just need to have the MaxL script interpreter available. We are also saved from having to do custom programming.

Generating the MaxL script dynamically is a tried and true approach that has served me well in many environments because it's extremely easy to setup, and has no dependencies that are hard to meet (a Java JRE and a MaxL interpreter).

The Jessub interpreter recognizes tokens written in a sort of "micro-language", which provides for some simple ways to generate many kinds of variables. Quite often the need to update substitution variables is timing-based, meaning that the target value of the substitution variable has something to do with the date or an aspect of the date, such as the month, day, or year.

How to use

Given an input text file template with Jessub micro-codes in it, we run Jessub, pass in the file, the name of the output file, and any other parameters. Jessub will read in the template, replace the tokens, and write the defined file to the output.

For example, let's say the contents of our file look like this:

The current day: ${Day_%1$td;NOW()}

The resulting output file will look like this (depending on day that the program is run this will be different:

The current day: Day_1

The format here is that a Jessub expression is a dollar-sign ($), followed immediately by a squiggly bracket ({), the expression contents, then an ending squiggly bracket.

The first thing inside the squiggly bracket is the format string that the Jessub expression will use. Although in the above example it looks complex, it's actually just a normal Java format string that could (and is) used with the String.format() function. In other words, we haven't invented an entirely new and arcane syntax to use here: we are leveraging all of the power and effort that has gone in to developing Java string formats (which are based on C printf string formats, and so on). The Java 6 string format page can be found here:

http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax

After the string format, we have a semi-colon (;), followed by all of the arguments for the string format. There are three different types of arguments that Jessub recognizes:

• NOW()
• ENV()

NOW()

Since many substitution variable updates have to do with the date, there is the NOW() function for generating a date. Whatever the date is when the script is run, NOW() will resolve to the current date, and then we can use the Java format string to get what we want. In the above example, the code "Day_%1$td" is a Java format string that evaluates to "Day_" and then the %1$td resolves to the day of the month from the date object that is passed in. As mentioned on the Java format string description page, the %1 refers to argument one of all of the arguments that are passed in. In addition to just grabbing the current time and date, we can also pass some parameters in to our NOW() function to adjust the date in a certain way. We can adjust the current date by a certain number of days, months, or years. For example, let's say that we want the contents of the substitution variable to be the previous date with regard to the current day. We can simply adjust the date value:

Yesterday: ${Day_%1$td;NOW(DAYS:-1)}

This is the same as our earlier example, except we are adjusting the days by negative one ("go back in time from the current date by 1 day, then use that as the value to format with"). We can adjust by months and years to if we want:

Some weird date: ${Day_%1$td;NOW(DAYS:-1,MONTHS:-1,YEARS:-1)}

This uses the date that is one year, one month, and one day prior to the current date.

ENV()

We can get the string value of an environment variable, if we want. We just use the ENV() function with the name of the environment variable.

The path: ${%s;ENV(PATH)}

Multiple values

We can format multiple values, just like a String.format() call, by separating different parameters with a semi-colon:

Multiple: ${%s %s;PARAM(foo);PARAM(bar)}

Running on the command line

We just need to run the Java jar from the command line and pass in the name of the files, plus any parameters we want:

java -jar jessub-1.0.0-dist.jar inputfile.msh.template outputfile.msh

Automating

Once we have our template setup properly, we can easily automate this in a batch or shell file that might look like this:

cd /d %~dp0 java -jar jessub-1.0.0-dist.jar inputfile.msh.template outputfile.msh essmsh outputfile.msh

Other

Jessub uses the excellent JodaTime library for working with dates. This library has a much more sane programming interface than Java's native Date/Calendar classes. JodaTime also has support for arbitrary calendar systems. Although I have not tried it, it is possible to develop a calendar plugin of sorts that could be used to adapt a normal calendar to a business fiscal calendar of any kind. For example, many businesses use a 13 period calendar for planning and other purposes. Since the source code is open, you are free to experiment with how this could work. Time permitting, I may attempt to develop it myself.

Building

Jessub is a Maven project designed for easy builds and updates. Simply run a Maven package command from the root project folder, and all files will be generated. The runtime JAR file has dependencies (Joda Time) built in so it can be run as a standalone JAR.

Thanks

Thank you for checking out this software. It is simple, but useful, and a good administrator is a lazy administrator that wants to sleep in instead of updating substitution variables.