Documenting IBM Planning Analytics

Written by Chris Sands

On my first day as a programmer my boss took me aside and said the thing that he hated more than anything was the terrible state of the documentation of the systems that I was going to be working on. Programs that had no internal documentation. Programs that had no external documentation. Programs that had misleading documentation. Programs that were coded esoterically.  Programs that only certain people could touch. It was very stressful. It was like playing Kerplunk professionally.

Nearly 35 years later, we have surely moved past such primitive times. My experience with IBM Planning Analytics systems that I’ve looked at suggests that things haven’t got much better. The excuses haven’t changed though; ‘It takes too long to do’, ‘I wasn’t sure what I was going to do before I did it’, ‘I know what it’s doing’, ‘if you’ve got a problem, just ask me’.

Easy to read and understand IBM Planning Analytics rules and processes really save time, money, and stress in the long run and give users the confidence to make changes and use code to expand their usage of the software.

Here are 10 simple documentation pointers that I would recommend in IBM Planning Analytics and 2 documentation methods that I use outside of IBM Planning Analytics. They are not rocket science and you will have others you use, or you may disagree with some (especially #3!).

1. Have a naming convention.

Every organisation will have different conventions. I like to use lowercase ‘v’ for variables, ‘p’ for parameters, ‘vp’ for variables that have been created from parameters and ’s’ for values coming from an outside source.

2. Use meaningful variable names.

Rather than use ‘vPrmChk’ for a variable that will check the parameters entered, why not call it vCheckEnteredParameters. It’s easier to see what it’s doing.

3. Use CamelCase.

I find this the most readable and easy to enter method of naming. So, I prefer ‘UnitsSold’ to ‘Units_Sold’ or ‘Units Sold’

4. Don’t be frightened of using text to set a variable.

Instead of ‘IF (vPrmChk=1) …’ . It’s much easier to read ‘IF (vCheckEnteredParameters = ‘In Error’) …

5. Write the comments that explain what is happening before you write your code.

You can enter the comments:

# Check if the product element is valid

#  If product element is not valid

#  then issue error message.

Then you can code it later, so it reads:

# Check if the product element is valid

#  If product element is not in the dimension

#    then issue error message.

IF  (DIMIX(x.Product, vProductElement) = 0)   ;

vProductExistsErrorMessage = ‘[‘ | vProductElement | ‘] does not exist in the Product dimension’  ;

vSetErrorMessageCheck.       = ‘Error In Process’                                                                           ;

ENDIF                                                          ;

6. Identify your rules.

We set up rules as, number + cube name + description, for instance, ‘010-Sales-Average Sales Price’. The means it’s easy to tie up your rules and feeders as you can put your feeder to the rule under the same rule name. You can have a list at the front of the rules file that, if nothing else, shows your colleagues that what follows was at least planned.

7. Layout your code.

My heart sinks when I see code that is bunched up. It’s much better to have white space and your ‘=‘ and ‘;’ signs lined up. Put your while loops, conditional commands, and sequential statements in aligned blocks so that it’s easy to work out what relates to what.

8. Get a colleague to look over your code, and if you are well organised, your plan.

They will spot potential weaknesses, recommend good ways of doing things, point you to code that they’ve already cut and help you keep to your organisation’s house style.

 9. Make it easy to remember

In the rules file I like to put a commented table that has all the dimensions in the cube

in the order that they are and a line that has them in the sequence that they appear. I find this a very useful aide-memoire when I’m looking at or amending the rules.

10. Get rid of old code.

When I’m changing a rules file, I take a copy of the .RUX file and keep it in a sub directory for old processes and rules with a suffix on the name to include the date of the change e.g., Sales-20210914.rux. This keeps the code in its pre-changed form and means I can delete the old code out keeping the actual rules file tidy for colleagues. If they want to look at previous versions, they can pull older versions up and see what the code was prior to the changes. If you have Notepad ++ you can pull up all the versions in one session, which can be handy.

Some documentation that is external to IBM Planning Analytics that I find helpful are old school, but they really work in explaining the system to your users and your colleagues who may have to maintain your code when you are unavailable. They are Data Flow Diagrams (DFDs) and Flow Charts. Rather than struggling with PowerPoint I recommend using LucidChart as it is very easy to use, looks great and is easy to share output with colleagues. Just one pointer, in your data flow diagram document the business process, which might contain one or many IBM Planning Analytics processes, as well as other processes e.g., Excel Macros or SQL triggers.