Rules Fundamentals- A White Paper

TM1 Developer

White Paper
2009, Cubewise Pty
Ltd

CONTENTS

1PurposeOfThisPaper..........................................................................................................................................................3
2Introduction..........................................................................................................................................................................3
3CreatingRules.......................................................................................................................................................................4
4RulesSyntax..........................................................................................................................................................................5
5WritingYourFirstRule.........................................................................................................................................................6
6TheCalculationStackExplained...........................................................................................................................................9
7TheNandCFilter...............................................................................................................................................................10
8Conclusion..........................................................................................................................................................................11

2009,CubewisePtyLtd

Page2of11

1PURPOSEOFTHISPAPER
ThisdocumentaimstosuccinctlyrevealtotheTM1developertheinnerworkingsofTM1slegendarycalculation
engineTM1Rules.ItdoesnotpurporttodesignasystemforyouorshowBestPractice.Thisisawholesubject
initselfRulesFundamentalsmustbefullygraspedbeforeBestPracticeisunderstoodandfollowedeffectively.
At Cubewise, we believe in simplifying to demystify the innerworkings of TM1 will be explained by
simulatinga2dimensionalcubetoshowthecalculationstakingplace.
Note: This is the sister paper to Cubewises Feeders Explained White Paper which can be found on the
CubewiseWebsite.

2INTRODUCTION
Dimensions add data up the hierarchy to give aggregated results. Nonadditive calculations such as more
complexcalculationsegSales=PricexVolumeareperformedinTM1sRulesengine,wherecrossdimensional
calculationsarepossibleandtherealpowerofTM1asamodelingtoolcanbeutilized.

Herearesomepointsofnote;

Eachcubecanhaveonerulefileattachedtoit.
Rulefilesarecompiledas.ruxfiles
Rules can dominate natural dimension aggregations if required (ie adding up averages up a hierarchy
doesnotmakesense)
Rulesscopeisfromasinglecelltothewholecubescells.
Rulescalculateatruntimelikehierarchyaggregationsieondemand
Rulescancalculateoncellswhichmaybeinputvaluebasedorruledcellsthemselves.Consequentlya
complex automatic calculation chain may be developed without turning to technical developers to
shuntnumbersaroundyoursystem.

2009,CubewisePtyLtd

Page3of11

3CREATINGRULES
Tocreatearulefileforacube,rightclickonacubeandchooseCreateRule.

TheRulesEditorwillappear.

TheeditorincludesdirectaccesstotheruleshelpfilesandshortcutstoTM1syntax.

2009,CubewisePtyLtd

Page4of11

4RULESSYNTAX
CellsthataretobetheresultofcalculationsarecalledTargetcells.Thosecellsthatarethesourceofthe
calculationsarecalledSourcecells!
Thebasicsyntaxisasfollows;
[Target]=N:[Source];

Thiscouldbesomethingsimplelike:

[Sales]=N:[CostofSales]*2;

Herearesomepointsofnote;

Cellsaresurroundedbysquarebracketsandelementsaresurroundedbysinglequotes.

TheN:asksdoesthistargetcellcontainallNumericelementtypes?ienoConsolidations

WecanalsouseC:whichasksdoesthistargetcellcontainatleastoneConsolidationelementtype?

IfwedonotputaCorNfilterquestionthenthereisnofilteratall

Rulestatementsarefinishedwitha;

2009,CubewisePtyLtd

Page5of11

5WRITINGYOURFIRSTRULE
Youarenowgoingtowriteyourfirstrule.Thecubethatwewillusewillbethemostbasic2dimensionalcubeto
allowthestudentthebestchanceofunderstandingtheruleconceptsfirst.

Giveyourselfthebestchanceofgettingtherightresultfirsttimeviewyourtarget
andsourcecellsinthecubebrowser.

CreateaviewoftheTestcubewiththeSalesAccount1000andthemonthdimensionacrossthecolumns.Savethe
viewasDefault.Itwillbeusedagain.

2009,CubewisePtyLtd

Page6of11

Addthisruletotherulefileandclicksave.RecalculatetheDefaultview.The1000,Julcellchangesto2.Notice
thecellhasgrayedoutshowingthecellisnotupdatablenowthataruleisreservedforthiscell.

2009,CubewisePtyLtd

Page7of11

Nowaddthefollowingruleandrecalculate.

Noticehowthe3populatesallthecellsexceptJul.NoticealsothatAllMonthspopulatesat3!
ThetricktounderstandinghowthesenumbersarepopulatedistothinkofTM1calculatingonecellatatime.
Therefore,ifweshouldtake1000,Julasthefirstexampleandaskwhatitsresultis.Ausermaybequeryinga
large data set with this cell or just this one cell on its own. Whatever the query size, TM1 must perform this
processforeachcellinapredeterminedcalculationorderorCalculationStack;

2009,CubewisePtyLtd

Page8of11

6THECALCULATIONSTACKEXPLAINED

1. Onuserquery(1000,Jul)thecellispassedtotheTM1server.
2. Ifthereisnorulefiletheresultissentbacktotheuserbasedonexactlywhatisinthecell.
a. Ifthecellhasaconsolidationelement,thenaninternalConsolidationprocesscalculatesthecell
andthenpassestheresultbacktotheuser.
3. If there is a rule file, then Step 2 is hijacked until the rule file has been searched for more complex
calculations(ieRuledcells)reservedforthiscell.
4. If the query has found a target area in the rule file, the calculation completes and passes back to the
userithasnorecursiveness.2aintheCalculationStackdoesnotrunatall.
a. Ifthetargetcellisdependentonasourcecell(highlylikely)thenthatcellmustberesolvedviaa
newcalculationroutineieitwillrunthesameCalculationStack.
Asyoucanimaginefrom4a,duringCalculation,TM1isperformingamyriadofcalculationsinordertoresolvea
dataset.
Herearesomepointsofnote;
Thequeryapproachestherulefilefromthetop,runsdownquestioningeachcellareaonthelefthandsideof
the file ie it tests itself against all Target areas. If there is a match then the rule is executed ie it takes its
currentcellinformationtotherighthandsideofthestatement.Therulesaroundthematcharesimple;ifthere
arenonoswhenmatchingqueryelementsinthesamedimensiontotargetelementsthenthereisamatch.

2009,CubewisePtyLtd

Page9of11

Thereforeinthiscase,Augisnotmatchedwiththefirstrulestatement(seeblackarrowbelow).Itnowtriesits
luckonthenextstatementdown.ThisstatementhasnoMonthelementspecifiedandthereforenonegative
isreturnedandthecalculationisconsequentlyperformed.Theresultfor(1000,Aug)is3.

7THENANDCFILTER
MuchconfusionexistsoverrulecalculationsatNandC(aggregate)level.Infactitiseasilyexplainedwithour
newknowledgeoftherulecalculationstack;
If the Cell which is being calculated is completely N level (ie all its elements are lowest level and have no
aggregationsrelationshipsinthedimensionatall)thenanN:filterontherighthandsideoftherulewillallowit
throughtobecalculated.

[1000]=N:3;
IeJul,AugetcareNandsois1000.ItisanNlevel(sometimescalledLeaf)cell

If the Cell which is being calculated is NOT completely N level (ie it has at least one element which is an
aggregate)thenaC:filterontherighthandsideoftherulewillallowitthroughtobecalculated.

[1000]=C:3;
IeAllMonthsisaCandonlythiscellwouldshow3.

IfwechoosenottodesignateNorContherighthandside,thenTM1rulesdeemsthatyouarenotinterestedin
filteringatallieallcells,whetherleaforotherwisewillbeallowedthroughtocalculateontherighthandside
[1000]=3;
IeJul,AugetcANDAllMonthswouldshow3.

2009,CubewisePtyLtd

Page10of11

8CONCLUSION
The above is merely a start to the road to mastering TM1 Rules. The flexibility and integration of this rules
languageisuniqueamongEnterpriseBPMtoolsandisaroutetoderivingenormousvalueforyourorganization.
NotenoughemphasisisputontheabilityoftheTM1systemtoautocalculatethroughacomplexchainofcells
thisallowsforextremelycomplexmodelingthecalculationchainthatcanbescaleduptolevelswherereal
worldgranularinformationcanuncovervaluableinsights.Instead,spreadsheetsandothertechnologieswholly
unsuitedtothistask,areutilizedtothelonglastingdetrimentoftheorganization.
TomasterRules,youwillneedtolearnshortcuts,branchingtricks(suchasIFandCONTINUEstatements)and
criticallyimportantlyFeeders.WeurgeyoutodigestMasteringFeederswhitepaperwhichaccompaniesthis
paper.

2009,CubewisePtyLtd

Page11of11