One of the most important things you can do to make you rules readable and helpful is to make sure they are properly formatted. There are some simple rules you should always, without exception follow. The rules of good formatting are;
1. Proper Case – Function names are not case-sensitive, for example, api.data.calculate and Api.Data.Calculate, or API.DATA.CALCULATE, are treated as the same. Still, it is a best practice of VB style to be consistent and to capitalize judiciously. Proper case throughout the rules file is much easier to read.
2. Always Comment – Add comments to any line of code explaining what you are doing and why. Use the apostrophe at the beginning of the comment to make sure it is not interpreted as part of the rules. If this is done in a VB editor, it should turn green by default.
3. Indentation is critical – This is especially true when using any nested statements or conditionals. Those are explained below. Indentation should be done for any scripting, even scripting objects in Business Rules Editor.
4. Variable and Constants properly named – All variables should be named useful names.
Formatting the rules also means using the underscore ‘_’ and colon ‘:’ symbols. When using the underscore you are telling the script the line is continuing on the next line. For example;
api.data.Calculate("F#[Bad Debt]:A#[EBITDAVar] = & _
The colon allows you to combine two lines. For example;
strSalesAccount = “A#7999.UD1#Sales” : strMktAccount = “A#7999.UD1#Marketing”
I think it is important here to underscore the importance of comments. You will not remember in a year or two why something is quite the way it is, comments will help you from making the same mistake again. It can help provide a new administrator detailed information, such as what needs updating or regular maintenance, if you add a new cash flow account for example. Finally it can help remind you what needs to be considered for an upgrade, or rebuild.
Variables & Constants
Variables and constants are used to hold values or expressions. Think back to your 9th grade algebra class. 2+y = x, y is the variable. See you teacher was right, this may prove useful yet. Variables can have any name. So while ‘y’ or ‘x’ is a valid name, they tell you nothing. Names should be something that makes sense. Consider which of the following is easier to follow. 2 + y = x or 2 + strVariablePercent = strPercentMarkUp. I would say you can understand more form the second line of rules than the first, even without knowing the context. Add a line of comments, and note the proper case, and you are on your way to well formatted descriptive rules.
A Variable is a value that changes depending on parameters and when it is used.
A Constant will not change, regardless of when it is used or changes in the application. You will need declare constants at the beginning of rules files. This is because since they don’t change you declare them right away. They are available to all procedures at all times. But other that these differences they are to be used just like variables.
You should have some guidelines when writing rules, and one of the simplest things to do to keep yourself organized is to have a naming convention. I like to use a prefix. The prefix is something that helps me remember what is in the variable. I might use ‘str’ or ‘s’ for a string, or ‘bln’ or ‘b’ for a Boolean (true or false), and ‘nbr’ or ‘n’ for number. Then using proper case I use a descriptive label for my variable. So, for a number from Net Income, my variable might be called ‘nbrNetIncome’. I can see that variable name anywhere in file and know what the variable is for and what is it. Compare that with ‘x’. If I saw x, who knows what it is for.
What helps is know what you are going to use the variable for as well. We have two names for variables; Replacement Variables and Execution Variables. Replacement Variables are typically used for constants like static strings (for example topUD1=“.UD1#TopUserDefined1”). This variable might change, but it is replacing some part of a string. Execution Variables are typically used for situations in which variable is populated or reset during some condition or rule (for example sPOVEntity = api.POV.Entity.Name). The point of view changes constantly and what would be written in the variable would be updated accordingly.
There are some other rules for variable names you must follow. They must always begin with a letter. They cannot contain a period. You should avoid keywords such as “OneStream”, “Entity”, “Account”, when naming variables. These names are reserved and could cause problems.
VB.Net requires you declare variables before using it. Since the variables will require what the type needs to be, you need to make sure you avoid letting the variable use a type that Rules Engine is not expecting for that member. For example if you use a rule that check is the year is 2010, then OneStream could see that as something different than “2010”. By using the quotes and declaring it As String, the number 2010, becomes a string “2010”. Otherwise when OneStream runs into this problem you will get a Type Mismatch error. So if you do get this error, double check that the variable you are testing is correct.