«Preparing a Tax Return Using Executable Decisions (Decision1040EZ) Tutorial OpenRules, Inc. December-2011 OpenRules, Inc. - ...»
Open Source Business
Decision Management System
Preparing a Tax Return
Using Executable Decisions
OpenRules, Inc. - Decision1040EZ - Decision Modeling Tutorial
Table of Content
Starting with Decision
Defining Decision Tables
Validation Rules – Simple Decision Tables
Using Formulas inside Decision Tables
When Conditions and Conclusions Share Decision Variables
More Complex Decision Tables
Defining a Business Glossary
Defining Test Data in Excel
Appendix. Form 1040EZ
OpenRules, Inc. - Decision1040EZ - Decision Modeling Tutorial
INTRODUCTIONIn this tutorial we explain how to implement a rules-based application that calculates tax returns using the notorious US tax form 1040EZ. This tutorial is written in the form of a
dialog between two people:
User – a person who wants to learn how to write OpenRules®-based applications OR – a representative of OpenRules® technical support who explains how to do it.
A user is not expected to be a software developer but rather a business analyst who is familiar with Excel and who has already looked at the OpenRules document “Getting Started” that includes several basic examples.
This tutorial explains how to use OpenRules® Decisioning approach to implement tax calculation logic for the form 1040EZ. It does not include any GUI and can be incorporated in any application as a pure decision service.
There is also another tutorial that explains how to use OpenRules® Dialog (ORD) to create a web-based dialog during which only necessary questions are being asked, all other answers are automatically calculated, and a ready to go tax return in the PDF format is being produced – see http://openrules.com/pdf/Tutorial.Dialog1040EZ.pdf.
BUSINESS CASEOR. We will prepare the notorious US tax form 1040EZ used by many US taxpayers to report on their revenue and expenses and calculate whether the taxpayer owes additional money or can expect a refund.
User. I did not use it myself but I know how frustrated some of my colleagues were when they tried to fill out this form themselves.
OR. There are plenty of web-based applications that help people to do it. While the form 1040EZ is supposed to be used only in simple cases, the business logic behind this form is not so simple, especially when a taxpayer was shown as a dependent by his/her parents or somebody else. The actual form has only 2 pages and in many cases only the first page is needed. The second page has to be filled only when a taxpayer is shown as a dependent.
We also have to keep in mind the eligibility criteria that specify when to use this form.
User. Where can we get the form?
OR. Look at the Appendix below. We downloaded this form from the IRS website and used this form to demonstrate how to use OpenRules®. For your convenience, the form 1040EZ is presented on the next two pages. We use the tax form for 2003 as the example for our
application – see the Appendix below. You may download the latest 1040EZ form from http://www.irs.gov/pub/irs-pdf/f1040ez.pdf. The instructions can be found at http://www.irs.gov/pub/irs-pdf/i1040ez.pdf. As you can see, the form is self-explanatory and people should be able to fill it out without external help.
User. I noticed that the official 1040EZ instructions have more than 35 pages; probably it is not so easy to cover all possible situations. However, our real OpenRules ®-based application is also not going to be easy, so I’d appreciate it if you would explain how to handle not just simple cases but also much more complex business scenarios.
OR. OK, we plan to build a simple decision service Decision1040EZ that implements only the business logic of the form 1040EZ.
DECISION “DECISION1040EZ” OR. This section will describe a methodological approach and consider different implementation options for the above tax form 1040EZ. A ready to go application is a part of the OpenRules® installation – you can find it in the sample project “Decision1040EZ”.
STARTING WITH DECISIONOR. We will apply a top-down development approach. It means that we will start with the definition of a Decision and not with rules or data. Let’s call our decision “DetermineTaxReturn”.
User. Sounds good to me.
OR. Let’s look at the first page of the Form 1040EZ. Can you list all decisions that we should make?
User. I guess they are defined in the lines of the form. After filling out general information
about a taxpayer we should do the following calculations:
Calculate Adjusted Gross Income (Line 4 by adding the content of Lines 1, 2, and 3) Calculate Dependent Amount (Line 5 with potentially complex logic described on the second page) Calculate Taxable Income (Line 6) Calculate Total Payments (Line 9) Define Tax (Line 10 using the standard Tax Table) Calculate Refund or Amount You Owe OR. Good. So, let’s create an Excel file “Decision.xls” with the following table of the type “Decision”:
The first column of this table defines the exact names for all of the above decisions. We will need to create decision tables for each of these decisions but at this point it is enough to just give these decision tables exact (unique) names – see the second column.
User. Can you remind me why each decision table name starts with := and ends with ()?
OR. This is necessary to inform OpenRules® that decision tables are actually executable Java functions contrary to the decision names in the first column.
User. Now we can start creating Excel tables for the Excel-based decision tables.
OR. Not so fast. If you look at the second page of the 1040EZ from you will notice some limitations when this form can and cannot be used. It means that before we start any calculations we should validate if the taxpayer is eligible to use this form. I’d recommend defining two different decisions, one that validates a taxpayer eligibility to use this form and another that actually does the necessary 1040EZ calculations.
User. OK, we can add another decision in a separate decision table:
But how can we connect these two decisions? We should execute the first decision only when the second one is successful.
OR. We may define a top-level decision with the following logic:
1. Execute a sub-decision that validates a taxpayer’s 1040EZ eligibility
2. If a taxpayer is 1040EZ eligible Then execute sub-decision that calculates the tax return.
Let’s call this top-level decision “Apply1040EZ”.
User. OK, but I did now know that decisions can have sub-decisions.
OR. Actually, you can use multiple tables of the type “Decision” to represent any decision trees just in a tabular format (that frequently is more manageable than a graphical tree).
You even can use conditions inside decision tables. Let me show you a possible solution:
Because we use an optional “Condition” we have to add a second row. The keywords “Condition”, “ActionPrint”, and “ActionExecute” are defined in the standard OpenRules template “DecisionTemplate” – see the configuration file “DecisionTemplates.xls” in the folder “openrules.config”. Here I am using a decision variable “1040EZ Eligible” that we will add to our glossary later on (probably as an attribute to a business concept “TaxReturn”). I assume that decision “ValidateTaxReturn” should set this decision variable to TRUE or FALSE.
User. Interesting… And if our validation fails (1040EZ Eligible will be FALSE) you just want to print the words “Do Not Validate” but do nothing.
OR. Exactly right. Note that the decision “ValidateTaxReturn” will always be executed (no conditions are defined). Also note that contrary to the decision tables, decisions always use a predefined parameter (decision) as defined in the template.
Now, when we are done with the definition of our decision and sub-decisions, we may concentrate on the decision tables.
DEFINING DECISION TABLESOR. The form 1040EZ gives us an opportunity to demonstrate different types of rules starting from very simple validation decision tables, then rules that deal with different calculation formulas, and finally with quite complex rules for calculation of dependent amounts. Let’s start with validation rules for the names we already specified in the decision “ValidateTaxReturn”.
Validation Rules – Simple Decision Tables User. OK.
Eligibility rules are defined at the beginning of the second page of Form 1040EZ:
I think we can automatically validate only two eligibility conditions:
1. Your taxable income (line 6) is less than $50,000
2. You taxable interest was not over $1,500
So, I can create the proper decision table “ValidateEligibility” as follows:
OR. Looks good but I can see two problems here. First of all, what will happen if both eligibility conditions are met? In other words, who will set the decision variable “1040EZ Eligible” to TRUE?
User. It is easy to fix. I will add one more row at the end of the table that will set this decision variable to TRUE and will even produce a message that 1040EZ can be used. Here it goes.
OR. The OpenRules® engine will actually execute this decision table in the way you expect.
However, theoretically this decision table violates a requirement that the order of rules (rows) inside a decision table should not matter. In this case it is easy to fix the reliance on the rule ordering by simply avoiding empty conditions as shown below.
OpenRules, Inc. - Decision1040EZ - Decision Modeling Tutorial User. I still like my initial version better because it is simpler. With your approach we have to mention thresholds like “50000” and “1500” in several places. What if we want to change such thresholds? What if we have not 2 but 4 or 5 condition columns? It would be much more difficult to maintain such a decision table.
OR. Your arguments are well taken. In reality it is really up to a rule designer (or to the company’s official policy) to decide how strictly to follow the methodological principles.
Let’s keep going. As mentioned earlier, I noticed not one but two problems with your decision table. Are your decision variables “Taxable Income” and “Taxable Interest” already defined by the time when you try to validate them?
User. Oh no. They are parts of the calculation logic. Let me look again at the first page of 1040EZ… OK, Taxable Interest is defined in Line 2 and simply should be entered by a taxpayer. However, the Taxable Income is defined in Line 6 and it should be calculated. I
am afraid we have to repeat the first 3 calculation steps before starting validation:
But why should we repeat these steps inside both decisions? Maybe it is better to add one more decision, say “Pre-Process”, that should be executed before “ValidateTaxReturn”.
OR. You certainly can do that, and in some cases it will be the right approach. However, I’d rather treat our two decisions “Validate” and “Calculate” as loosely coupled services and would rather minimize unnecessary dependencies. Besides, we will reuse the same calculation decision tables anyway. So, let’s stick to what you’ve already done.
Using Formulas inside Decision Tables
User. OK. Now we have to put the actual calculation logic inside decision tables that we already have specified within our table “ValidateTaxReturn”. The first decision table is “CalculateAdjustedGrossIncome”. We will need to calculate the decision variable “Adjusted Gross Income” that is specified in Line 4 as a sum of Line 1 (Wages), Line 2 (Taxable Interest), and Line 3 (Unemployment Compensation). I can use a decision table with only one conclusion for the decision variable “Adjusted Gross Income”. But how can I define a sum of different type variables?
OR. You can get access to all type variables using predefined get-methods. For example,
assuming that the mentioned decision variables have real values, you may access them as:
OpenRules® allows you to put any formulas inside decision table cells starting with “::=”.
Also do not forget to always put your formula in parenthesis. Let me help you for the first
User. I got it. But even if we do not use these decision variables as decision table columns, we probably still have to put them in our glossary later on.
OR. Yes, that is a good point. Before we jump to more complex calculation rules, let’s do very similar decision table “CalculateTotalPayment”.
User. It defines “Total Payments” as the sum of “Tax Withheld” and “Earned Income Credit”. Here it goes.
OR. I am glad you did not forget parenthesis. While it would not matter in this case it is a good practice to always put your formulas in parenthesis.
Now, let’s leave the most complex rule “CalculateDependentAmout” for desert, and next work on the decision table to “CalculateTaxableIncome”.
When Conditions and Conclusions Share Decision Variables OR. Decision table “CalculateTaxableIncome” does not simply uses a formula, but has an interesting flavor, if the formula for Taxable Income produces a negative result we need to set Taxable Income to 0. How would you approach this problem?