HFM Business Rule Writing Tips and Techniques Presentation Transcript
1. Hyperion Financial Management: Business Rule Writing W riting Tips and Techniques Chris Barbieri Consolidation Practice Director Oracle ACE Ranzal & Associates *With significant content from “JimTheRulesGuy” Heflin & Geordan Drummond of Ranzal ☺ Topics • Basics of HFM rules in classic Vbscript • Advanced topics in classic mode • Debugging • Intro to Calc Manager • Questions ? 3. HFM Rules The basics 4. “A good rules file is an empty one.” - Anonymous 5. What are we doing with rules in HFM? •Rules primarily move data within the system •Also provide NoInput, Input, ICT intersections •It‟s always a pull* •Pull to all valid intersections on the left hand side of the equation from the intersections on the right •Always think in 12 dimensions that comprise the point of view. •* Except in consolidation rules, Sub Allocate, and ImpactStatus… •Don‟t focus on the vbscript •Do focus on “where can we read from and where can we write to?” 6. HFM Rules 101: There are two main functions • The HS.Exp function is used to write data to the database HFM destination = source data from HFM • The HS.GetCell function is used to retrieve data from the database A variable = data from HFM 7. Tip 1: Know what dimensions are valid on each side of the equation. On the left hand side: On the right hand side: • The current point of view is set, these • Any of the 12 dimensions dimensions cannot be specified: can be specified. – Scenario – Year – Period – Entity – Value • These can be specified – Account – ICP – Custom 1-4 can be specified. • View is a special case – Based on the ZeroView settings and the scenario default d efault view 8. Example: Invalid HS.Exp • Rollforward beginning retained earnings HS.Exp “A#BegRetainedEarnings.P#January” & _ “= A#EndRetEarn.Y#Prior.P#December” & _ “+ A#NetIncome.Y A#NetIn come.Y#Prior.P# #Prior.P#Decemb December.W#YT er.W#YTD” D” 9. Tip 2: Data is written to the base level elements of a dimension In the following dimensions you can only write to a base level elements: elements – Account – ICP – Custom1 – Custom2 – Custom3 – Custom4 So only base members on the left hand side 10. Tip 3: Implicit vs. Explicit Intersections Intersections • Dimensions not explicitly on the right hand side of an equation are implicitly lifted from the left hand side and/or the POV. • Very important to explicitly define what is on the left and right hand side of an equation. Don‟t leave rules to guesswork – be explicit! 11. The left hand drive s the equation HS.Exp “A#Account3.C1#Chips = A#Account4” HS.Exp “A#Account3.C1#Olap = A#Account4” 12. The same formula reversed HS.Exp "A#Account3 = A#Account4.C1#Chips" HS.Exp "A#Account3 = A#Account4.C1#Olap" Last one in wins! result • 13. Tip 4: A statement will run for all valid intersections of data. • This is often not the desired result For Example an account “Account1” has 8 valid base members in Custom1 HS.Exp “A#Account1 = 10” • What will the total value of Account1 be for Custom1? 14. Results in “10” in every valid intersection 15. Tip 6: If you can not specify a dimension on left hand side of the equation, then control when the statements are run. If HS.Period.IsFirst = True Then HS.Exp “A#BegRetainedEarnings” & _ “= A#EndRetEarn. A#EndR etEarn.Y#Prior.P Y#Prior.P#Last” #Last” & _ “+ A#NetInco A#NetIncome.Y#P me.Y#Prior.P#La rior.P#Last.W#YT st.W#YTD” D” End If 16. Yes - The system knows what comes prior to period 1 If HS.Period.IsFirst = True Then HS.Exp "A#Account1 = A#Account2.P#Prior" & _ "+ A#Account3.P#Prior.W#YTD" End If • HFM Scenarios are not linked like the “Category” in Enterprise • … but the system does “know” the sequence of the year dimension • Note: You can get in trouble if you run this rule on the first year in the system! 2.
Tip 7: What will be the result? HS.Exp "A#Account1 = A#Account2” & _ “ * (A#Account3 / A#Account4 )" 18. Nothing – but be careful • The HS.Exp function itself seems to take division by zero into consideration and will just yield nothing. • It did not write a zero if there was data in the destination cell… it did not write anything • If you use a GetCell or regular VB code… SomeVariable = HS.GetCell "A#Account2” & _ “ * (Variable1/AVariableWithValueZero AVariableWithValueZero)“ • This will fail with a division by 0 error 19. Tip 8: The [None] entity • The [None] entity does not have a currency • Rules will assume you want to read data from the same value dimension member you are in • [None] is the only valid value If HS.Entity.Member = "Child2" Then HS .Exp "A#Account2 = E#[None].V#[None].A#Account4“ E#[None].V#[None]. End If 20. Tip 9: Don‟t fill the database with 0‟s • Be careful when writing to the database that you are not pushing 0‟s into the database • A zero is data – which is not the same as nothing. What do you think will happen when you run a “Consolidate all with Data”? • This has a negati ve effect on performance • This can very quickly bloat the database size 21. HS.Exp – Pushing Zeros HS.Exp "A#Account3.C1#Chips = A#Account4.C1#Chips * 1.1" HS.Exp “A#Account3.C1#Computers = A#Account4 “ & _ “.C1#Computers * 1.1” Before After 22. HS.Exp - Pushing Zeros part 2 SomeVariable = HS.GetCell("A#Account4.C1#Computers") * 1.1 HS.Exp "A#Account3.C1#Computers = " & SomeVariable Before After 23. HS.Exp – Pushing Zeros Part 3 SomeVariable = HS.GetCell("A#Account4.C1#Computers") * 1.1 If SomeVariable 0 Then HS.Exp "A#Account3.C1#Computers = " & SomeVariable End If 24. HS.Exp – Pushing Zeros Part 4 You can use the GetCellNoData function. This function is like the GetCell function but as an added bonus it populates a Boolean variable to let you know if function is returning data SomeVariable = HS.GetCellNoData(“A#Account4.C1#Chips”,IsEm pty IsEmpty) * 1.1 If IsEmpty = False Then HS.Exp "A#Account3.C1#Chips = " & SomeVariable End If 25. HFM Rules Advanced Topics and Debugging 26. The thrills and excitement of working in the Value dimension ! AKA: If you‟re not afraid….. you will be 27. The Value Dimension is the key • The Value dimension is the key to Rules • The Value dimension is the key to HFM • It enables: – Currency Translation – Intercompany Transactions – Percentage Consolidation – Journal Entries at multiple levels 28. A simple representation of the elements in the value dimension [Contribution Total] [Contribution] [Contribution Adjs] [Proportion] [Elimination] [Parent Total] [Parent] [Parent Adjs] 29. Tip 1: The calculate sub procedure may be run several times per entity. • Unless restricted, [Contribution Total] Sub Calculate can run [Contribution] [Contribution Adjs] up to eight times per [Proportion] [Elimination] [Parent Total] entity [Parent] [Parent Adjs] • May ac cidentally end up with double or triple the desired value • Even if it‟s correct, it simply takes unnecessary time 30. Specify the Value Dimension If HS.Value.Member = "" Then Some code statements… Else Some code statements… End If 31. Tip 2: Reading Across the Value Dimension 3 1 2 • Rules are not run and you can‟t write to • ( 1) and (2) are entirely independent of each other • Avoid reading from outside the data unit • Definitely avoid reading Calculated values from outside the data unit. 32. HFM Rules 201: Default Sub routines Most Common Less Common Infrequent • Calculate • Allocate • ICT • Translate • Input • EPU • Consolidate • NoInput • Dynamic 33. Tip 1: Debugging The Editor will help you…. • Save time • Format code • Syntax check code • Use VB functions – The editor knows what parameters are required etc. • Has color coding 34. Tip:2 Put the POV into variables • At the beginning of c ode place the Point of View into variables. • Pass this into custom subroutines 17.
Tip 3: Comparisons are case sensitive. 'If you write this statement: pov_scenario = HS.Scenario.Member 'And get this data out of the system: pov_scenario is equal to "ACTUAL" 'This comparison is not true If pov_scenario = "actual" then „However this is true If LCase(pov_scenario) = "actual" then 'The LCase function is the Lower Case function (Yes there is a UCase function for Upper Case) 36. What does this code do? If HS.Value.Member = "" And HS.Scenario.Member = "ACTUAL" _ And HS.Year.Member >= "2002" Then variable1 = HS.Entity.List("","CC_Alloc_Ent") Dim i For i = LBound(variable1) To UBound(variable1) If HS.Entity.Member = variable1(i) Then Variable2 = HS.Getcell("A#account123.I#[ICPNone].C1#MfgFixGen.C2#[None].C3#[None].C4#[None ]")+HS.Getcell("A#account123.I#[ICPNone].C1#MfgVarGen.C2#[None].C3#[None].C4#[N one]")+HS.Getcell("A#account123.I#[ICPNone].C1#ShippgWHGen.C2#[None].C3#[None ].C4#[None]")+HS.Getcell("A#account123.I#[ICPNone].C1#SellingGen.C2#[None].C3#[N one].C4#[None]")+HS.Getcell("A#account123.I#[ICPNone].C1#EnginGen.C2#[None].C3# [None].C4#[None]")+HS.Getcell("A#account123.I#[ICPNone].C1#AdminGen.C2#[None]. C3#[None].C4#[None]") If Variable2 > 0 Then Call Subprocedure1 Exit For End If End If Next End If 37. Tip 4: Formatting Counts 38. Formatting 1: Document Code • Use comments to say what the code is doing – Add any concerns you may have about the code and possible ways for it to break or need for maintenance – Add your initials and dates to everything you change • If you don‟t document code, it is very difficult for anyone to help you • Undocumented code is difficult to maintain (modify later) • Your future audience may be you! 39. Formatting 2: Use meaningful variable names. • Don‟t make your variables a secret code • If the variable is holding average daily sales call it something like: – AvgDaySales – average_daily_sales • Be careful if you mix case 40. Formatting 3: Use indenting • Indent code in loops For month = 1 to 12 Line of code Line of code Line of code Next „Month • Indent code in conditional statements If m onth = 6 then Line of code Else Line of code End If „month • Comment the end of each loop or condition • 900 lines later, you‟ll clearly understand which conditions were in place 41. Formatting 4: Line Continuations A formula may be complex but at least try to be reasonable as to where the line breaks occur. 42. Resources • HFM Rules course from Oracle Education • VBA for Dummies – Nice overview of programming and VBA. • VBScript in a Nutshell – by Childs, Lomax, & Petrusha, published by O‟Reilly, is a really handy syntax reference when coding. • Microsoft – 6.0 Programmer‟s Guide • HFM_Admin.pdf & HFM_User.pdf – Functions guide • Oracle Technology Network forum – http://forums.oracle.com/forums/forum.jspa?forumID=407&start=0 43. Tip 4: Type less • Variables can hold strings which represent blocks of code Nones =".I#[I CP None].C1#[None].C2#[None].C3#[None].C4#[None]" • This works HS.Exp "A#AvgWorkCap" & Nones & "=" & (sum_wc / 13) 44. Tip 5: Impact Status • HS.ImpactStatus(“target POV”) • Function that simply changes the calc status of the target from anything to “CN” – Only need to use on base entities – Anytime Sub Calculate runs, you know that data has been updated – Same or future Period, can be a different scenario, year, entity, etc. • Always used for Roll -forwards 45. Impact Status for Synchronizing Actual Data with Forecast • Used to notify the Forecast that Actual has been updated – First, when you‟re in the Actual scenario, change the calc status in the Forecast Scenario – Second, when you‟re in the Forecast scenario, set all accounts equal to their respective values from Actual • Also used for currency restatement scenarios • Performance -wise, this is “expensive” so use wisely and sparingly 46. Tip 8: Break the Rule file into multiple sub-procedures Advantages: • Each sub procedure will deal with one “set” or rules. – Cash Flow – Allocations – Statistics • You can turn types of rules on and off • Cuts down on repetitive code • Helps with debugging • Overall code is more readable • Calc Manager is designed for this approach 47. Calling all Sub Routines 35.
Tip 9: Debugging Code • The real mystery is: what are the values of variables while the system is running? • What is the POV when the rule is running? • Did I meet an If..Then condition? • Does my variable contain what I think it should? • You can‟t use a VB message box function • Write information to a text file that you can look at after the rules have run. 49. Writing to a text file • Not natively part of HFM, but used so often most people think it is • Added functionality directly into Calc Manager 50. Using the WriteToFile Routine • Call WriteToFile(“Text to write out”) • Call WriteToFile(“VariableName = ” & variable content) 51. Output of the File • File output is from the HFM app server‟s perspective and owned by the DCOM user – Create a file share for this • This is a snapshot of the text output • I was just trying to see what data was in each of the value dimensions at a particular time • The Time / Date Stamp is coded into the output, and is automatic 52. Intro to Calc Manager The future of EPM rules development 53. Overview • Web-based, object-oriented module that creates: – HFM rules – Planning Business Rules • GUI creates flow chart -like representation of rules • Relationship to EPMA – 11.1.1.2 must use EPMA to use Calc Manager and vice- versa – 11.1.1.3 allows for Calc Manager to be used with Classic applications and Classic rules with EPMA 54. Overview How is this different from today‟s rules? • In the end the logic is still the same for HFM – Calc Mgr creates and stores the visual representation – During deployment an .rle file is created from the objects and loaded to HFM – Deployment is equivalent to today‟s step of loading rules – VBScript also be generated on demand to validate what will be created during deployment 55. Object Hierarchy • RuleSets – Rules * • Components * Rules can also contain other nested Rules 56. Rule Sets • RuleSets – Are equivalent to major subroutines (e.g. Calculate, Consolidate, Translate, NoInput, etc.) – Only one RuleSet per Calculation Type can be deployed at once but multiple versions can be created and stored – RuleSets perform “Calls” for all of the individual rules 57. Rules • Rules – Are equivalent to custom subroutines that are called from main subroutines – Where all of the actual code is actually housed 58. Elements – Components (Demo) • Formula – Equivalent to any statement/formula such as HS.Exp or setting a variable equal to something – Also contains conditional processing for individual statements • Script – Allows VBScript to be written for part of a rule rather than using the GUI interface • Condition – Used to wrap a conditional statement around other components (e.g. “If pov_entity = x then….”) • Member Range – A list of items that can be looped through, such as a member list • Data Range – Equivalent to Open Data Unit loops • Fixed Loop – A numbered series that can be looped through (e.g. “For i = 1 to 10”) 59. Formula Details (Demo) • Almost all of the typically used functions are available, whether HFM specific, or general VBScript ones • Changes in Syntax – “@” symbol used at the beginnin g of formulas – HS.Exp is implicit if no variables are used but just POVs are referenced – No need to use ampersands for concatenation – No need to use double quotes unless space is part of member name – Variables require “{}” brackets 60. Features (Demo) • On -demand conversion to VBScript – Done at the Rule or RuleSet level – allows you to see the code that will be generated upon deployment – Can not be modified and converted back to Component objects but assists in troubleshooting • Commentary available in numerous places • Logging (aka “Write to File”) • Timer • Disable – equivalent to “commenting out” a line • Member, function and variable selection throughout 61. Replacement Variables • Typically used for constants like static strings • Need to be “declared” through the Variable dialogue box before use 62. Execution Variables • Typically used for situations in which variable is populated or reset as part of a rule (e.g. Open Data Unit members) • Need to be “declared” through the Variable dialogue box before use • Scope can be at RuleSet or Rule level 63. Execution Variables: Boolean • True or False • Prefix with “b” 64. Execution Variables: Numeric • Numeric value, usually data or a counter • Prefix with “n” 65. Type Explicit Exp Statements 48.
Execution Variables: String • Strings, usually the label of a metadata member, or a user defined field contents • Populated by functions • Prefix with “s” 67. Other Features • Sharing • Expand/Collapse • Zoom Levels • Printing 68. Rule Development / Conversion Approaches • Create from scratch using new graphical objects • Place the rules into script objects • Use a conversion utility to migrate from VB Script to Calculation Manager objects 69. Benefits What are the benefits of using Calculation Manager? • Easier to maintain for administrators • Doesn‟t require quite as much coding knowledge (but still requires app knowledge) • More transparent way to explain calculations to auditors or for documentation purposes • Shared objects can be used in multiple situations and multiple applications • Templates allow for the faster creation of the most commonly used rules and the benefit of leveraging best practices 70. Questions? 71. Chris Barbieri
[email protected] Needham, MA USA +1.617.480.6173 www.ranzal.com 66.
