Adventures in Groovy – Part32: Require Explanations WhenData Is Outside AcceptableRangesGroovy offers creative ways to force data into acceptableranges. But, what happens when there is an acceptable reasonfor abnormal trends, or drivers? With Groovy, you can notonly add limits to data cells, but you can also allow entryoutside of those ranges if the user enters an explanation. With Groovy, you get the best of both worlds!

Use CaseRequiring data within limits is a huge improvement to yourapplication. It improves the accuracy and ownership of thebudget, and reduces fire-drills at the end of your budgetcycle. In this example, we will require a rate to be between-10 and 30 percent. If a user enters data outside that range,the form will not be able to be saved.

However, if a user enters a comment, Groovy will then allowthe form to be saved. Is this perfect? Of course not. Auser can still go in and enter a poor explanation, or justenter a space to bypass the validation rule. I have alwaysfelt that no system can make people be responsible, so we willassume that your users are doing what they are instructed and

your leadership will hold them accountable. To show thisfunctionality, view this short video.

The CodeThis validation is actually quite simple. This follows thesame rules as other validations and must be “Run BeforeSave.” Use Members on Form and Hide Prompts is alsosuggested.

[crayon-6233035382ee9344115827/]

Finishing UpI really hope this inspires you to be creative about usingGroovy to add useful user functionality. As you can see, youcan add awesome functionality relatively easily. If you haveany creative solutions you would like to share, please add acomment.

Adventures in Groovy – Part15: Returning Errors (RTPEdition)

IntroductionOne of the huge benefits that available in Groovy Calculationsis the ability to interact with a user, validate data, and acton the validation. Now, we can interrupt form saves, stop RunTime Prompts from continuing, and communicate information backto the user.

This may sound repetitive if you have read part 13 and part14, and you can skip to the code example to learn more aboutrun time prompt validation. If not, you must have anunderstanding of the validation functions and the componentsof the messageBundle. There are a number of functions forvalidation, and they can be categorized functionally. Althoughthey all can be use somewhat interchangeably, the logical usesare

Data Form validation functionsaddValidationError

RTP validation functionsvalidateRtp

Validation functions that are more open ended and can beused just about anywhere

messageBundlemessageBundleLoaderthrowVetoException

In this post, we will discuss one aspect of this, and probablythe simplest application, validating Run Time Prompts (RTP).

The MessageBundleBefore a few of the methods can be used, one must firstunderstand the MessageBundle and MessageBundleLoader methods. To look at documentation, they might seem very complex, and amaybe a little intimidating. The reality is that these arejust objects that hold the error messages. That is prettymuch the long of short of it. The messageBundle holds a map

(basically a lookup table that is two columns and n rows) ofthe error ID and the description of the error you want todisplay. If the application is consumed by users withmultiple languages, a messageBundle can be created for eachlanguage. The messageBundleLoader allows you to identifywhich bundle to use based on the user’s local. The examplebelow should answer any questions you have.

The Message BundleThink of this method as an array, or a table in Excel. It has2 columns (ID and message). It can have an infinite amount ofrows. The syntax of this is “[id,message]”. For multipleerrors, this is duplicated, separated by a comma, like“[id,message],[id,message]”. Here is an example of amessageBundle with one error.[crayon-62330353836a3154676144/]And with two errors.[crayon-62330353836a9487552764/]And with two errors in Spanish.[crayon-62330353836ab394200476/]This can be extended to hold all the error messages requiredfor the scope of the calculation.

The Message Bundle LoaderThe messageBundleLoader is the piece that pulls either asingle, or multiple, messageBundles together to use in acall. If only one language is required, it would look likethis.[crayon-62330353836ac710339641/]

For multiple languages, it would include multiplemessageBundles

[crayon-62330353836ae491554057/]

Validate The InputWhen a validation error exists, the prompt window will notclose, so it won’t let a user continue unless all the dataentered validates. Validations are only limited to yourknowledge of how to validate the input. Let Google be yourfriend. You will be hard pressed to have a sitiation whereyou can’t find an example of what you are trying to do. Ifyou aren’t familiar with “regex,” it will likely be includedin just about any Google search you do. The examples belowall use a regex string to validate the inputs.

To use a run time prompt in Groovy, they must be initiated. This looks like a comment, but it acts differently whenprefaced by RTPS:[crayon-62330353836af440778890/]Next, we will create a messageBundle. Although it is simplierthan above, it is more than enough to demonstrate its use inthe validateRtp method. This creates an error for each of thethree validations in English.[crayon-62330353836b0067054873/]Now, the actionable stuff. The next 3 lines will validate the3 run time prompts. If any of them fail, the RTP window willremain open and the user can’t continue until they fix theerrors or cancel the action.[crayon-62330353836b2925158271/]Putting it all together, we have the following.[crayon-62330353836b4411521638/]

Wrap UpIt has been a long time since developers have had this kind ofcontrol. The possibilities are only limited by yourimagination and business requirements, but there isn’t anyvalidation that can’t be done. This wraps up the 3 validationmethods.

Enjoy this new functionality. Don’t underestimate itsimportance. This functionality can save your customers hoursof work and lots of frustration. Helping them input accuratedata improves the forecasting and budgeting process. Implement these techniques and they will love you!

Adventures in Groovy – Part13: Returning Errors (DataForms)

IntroductionOne of the huge benefits that available in Groovy Calculationsis the ability to interact with a user, validate data, and acton the validation. Now, we can interrupt form saves, stop RunTime Prompts from continuing, and communicate information backto the user. There are a number of functions for validation,and they can be categorized functionally. Although they allcan be use somewhat interchangeably, the logical uses are

Data Form validation functionsaddValidationError

RTP validation functionsvalidateRtp

Validation functions that are more open ended and can beused just about anywhere

messageBundle

messageBundleLoaderthrowVetoException

In this post, we will discuss one aspect of this, and probablythe simplest application, validating Run Time Prompts (RTP).

The MessageBundleBefore a few of the methods can be used, one must firstunderstand the MessageBundle and MessageBundleLoader methods. To look at documentation, they might seem very complex, and amaybe a little intimidating. The reality is that these arejust objects that hold the error messages. That is prettymuch the long of short of it. The messageBundle holds a map(basically a lookup table that is two columns and n rows) ofthe error ID and the description of the error you want todisplay. If the application is consumed by users withmultiple languages, a messageBundle can be created for eachlanguage. The messageBundleLoader allows you to identifywhich bundle to use based on the user’s local. The examplebelow should answer any questions you have.

The Message BundleThink of this method as an array, or a table in Excel. It has2 columns (ID and message). It can have an infinite amount ofrows. The syntax of this is “[id:message]”. For multipleerrors, the id:message is duplicated, separated by a comma,like “[id,message,id:message]”. Here is an example of amessageBundle with one error.[crayon-623303538399e844897627/]And with two errors.[crayon-62330353839a3773908419/]And with two errors in Spanish.[crayon-62330353839a5443613800/]This can be extended to hold all the error messages requiredfor the scope of the calculation in all the locales required.

The Message Bundle LoaderThe messageBundleLoader is the piece that pulls either asingle, or multiple, messageBundles together to use in acall. If only one language is required, it would look likethis.[crayon-62330353839a6888449643/]For multiple languages, or multiple messageBundles, they wouldbe concatenated together with commas. View a valid list oflocales to make sure the parameter in parenthesis is correctlylinked to the correct locale.[crayon-62330353839a8765735608/]

Throw an Exception (Interrupt Form Save)Here is where the cool stuff happens. see post about loopingthrough cells

If a validation error exists, an exception can be generated tostop the form from saving. To do this, simply use thethrowVetoException method. This accepts 2 parameters. Thefirst is the messageBundlerLoader, and the second is the idassociated to the to be displayed. Using the example above,and assuming the local is US, the following would stop theform from saving and display a message of “Only alphanumericcharacters can be entered (a-z, 1-9).”[crayon-62330353839a9601268016/]

Consolidated ExampleThe following example creates two error messages in twolanguages. On form save, this will loop through all the cellsand throw an error if any value is negative.[crayon-62330353839aa242470803/]

Wrap UpIt has been a long time since developers have had this kind of

control. The possibilities are only limited by yourimagination and business requirements, but there isn’t anyvalidation that can’t be done. Future posts will tacklevalidating Run Time Prompts, and taking form validation onestep further by adding cell level tool-tips and color coding.

The last thing with these validation calculations is theimportance of when they are executed. The documentation Ihave from Oracle states something slightly different, so Idon’t know if this is the way it is supposed to work, but inmy experience, where the rule runs is critical. Here is whatI am experiencing.

When the rule is set to Run Before Save, and there is avalidation error, the user can’t save the form and anerror messages is displayed in the correct locale. Tome, this is the experience that is expected.When the rule is set to Run After Save (which is the wayit is documented), and there is a validation error, theuser receives an error, but the data is saved.

The difference in the above does provide some interestingoptions. Let’s say that we have a form and users are requiredto allocate an expense. If the expense is not allocated at100%, the form can’t be saved. Assume that there is a rulethat the expense shouldn’t be allocated to more than 3 places,but users should be warned if it is. In this case, if therule is set to run AFTER save, the user gets the message, butthe data is saved.

Either way, if the rule is executed before other rules on theform, no subsequent form will fire if there is a validationerror.

Adventures in Groovy – Part10: Validating Form Data

IntroductionOne of the huge frustrations I have with Planning is the factthat you haven’t been able to stop a user from saving datathat didn’t validate since Smart View was released and DataForms could be opened in Excel. Prior to that, the formscould be customized with JavaScript and the form save could beinterrupted and cells flagged. Well, thanks to GroovyCalculations, it is back, and every bit as flexible.

ExampleThe following Data Form allows users to add new products andenter financial information. In this form, 3 rules exist.

The GP Level 2 % has to be between -10% and 30%.1.The Regular Cases CANNOT have one month that is more2.than 50% of the total cases.If Regular Cases is entered, a corresponding Average3.Price per Case is required.

When a user fills out the form and violates these rules, thecell background is changed and a tool tip is added. Ifviolations exists, the form does NOT save any changes to thedatabase. Before any changes can be committed, all errorshave to be corrected. In this example, all 3 validation rulesare violated and noted. If the user hovers the mouse over thecell with a violation, the tool tip is displayed with the rowand column members, and an error message explains to the userwhat the issue is with the data that is entered.

The CodeThe significance of this is huge, but the implementation israther simple. It is probably be one of the more basic thingscreated with a Groovy Calculation. Quite simply, to add avalidation error and stop the form from saving, all that hasto be done is to add a validation error to the cell.

cell.addValidationError(0xFF0000, “Customer ErrorMessage“,false)

This method accepts 3 parameters.

The first is the color you want the background to change1.to. This is the integer value of any color. Mostpeople are familiar with the RGB code, and this can beretrieved in almost any image editor (even WindowsPaint). There are many free options, like the freeoption at https://www.shodor.org/ to convert that to avalue that can be interpreted in Groovy.The second parameter is the error message to be2.displayed in the tool tip.The third is optional, and defaults to false. False3.that it will identify the cell as an error and stop theform from saving.

This will likely becused in a grid iterator, which is how thisexample was constructed to get the screenshot above. If thegrid iterator object is foreign to you, read Adventures inGroovy – Part 3: Acting On Edited Cells. The one functionthat is void from that article is the crossDimCell method. This acts like a cross dim (->) in a calculation. So, itreferences the POV of the cell and overrides the dimension ofthe member specified as a parameter. If multiple differencesexist, separate the names with a comma.[crayon-62330353840f6644077391/]

Form SettingsThe one gotcha is that this needs to run BEFORE SAVE. Itmakes sense, but I was expecting a similar result asvalidating a RTP when the Business Rule runs on save, so ittook me a good night sleep to recognize that error injudgement.

Why This Is SignificantYou may not thing this is a big deal because you can checkthis in a Business Rule after the data is saved and return anerror message requesting the user to change it. However, theusers are as busy, if not more busy, than you are. There arelast minute changes that get slammed in at the end of aforecast or budget cycle. There is no design doc to go backto and say it is going to take longer and we need a changeorder. The CFO won’t accept that as an answer, so things getforgotten or missed. This example forces valid data (notnecessarily accurate) to be entered, and all kinds of thingscan be checked to make sure human errors don’t turn into hugeissues for financial reporting. Think if you had a productand forgot to put a price. You could be missing millions, andthis type of proactive validation can prevent such things fromhappening. Little things like this reduce, or eliminate, firedrills later on in the budget cycle.

ConclusionThere is an infinite number of things that can beaccomplished. Simple things like the above, to extremelycomplex validation can be added. Think about ensuringallocated dollars are fully allocated(100%), forcing salariesto be in predefined pay bands for titles, and forcing theresults of driver based planning to be within a logicalmargin.

If you have some examples, please share with the community byposting a comment below.

Adventures in Groovy – Part2: Data Validation

IntroductionWe all know the Data Form validation rules are serviceable,but they are not robust. When Smart View advanced and formswere opened in Excel, the validation logic developers had inJavaScript became useless. Since then, we have really missedthe ability to communicate with the user interactively withvisual cues and validation rules that halted the saving ofdata. Well, Groovy calculations to the rescue!

I will preface with the fact that I am encountering some oddbehavior, so I am going to break this up into multiplearticles. It appears that Oracle is validating Groovyenhancements in Data Forms on the web, and not necessarilytesting the full functionality in Smart View. Currently, Ihave this working in a browser perfectly, but 3 of the 8

columns are failing in Smart View. I am hoping to get closureto a ticket on this in the near future. When I get aresolution, I will amend this article with some clarity oneither what I am doing wrong, or when it will be resolved.

High Level requirementAt a high level, the planners want to see any seeded valuethat was changed with a different background color to singleout the lines that have been edited.

The DetailsWe have a form that provides the users the ability to overrideseeded data. In this example, a planner can change theAverage Price/Case, Net Sales, and/or GP Level 2 at any levelof the hierarchy and gets allocated down to level 0 on a % toTotal. This form has the accounts in question for 3 sources. The override columns are a separate version that is set totop down so security doesn’t prevent them from entering at anon-level 0 member. This is only used to enter the 3 values,is used to calculate the Input source, and is cleared.

The Initialized source is seeded from prior year growth. This, in essence, is the basline seeded amount. Atinitialization, the Input source is a duplicate of Initialized

source.

The Initialized source is also on the form. When overridesare entered, it is applied to the input source. At this pointin the process, the Input is different from the Initializedsource, as shown by the orange color in the previous image.

Why Not Validation Rules?First, there is limited functionality in the Data Form

validation rules. In this case, the functionality is there,but has an issue with the precision of the data. Even thoughInput equals Initialized (or appears to), validation failsand shows a different background color. I have seen thisbefore with decimals with large precision.

How Groovy Solves ThisGroovy calculations have the ability to traverse through thecells of a Data Form. The 8 cells that can be impacted by the3 overrides can be checked against their counterpart insubsequent columns (comparing the same account in the Inputsource to the Initialized source). This is for anotherdiscussion, but Groovy can actually create temp grids and pulldata directly from Essbase that doesn’t exist in the grid,too.

To simplify this, the following only loops through the firstcolumn – Avg Price / Case. This can be replicated easily forall subsequent columns by changing the account in question.

This example uses several Groovy methods/functions. First,the data grid is stored in a variable, as it will bereferenced throughout. Next, we are using thedataCellIterator, which is the same in the previous post onGroovy. If you didn’t read that, or don’t understand theiterator, check that out.

At this point, the calculation is requesting to loop throughall the cells with Avg Price/Case AND Input in the POV. Inside the loop, lDestMembers is set to a list equal to allthe members in the POV for the relative cell. memberNamesreturns every member in the POV in a Groovy list.

The next step is getting the value for the corresponding cellin the Initialized source. getCellWithMembers accomplishesthis with the appropriate parameters passed. This functionaccepts member names, so all the members in the Input cell’s

POV are used, excluding the source dimension. This is changedto Initialize.

Lastly, the comparison is made between the two cells. If theyare not identical, setBgColor is executed on the Input sourcecell to identify it as something that has changed due to anoverride.

The Calculation[crayon-6233035384de3689335551/]

Data Form ChangesThis new Groovy Business Rule should be added to the form andexecuted on load and save. This will ensure that the accountsthat have been changed are identified both before, and after,the user makes any changes. One more note that might save youhours of frustration – make sure this rule runs last whenother rules are also executed!

ConclusionThis opens up a lot of options that far surpass the defaultform validations. Other options are available.

Tool-tips can also be assigned to a cell instructing theuser how to resolve a validation error, if one exists.The form save can be interrupted, stopping the user fromsaving data on a form (or even saving only parts of theform) when validation errors exist.Data can be altered to force validation prior to saving.Detailed messages can be displayed with instructions andother communication to the user.Have specific calculations executed based on the dataentered.

This is not an exhaustive list. We, as developers andarchitects, literally can do anything we want and have

complete control over what happens and what doesn’t happen. This is exciting because we have nearly complete control overwhat happens on save. If you have other ideas, or questions,please share them with comments.

FDMEE: Loading Data toDifferent Plan TypesI’m currently working with a Planning application that has 2data types with different dimensionality. This proved to causesome issues when I would try to import data via FDMEE. I wouldreceive a validation error during the import phase fordimension UD4 (Customer dimension) which was valid for PlanType 2 but not for Plan Type 1

For this specific case, I was trying to load data for PlanType 1, which has a different set of dimensions from Plan Type2. The customer & product dimensions are not valid for PlanType 1. Note the settings from the dimension library for bothdimensions.

Customer:

Product:

From the setup tab in FDMEE, click Target Application. We needto remove Customer & Product from the “Data Table Column Name”column:

Remove the values for Product & Customer and click save:

Then click refresh metadata:

After refreshing the metadata, go back to the Data LoadWorkbench and import the data file. The import & validatesteps should complete successfully now:

Data Validation Rules inPlanning 11.1.2.xGoodbye to the days of JavaScript in order to enforce datainput policies and rules to Planning web forms. With Planningversion 11.1.2 and newer, Oracle has introduced a powerful setof tools for data validation within the Planning Data FormDesigner itself. Let’s walk through a scenario of how thisworks.

Say that we have a product mix form that will be used to inputpercentages as drivers for a revenue allocation. Here’s whatthe form looks like:

We should expect that the sum of these percentages to be 100%at the “Electronics” parent member. If this is not the case,the revenue allocation will incorrectly allocate data acrossproducts. So how do we enforce this rule? Simple… let’s takea look at the data form design.

As a row definition we’ve included two member selections; 1)Descendants(Seg01) or Descendants(Electronics) and 2) Seg01 orElectronics. We are going to add a validation rule to row 2of the data form. To do this, highlight row 2 and click thesign to add a new validation rule. Notice that in thevalidation rules section, it now says ‘Validation Rules: Row2’.

The Data Validation Rule Builder will then be launched. Let’sfill in the rule. We should ensure the Location is set to‘Row 2’. We’ve filled in a name and quick description, thenensured that the ‘Enable validation rule’ check box ischecked.

For the rule we’ve defined some simple if logic:

IF [Current Cell Value] != [Value = 1] THEN [Process Cell] ;

To define what occurs if this condition is met we choose the

‘Process Cell’ action defined by the small gear with a letterA next to it. Here we will highlight the cell red and notifythe user with a validation message.

We click through to save the Process Cell definition and theValidation Rule itself and should now see the rule in the dataform definition.

So let’s take a look at how the end user will interact withthis form. Percentages are entered by product for eachmonth. Upon save, notice that all months for Electronics thatequal 100% appear normal. December only sums to 90% and ishighlighted in red as we specified in the data validation

rule. We cannot limit the user’s ability to save the formuntil the cell equals 100%; we can only notify them of theissue, and explain the cause and potential resolutions.

Of course, this is a simple example of what can be done usingPlanning’s Data Validation Rules. The possibilities areendless. Oracle has more scenario walkthroughs in thePlanning Administrator’s Guide. View them here:http://download.oracle.com/docs/cd/E17236_01/epm.1112/hp_admin/ch08.html