Rules Fundamentals- A White Paper

TM1 Developer

White Paper©2009, Cubewise Pty Ltd

     

  © 2009, Cubewise Pty Ltd                Page 2 of 11 

CONTENTS 

 

1 Purpose Of This Paper .......................................................................................................................................................... 3 

2 Introduction .......................................................................................................................................................................... 3 

3 Creating Rules ....................................................................................................................................................................... 4 

4 Rules Syntax .......................................................................................................................................................................... 5 

5 Writing Your First Rule ......................................................................................................................................................... 6 

6 The Calculation Stack Explained ........................................................................................................................................... 9 

7 The N and C Filter ............................................................................................................................................................... 10 

8 Conclusion .......................................................................................................................................................................... 11 

 

   

     

  © 2009, Cubewise Pty Ltd                Page 3 of 11 

 

1 PURPOSE OF THIS PAPER 

This document aims to succinctly reveal to the TM1 developer the inner workings of TM1’s legendary calculation engine – TM1 Rules. It does not purport to design a system for you or show Best Practice. This is a whole subject in itself ‐ Rules Fundamentals must be fully grasped before Best Practice is understood and followed effectively. 

At  Cubewise,  we  believe  in  “simplifying  to  demystify”  –  the  inner‐workings  of  TM1  will  be  explained  by simulating a 2 dimensional cube to show the calculations taking place. 

Note:  This  is  the  sister  paper  to  Cubewise’s  “Feeders  Explained” White  Paper which  can  be  found  on  the Cubewise Website. 

 

2 INTRODUCTION 

Dimensions  add  data  “up  the  hierarchy”  to  give  aggregated  results. Non‐additive  calculations  such  as more complex calculations eg Sales = Price x Volume are performed in TM1’s “Rules” engine, where cross dimensional calculations are possible and the real power of TM1 as a modeling tool can be utilized. 

 

Here are some points of note; 

 

Each cube can have one rule file attached to it. 

Rule files are compiled as .rux files 

Rules can dominate natural dimension aggregations  if  required  (ie adding up averages up a hierarchy does not make sense) 

Rules “scope” is from a single cell to the whole cube’s cells. 

Rules calculate at runtime like hierarchy aggregations ie on‐demand 

Rules can calculate on cells which may be  input‐value based or ruled cells themselves. Consequently a complex  “automatic  calculation  chain” may be developed without  turning  to  technical developers  to shunt numbers around your system.    

    

     

  © 2009, Cubewise Pty Ltd                Page 4 of 11 

3 CREATING RULES 

To create a rule file for a cube, right click on a cube and choose “Create Rule”. 

 

 

 

The Rules Editor will appear. 

 

The editor includes direct access to the rules help files and shortcuts to TM1 syntax.   

   

     

  © 2009, Cubewise Pty Ltd                Page 5 of 11 

4 RULES SYNTAX 

Cells that are to be the result of calculations are called “Target” cells. Those cells that are the source of the 

calculations are called…”Source” cells! 

The basic syntax is as follows; 

[‘Target’] = N: [‘Source’] ; 

 

This could be something simple like: 

 

[‘Sales’] = N: [‘Cost of Sales’] * 2 ; 

 

Here are some points of note; 

Cells are surrounded by square brackets and elements are surrounded by single quotes.  

The N: asks “does this target cell contain all Numeric element types?” ie no Consolidations 

We can also use C: which asks “does this target cell contain at least one Consolidation element type?”  

If we do not put a C or N filter question then there is no filter at all 

Rule statements are finished with a “;”    

     

  © 2009, Cubewise Pty Ltd                Page 6 of 11 

5 WRITING YOUR  FIRST RULE 

You are now going to write your first rule. The cube that we will use will be the most basic 2 dimensional cube to 

allow the student the best chance of understanding the rule concepts first. 

 

   

 

Create a view of the Test cube with the Sales Account “1000” and the month dimension across the columns. Save the 

view as “Default”. It will be used again. 

 

   

Give yourself the best chance of getting the right result first time – view your target 

and source cells in the cube browser. 

     

  © 2009, Cubewise Pty Ltd                Page 7 of 11 

Add this rule to the rule file and click save. Recalculate the Default view. The 1000, Jul cell changes to 2. Notice the cell has grayed out showing the cell is not updatable now that a rule is reserved for this cell. 

  

   

     

  © 2009, Cubewise Pty Ltd                Page 8 of 11 

Now add the following rule and recalculate. 

 

 

Notice how the 3 populates all the cells except Jul. Notice also that “All Months” populates at 3! 

The trick to understanding how these numbers are populated is to think of TM1 calculating one cell at a time. Therefore, if we should take ‘1000’,’Jul’ as the first example and ask what its result is. A user may be querying a large data set with  this cell or  just  this one cell on  its own. Whatever  the query size, TM1 must perform  this “process” for each cell in a pre‐determined calculation order – or Calculation Stack;    

     

  © 2009, Cubewise Pty Ltd                Page 9 of 11 

6 THE  CALCULATION STACK EXPLAINED 

 

1. On user query (1000, Jul) the cell is passed to the TM1 server. 

2. If there is no rule file the result is sent back to the user based on exactly what is in the cell. 

a. If the cell has a consolidation element, then an internal Consolidation process calculates the cell – and then passes the result back to the user. 

3. If  there  is  a  rule  file,  then  Step 2  is hijacked until  the  rule  file has been  searched  for more  complex calculations (ie Ruled cells) reserved for this cell. 

4. If  the query has  found a  target area  in  the rule  file,  the calculation completes and passes back  to  the user – it has no “recursiveness”. 2a in the Calculation Stack does not run at all. 

a. If the target cell is dependent on a source cell (highly likely) then that cell must be resolved via a new calculation routine ie it will run the same Calculation Stack. 

As you can imagine from 4a, during Calculation, TM1 is performing a myriad of calculations in order to resolve a data set. 

Here are some points of note; 

The query approaches the rule file from the top, runs down questioning each cell area on the left hand side of the  file –  ie  it  tests  itself against all Target areas.  If  there  is a match  then  the  rule  is executed  ie  it  takes  its current cell information to the right hand side of the statement. The rules around the match are simple; if there are no “no”s when matching query elements in the same dimension to target elements ‐ then there is a match. 

    

     

  © 2009, Cubewise Pty Ltd                Page 10 of 11 

Therefore in this case, Aug is not matched with the first rule statement (see black arrow below). It now tries its luck on the next statement down. This statement has no Month element specified and therefore no “negative” is returned ‐ and the calculation is consequently performed. The result for (1000,Aug) is 3. 

 

 

7 THE  N AND C  FILTER 

Much confusion exists over rule calculations at N and C (aggregate)  level. In fact  it  is easily explained with our new knowledge of the rule calculation stack; 

If  the  Cell which  is  being  calculated  is  completely N  level  (ie  all  its  elements  are  lowest  level  and  have  no aggregations relationships in the dimension at all) then an N: filter on the right hand side of the rule will allow it through to be calculated. 

 

[‘1000’] = N: 3 ; 

Ie Jul, Aug etc are N and so is “1000”. It is an N level (sometimes called “Leaf”) cell 

 

If  the  Cell which  is  being  calculated  is  NOT  completely  N  level  (ie  it  has  at  least  one  element which  is  an aggregate) then a C: filter on the right hand side of the rule will allow it through to be calculated.  

 

[‘1000’] = C: 3 ; 

Ie “All Months” is a C and only this cell would show 3.  

 

If we choose not to designate N or C on the right hand side, then TM1 rules deems that you are not interested in filtering at all – ie all cells, whether leaf or otherwise will be allowed through to calculate on the right hand side 

[‘1000’] = 3 ; 

Ie Jul, Aug etc AND “All Months” would show 3.     

     

  © 2009, Cubewise Pty Ltd                Page 11 of 11 

8 CONCLUSION 

The  above  is merely  a  start  to  the  road  to mastering  TM1 Rules.  The  flexibility  and  integration of  this  rules 

language is unique among Enterprise BPM tools and is a route to deriving enormous value for your organization.  

Not enough emphasis is put on the ability of the TM1 system to auto‐calculate through a complex chain of cells 

– this allows for extremely complex modeling “the calculation chain” that can be scaled up to levels where real‐

world granular information can uncover valuable insights. Instead, spreadsheets and other technologies wholly 

unsuited to this task, are utilized to the long‐lasting detriment of the organization. 

To master Rules, you will need to  learn short cuts, branching tricks (such as IF and CONTINUE statements) and 

critically importantly – Feeders. We urge you to digest “Mastering Feeders” white paper which accompanies this 

paper.