| The OpenRulesTM Tutorials Home |
|
Case Study |
Business and Technical Specialists Working Together On a Rule Project. Part 2 - Adding A Web Interface
In this document we provide a detailed description how to
create your own rules-based Web application using
OpenRules. The
first part
described the clinical guidelines and presented them as business rules.
Working together, a Business Specialist [B] and a
Technical
Specialist [T] have already defined the business terms and facts along with the
proper business rules. This part of the use case describes how [B] and [T] work together again trying to create a Web interface that models possible interaction sessions between
a doctor and a rules-based system.
[T] Hello again. Today is our second OpenRules session. Let me summarize what you and me did during our first common session. We basically implemented your Clinical Guidelines completing 3 major phases of the Business Rules Development:
I think we both did a good job, and now we have in our hand a working rule project. Later on we will expand these rules, and we will even try to make your rules to work with our real database and other production systems. But so far, there were two things that annoyed both of us:
We will try to get rid of these deficiencies and learn how to create a Web-based interaction process with multiple graphical forms and business rules.
[T] Today, we will create a normal GUI for our use case. So, a doctor would be able to get recommendations from our rule engine directly from Internet. Would you like to "talk" with our rule engine through a friendly web interface?
[B] It would be fantastic!
[T] Good. Hope you are familiar with such things as HTML, Java Script, Web Application Server or JavaServer Faces?
[B] Oh, boy! I know how to browse the Internet, but all these "techie" words... Is it really necessary?
[T] Just kidding. Don't worry: I myself am not an expert in all these web development techniques but of course I am familiar with the HTML basics. The good news is that folks from OpenRules along with business rules provide a library called "Forms" that does the magic. It really looks simple and does not require any programming expertise. Using OpenRules Forms, we can define our future web pages directly in Excel (like we did with your business rules). OpenRules introduced a special type of table called "Layout", so we can place different form elements like labels, input fields, and buttons directly into an Excel table. Hopefully, you will be able to define all Web forms yourself. Let's start together, and later on you would be able to beautify the forms yourself.
[B] You like to challenge me. OK, let's try, but please remember that my college degree was in medicine not in programming. So, here is our old Excel file HeathCare.xls. Where would I start?
[T] Forget about the technical stuff for a moment. Let's take a piece of paper and pencil or if your prefer MS Word, and think how our future GUI will look. First of all, there will be a dialog between a doctor and our rules-based system that assists doctor in recommending a medication and the proper dose to a particular patient. During a patient visit, the doctor should start with entering basic information about the visit, right? What do we already have in our Datatype "Visit"?
[B] Here what we defined last time in our business glossary in the file
HeathCare.xls:
[T] OK. So, to start an interaction with the system, a doctor has to enter at least the visit's date, identify a patient (probably by name), and set the encounter diagnosis like we did in our test data. Can you draw the proper form on paper?
[B] It is simple. I will use MS Word for my quick screen drawing:
[T] Good. I like your choice of simple colors. Let's assume we would be able to retrieve patient information from a database by using the patient's name as John Smith. So, the next form should display the related patient information, right?
[B] Yes. But it should also warn us if the patient John Smith is not found.
[T] You are right, but let's deal with this interaction logic later. For now,
would you
please draw another form that will allow a doctor to get and modify (if necessary) the
patient information. You may look at the test data we created last
time:
[B] No problem. Here is my sketch of the Patient form:
[T] It looks good. From this screen you should be able to update Weight, Creatinine Level, and medications. However, the fields "Name" and "Age" probably should not be changed because this information will come from the patient database. So, we should define these fields as labels not as input fields. You may just remove your white background for these fields.
[B] Done. Is there anything else?
[T] Yes, I think we should display the automatically calculated Creatinine Clearance right here. Do you agree? It should be presented as a label too. But Creatinine Clearance depends on the patient's age, weight, and creatinine level. So, probably, it would be nice if we add a button "Refresh" right after the label "Creatinine Clearance". Every time a doctor changes Weight or Creatinine Level, s/he can push Refresh and the system should re-calculate and display a new Creatinine Clearance value.
[B] It is simple for me to add fields and buttons to my sketch. Hope it would
not be very difficult for OpenRules too. Here is my updated sketch:
[T] Looks almost perfect to me (I still have some doubts about your use of comma for multiple allergies, but we will worry about that issue later). So, do we need any other forms?
[B] Of course. After entering information on this screen, I want to be able to run our rules and display the recommended medication, doses and all other results produced by our rule engine.
[T] So, draw your final form for the rule engine recommendations. Just keep in mind that all fields on this form will be "read only".
[B] Give me a minute. Here we go:
[T] Good. Let's summarize what we did so far. We defined three Web forms:
and specified all the input and output fields in them. Now we have to convert your sketches into Excel tables known in OpenRules as Layouts.
[B] OK, do you want me to start adding new tables to our old Excel file?
[T] Just a second. First of all, I will add a new worksheet to the Excel file and call it "Layouts". We will put three layout tables into this worksheet, that is one for each of your three sketches. Let me create the very first layout myself and then you take over.
[T] I will start with your form "Visit Information". In your sketch, you have actually already defined a table with a very simple generic structure:
|
Header |
|
| "Label 1" | [Input 1] |
| "Label 2" | [Input 2] |
| ... | ... |
In OpenRules, all Labels are added to the Layout cells using quotation marks. Input fields are usually attributes of some objects and they are surrounded by square brackets, for example: [visit.encounterDiagnosis]. So, here is my layout table for your "Visit Information" sketch:
Just as in the case of Rules tables, the very first (black) row of this table describes the table interface:
- the keyword "Layout" defines the type of the table
- the words "TableLayout VisitInformation(Visit visit)" is a signature of this
table. It means that this table will be known under the name "VisitInformation" with one parameter of
the type "Visit" and it will return an object of the type TableLayout.
[B] I can see: you are using the parameter "visit" to specify an input field like [visit.date]. I think it is pretty intuitive. So, let me try to create two other sketches myself. Here is my layout for "Patient Information":
How would I represent a button "Refresh"? For now I just put a question mark in the
proper cell.
[T] That's a good beginning. Allow me make a few comments.
1) Remember that our fields "Name", "Age", and "Creatinine Clearance" are not input fields and should be read only? To do this, you only need to omit the square brackets for these fields. This will indicate to OpenRules that it should only display the current values for attributes of the object "visit".
2) I noticed that you have created 3 separate input fields for "Allergies" starting with the index [0]. While the array "allergies" defined in the datatype "Patient" can contain more than 3 elements, I think you made a safe choice to begin with.
3) And finally, about the "Refresh" button. Do you remember, that
OpenRules allows us to refer to other OpenRules tables inside Excel cells? Let's assume that our button is defined
in other layout called "refreshButton". Here is a standard implementation of a
push button in OpenRules:
It uses basic HTML, but all you need to do is give the push button a name
using value="Refresh". Inside your "PatientInformation" layout you
may refer to this button as refreshButton(). Of course, you also could put this
HTML code directly into your patient's layout. Actually, if you are familiar
with HTML, you
can use it directly in Layout tables to beatify your web pages.
[B] OK, here is my updated Layout:
[T] It seems you would not have problems with the final "Recommendations" layout.
[B] Here it goes:
[T] Great, let's assume that our layout tables are ready. Now we have to discuss an interaction logic and prepare the first working version of our future Web application.
[B] If I had known it would be so simple, I would have done my sketches directly in Excel from the very beginning instead of using Word.
[T] A good idea for the future.
[T] Before we move forward, I believe our Excel file had become overloaded and I would prefer to reorganize our rule project by distributing the tables among different Excel files. Here what I would suggest. Let's create a new Excel file where we will keep only our business rules. I will name this file "HealthCareRules.xls" and will copy into it the HealthCare.xls worksheets:
So, we will keep in this file only information relating to Business Rules. As such, let me remove from "Methods" our launching method "main" and leave here only the "creatinineClearance" calculation method.
[B] It is your area of expertise, so I will just watch. However, I would appreciate if you would continue to comment what you are doing and why you are doing it.
[T] Thank you. So, we still have the following worksheets left in the file HealthCare.xls:
I will copy them into a new Excel file "HealthCareMain.xls". We will have to modify the Environment and Methods later but we will not have to change our business terms and facts. Finally, let me create one more Excel file "HealhCareForms.xls" and copy into it our newly created form layouts. We will keep all tables related to the Web interface in this workbook.
And finally, I will place these files in different subdirectories of the root directory "rules" to follow OpenRules recommendations about Business Rules Repository organization:
[T] So, now we have in the file "HealhCareForms.xls" all our form layouts. But what about the interaction logic?
[B] English please.
[T] OK. How will the system know that first we want to show the Visit Information form and then the Patient Information form? How will it know that when a doctor changes the patient's weight and presses the button "Refresh" the system should recalculate the creatinine clearance?
[B] And that's what you call "interaction logic?" I got it.
[T] And much more. Our Web-based application will be able to read/write data from/to our real database that located somewhere on the server, right? It means we should discuss the interaction logic of screens with respect to the information kept in the database as well as any new information entered by the doctor. For example, how will we treat a new patient that can not be found in the database?
[B] These are all valid questions. It will not be simple to provide all answers right away.
[T]. Right. As we agreed last time, it is always a good practice first to implement an initial version that does the basic work, and add more details as we go. I would suggest you consider a straightforward interaction logic:
Enter input information from you first two forms
Execute our recommendation rules
Display results on a third form.
[B] OK, let's do it. I am really eager to see how my forms work together with rules.
To navigate from one form to another we will add buttons "Next" and "Prev" at
the bottom of each form. OpenRules comes with a standard library to support
different interaction processes. This library "openrules.forms.lib"
includes a so called Dialog Manager that keeps track of the latest pushed
buttons as well as the current and next layouts. The library also provides some convenience methods and
the default presentation style for form background, fonts, etc. While we always
can create a more sophisticated interaction manager, let's stick
the default one described in the Excel file "Dialog.xls".
This manager recommends defining a main method with the name "main"
and using the method "actionButton(name)" for action button layouts.
The method "main" will be executed every time a user pushes an action button. I will put this method in the file "HealthCareMain.xls"
to replace the old method "main". Here it is:
As you see, we will execute our old rules recommendTherapy, recommendDose, and drugInteraction upon each push button event. We can do it more selectively later on, but it will not create serious overhead at this point. I added here two more methods:
Please, make certain that al rules have the parameter "visit" (an instance of our old datatype "Visit"). Processing flow rules should define the value for "dialog().nextLayout", where dialog() is a standard function that provides access to the Dialog object that supports the current interaction session.
[B] I think you lost me with this programming stuff, but hopefully this information is needed only for technical people like yourself.
[T] That's correct. But now I need your active participation. Together
let's specify the processing flow rules by using the following table:
The first column contains the names of our forms (layouts) as processing steps. The first row contains all possible events (actions). You have to put each processing step inside the cell on the intersection of the step-row and the column-event. For example, if a user pushes the action button "Next" while the current step is "VisitInformation", then the next step should be "PatientInformation".
[B] I got it. But what is the action "Init" and why is the very first step-row empty?
[T] The initial event occurs when our application starts for the first time. What is our initial form?
[B] VisitInformation. I will put it in the column "Init" in the first row.
[T]. Good. A empty cell in OpenRules usually means "whatever". Can you fill out the rest of the table?
[B] Here it goes:
[T] Very good. So, when a user clicks to the button "Next" while on the step "PatientInformation", he will be redirected to the step "Recommendations", etc. You left many cells empty. What if a user clicks to the button "Next" while on the step "Recommendations"?
[B] It is impossible because we have not added the button "Next" to the form "Recommendations".
[T] You are right. But in general, it is a good practice to somehow report about "impossible" situations. For example, the "impossible" situation could occur by a programmer error. We could create another Layout table "Impossible", and put it in all empty cells. But let's leave your table as is for now.
[B] OK. But I also have a question to you. What if we have many forms and a much larger processing flow table? Do I have to type the names of the steps every time?
[T] Not necessarily. You can take advantage of the fact that you are in Excel to create drop-down lists. Select the cells with all your steps, and then from the Excel's menu choose Insert + Name + Define. To name the selected range of Excel's cells, types the word "steps" and click "OK". Now, select the entire input area of our processing flow table (all light green cells), and then go to Excel's menu Data + Validation. In the Data Validation dialog, chose "Allow: List" and "Source: =steps". When you done, instead of typing the processing step names you would be able to select them from drop-down lists.
[B] It is cool.
[T] I will not bother you with the implementation details of this table: I added them in the hidden rows. I placed our processingFlowRules in a separate worksheet "Processing Flow Rules" of the file "HealhCareForms.xls". As usual, to see the technical view, just click [2] or "+" buttons.
[B] I don't really care as long as it works and I can add more forms and change the processing logic myself.
[T] Good. And finally we need one more rules table to define which actual layouts correspond to the processing steps we used above. Here is the proper mapping table with the implementation details in gray:
[T] We are almost ready to try our newly created web interface together with old business rules. However, I need to do a few more technical things.
[T] I have to warn you that configuration of Web applications on a Web server is a tricky thing, that usually done by technical experts and certainly not by business analysts. The good news is that you will deal only with Excel rules and forms and will test the results using an Internet browser.
Let me make changes the Environment table inside our main file "HealthCareMain.xls" . Previously, when we used a single file "HealthCare.xls", this table contained only one row that defined the standard lOpenRules tool library com.openrules.tools. Now have to define references to our additional Excel files such as HealthCareRules.xls, HealthCareForms, and standard file Dialog.xls that is already deployed on our web server. Here is the final Environment table:
| Environment | |
| include.path | http://localhost:8080/openrules.forms.lib/ |
| include | ../include/HealthCareRules.xls |
| ../include/HealthCareForms.xls | |
| <Dialog.xls> | |
| import.static | com.openrules.tools.Methods |
Now, I have to deploy our forms and rules on a so called application server. We will use the most popular Open Source server known as Apache Tomcat. I have already downloaded and installed Tomcat in the directory C:/apache-tomcat-5.5.17. I will start this server in a standard way using C:/apache-tomcat-5.5.17/bin/startup.bat. Now I will execute two processes "Build" and "Deploy". I can do it using some special build-files provided by OpenRules. it is enough to double-click to build.bat and then to deploy.bat correspondently. Now we are ready. Please, double-click to the file HealthCare2/run.html to start an Internet browser to work with our deployed project.
[B] Just a second... Wow! This is my first form shown in the Internet Explorer:
[T] Go ahead, push the "Next" button.
[B] Here it is. Look, as we planned, the Creatinine Clearance is automatically calculated and can not be changed!
[B] Let me change the weight from 78 to 88 and push "Refresh". Here we are: the Creatinine Clearance has been changed to 50.11. And now let's see which therapy our smart rule engine will recommend us. I will push "Next":
[B] That's great. I can use the buttons "Prev" and "Next" to navigate between the forms. I like this interface much more than the old black screens. It is much closer to our real system.
[T] Yes. Without changing rules or forms, you need only to change the default style sheet to beautify these screens dramatically. But what is really important is the fact that now our rule engine resides on the web server and available for multiple concurrent users. When you (or an authorized rules administrator) make changes on the server site, they will be immediately reflected on the screens of all connected users.
[B] How can we prevent input errors? For instance, normal creatinine level is about 1 for an average adult. Infants that have little muscle will have lower normal levels (0.2). Muscle bound weight lifters may have a higher normal creatinine. A baby may need dialysis when the creatinine reaches 2, whereas a normal adult may be able to hold off until 10, or higher.
[T] To validate user input, OpenRules provides built-in validators or also allows us creating our own custom validators. For example, let's add a simple validator for creatinine level. Is it fair to say that creatinine level can not be less than 0.01 and more than 15?
[B] As I said, it depends on age, but even such input validation already can prevent many errors.
[T] In this case, it is enough to add a build-in range validator for real numbers (they have type double) as on the following layout:
If a user enter a number that is less than 0.01 or greater than 15, then an error message will be displayed on the right of the input field. We can use a simple Excel table to create a more sophisticated creatinine level validator that will take into consideration patient's age, but let's do it another time.
Today is Friday, and I believe we have reached a good point to call it a day. Thanks for being patient with many technical details I could not avoid.
[B] It is quite OK. I understand that Web application development is a complex discipline, but OpenRules with Excel really makes it much simpler. I feel that we are ready to develop much more complex applications with hundreds of forms controlled by thousands rules using the same approach. And that's exactly what we need. Thank you and have a great weekend.