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

Here are 10 simple documentation pointers and methods that we would recommend in IBM Planning Analytics.

Have a naming convention #

Every organisation will have different conventions. We 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.  

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.  

Use CamelCase   #

We find this very readable and an easy to enter method of naming. So, we prefer ‘UnitsSold’ to ‘Units_Sold’ or ‘Units Sold’ 

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’) … 

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; 

Identify your rules #

We set up rules as, number + cube name + description, for instance, ‘010-Sales-Average Sales Price’. This 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.  

Layout your code #

It helps with readibility 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. 

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

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

Make it easy to remember  #

In the rules file we 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. This can be a useful aide-memoire when looking at or amending rules.  

Get rid of old code #

When changing a rules file, 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 the old code can be deleted, 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 other documentation that can help if you need to explain the system to users and colleagues include Data Flow Diagrams (DFDs) and Flow Charts. Rather than struggling with PowerPoint some of our consultants use LucidChart. 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.