Drools, part 1.

The goal of this class is to model an offer process in a small company. The diagram below shows a generalized task flow in the process:

The offer process is initiated via an external document describing the order. The description takes many different forms, from informal inquiries (contact is the only valuable part), to highly formalized documents describing the order, broken down into several aspects (commercial, formal, etc). One can distinguish two important features of the query:

1. formal requirements defining the process, eg. preventing or limiting contact with the ordering party at the offer stage, as well as the commercial terms of joining the offer procedure.
2. the level of order specification, e.g. from one that barely signals the subject matter and does not allow any analysiks without further inquiries, to a coherent and complete presentation of the item, which should be enough to prepare the offer.

The process that we want to model will support the user in making decisions during the three main stages of processing the offer inquiry:

1. Formal analysis.
2. Substantive analysis.
3. Preparing the right offer.

First of all, a formal/commercial analysis has to performed. One has to check the conditions, whether the company is able to fulfill the order according to the proposed procedure.

At this stage, the conditions are verified, such as having the right permissions, having the required certificates, appropriate company qualifications, etc.
Negative completion of this stage results in automatic termination of the offer process.

If the formal analysis ends with a positive result, the substantive analysis is performed on the query. Substantive analysis consists of two phases: preliminary substantive analysis and proper substantive analysis. During the initial analysis, it is determined (based on the available knowledge) whether the order can be completed. Factors such as availability of teams, project risk, attractiveness of the order etc. are taken into account here. If the order is feasible, then the proper analysis is performed, during which the cost estimate and the substantive part of the offer are prepared based on the opinions of the experts (e.g. IT department employees). If it turns out that the specification provided in the inquiry is insufficient, then the customer is contacted (if it is possible) to the get missing data. If the contact with the customer is impossible, the request is rejected.

The results of the substantive analysis are: the concept of the solution and the initial cost estimates.

The substantive analysis' results serve as a starting point for preparing the right offer. This stage, carried out by the sales department, is designed to develop the final valuation. The final valuation is calculated on the basis of the valuation prepared by the IT department and appropriate modifiers as: commercial attractiveness, substantive attractiveness, how important is the client, etc.

The offer prepared this way has to be approved by the board, and can be sent to the clien only after applying required fixes and changes.

The modeling of the described example will include:

1. Rule aspect: Defining a rule system supporting a user in the decision-making process at the stages of formal, substantive and offer preparation.
2. Process aspect: Mmdeling the complete process describing the request processing.

The description you've just read is only meant to introduce into the context. Details, like sizes, attributes, coefficients and their dependencies describing the problem will be introduced only at the appropriate modeling stage. The instructions are not binding and you can freely make modifications at your own discretion / invention.

• In first part, we will model the basic components of the knowledge base (or repository as you will see).
• We will also learn how to create additional resources (resource files, packages, etc.), required to execute the model
• For now we will model only the formal analysis part of the process.

Having the JBoss running, visit the following address:
http://127.0.0.1:8080/drools-guvnor
In case you were asked to log in, enter:

login: admin
password: admin

In the left panel there are several entries:

• Browse - just browse the repository
• Knowledge Bases - contains definitions of all the knowledge bases, their packages and components. This will interest us at most.
• QA - allows user to define and run tests.
• Package snapshots - manages the compiled packages
• Administration - you can guess ;)

• Every item in the repository has to be placed in the Global Area, or in a package
• In order to prevent conflicts between different teams working on the same repository, every user should create his own package (with an unique name).
• To create a new package, enter Knowledge Bases and choose Create New ⇒ New Package:
• Avoid spaces and special characters (like dash '-') in the name

• Before being used, the package has to be compiled first
• We wil compile the package in the beginning, so later we will have only to update it.
• To compile the package
  1. click on the name of the package (left panel)
  2. select the Edit tab,
  3. press Build package.
• Successful compilation is indicated by a green icon and a message similar to:

  Package built successfully. Last modified on Wed Oct 24 11:14:10 GMT+200 2012

• A good practice is to create snapshots of the package, that will be later delivered to the applications. This way we will avoid version related problems.
• In order to create a snapshot, one has to:
  1. press Create snapshot for deployment
  2. first time one has to press NEW and give it a name, e.g. package_name-pkg — again, avoid spaces at all costs
  3. later, there will be a second option to use the existing name (that we will use)

• Resource database ChangeSet, this file contains all resources' definition
• One can add resource in one of the two ways:
  1. Every resource one by one .
  2. We add a file that contains resources' definitions, so called ChangeSet.
• The second solution is better because:
  1. there is no need to recompile the package after changing the resources (size, amount)
  2. the ChangeSet can be easily downloaded from the server
• To create ChangeSet one has to:
  • choose the Knowledge bases item on the left panel
  • select Create new ⇒ New Change Set
  • in the new dialog:
    1. press Create new.
    2. give a name, e.g. package_name-cs - again no spaces
    3. we make sure that it will be created in our package
       1. press Create in Package.
       2. choose name of your package
    4. press OK.
• The file has been created; now we can edit it. For now we add there only a snapshot of our package
  1. we put cursor between the tags <add>…</add>.
  2. In left part of the windows, we press Package, in the Add new <resource> Element section.
     One can also add single items from other packages, using the button:Asset.
  3. In the new dialog we expand the Packages tree too find the recently created snapshot.
  4. If everything has been done correctly, you should get a result similar to

     <resource   source='http://127.0.0.1:8080/drools-guvnor/org.drools.guvnor.Guvnor/package/package-name/snapshot-name' type='PKG'/>

• This file contains a resource in a form of a package snapshot, that should be enough to compile the knowledge base.
• In order to give access to the resources from the outside, we have to make it availible. In theresource tag, we add the three attributes and values:
  1. basicAuthentication='enabled'
  2. username='admin'
  3. password='admin'
• Now we save the file: File ⇒ Save and close.

• Before adding rules, we have first to define structure of the knowledge base/facts. Again we can go two ways:
  1. use the guvnor interface
  2. upload the POJO (Plain Old Java Object) classes in a jar.
• We will go the first way
• We will define two types of facts:
  1. Proper facts - facts/objects containing knownledge obtained during the offer process
  2. Auxiliary facts - facts/objects defining the state of the process.

• At this moment we can define the following facts:
  1. Type 1: facts telling if the offer fulfills certain formal requirements, e.g
     1. Is the aquisition possible?
     2. Do we have a sufficient insurance policy.
     3. Do we have a required certificates.
     4. Do we have sufficient experience?
     5. Does the offer meets the minimal formal expectations?
     6. Is the offer in conflict with the different offers?
  2. Type 2: facts containing decisions took in the formal analysis process
  3. Type 3: auxiliary facts defining the current state of the proccess
• Because Type 1. facts are very similar to each other, to we can use the inheritance technique, known from tohe object programming. We will create one base fact and other will inherit from it.
• Because facto of Type 1 and Type 2 are on a similar level of abstraction, they will put together in the same group. The Type 3 will be separated.
• In order to define a group of facts, one has to:
  1. use Knowledge bases ⇒ Create New ⇒ New Declarative Model
  2. In the new dialog window:
     1. select Create new
     2. choose a name, e.g. factTypes
     3. then Create in Package:.
     4. We select our package from the list.
• The same way one can define the second group, e.g. helperTypes.
• Now we can define the fact types:
  1. Assets ⇒ Model ⇒ factTypes (your name) ⇒ Open.
  2. In the new window we press Add new fact type to add a new type
  3. First, we will create a base type for the all Type 1 facts.
     1. give it a name, e.g. reqsFormal
     2. OK
     3. Now we define fields/properties of the type:
        • Asked - [True/False] - defining if the specific question was asked/answered
        • Question - [String] - the question itself
        • Answer - [True/False] - answer provided by the user
        • ProceedAnswer - [True/False] - correct (positive) answer for the question
        1. To add the field, find the Add Field button in the edition panel and fill the form:
           1. specify the name, e.g. Question
           2. select the Text datatype.
  4. After creating the base type, we will define the other facts based on it
     1. Our facts will not add any new fields, they will just differ with a type itself
     2. To create a deriverative fact, we proceed almost the same way as before; we have only to select the base type:
     3. This way we create at least six new types:
        1. reqsFormalAcquisition
        2. reqsFormalInsurance
        3. reqsFormalCertificates
        4. reqsFormalExperience
        5. reqsFormalMinExpectations
        6. reqsFormalConflicts
  5. Now, the last fact in this group will be tyhe Type 2 fact. It will contain a decision whether the offer passed the formal analysis:
     1. the new fact should be named formalDecision and have only one boolean field Decision
  6. Resulting list of facts should look similiar to:
  7. Don't forget to File ⇒ Save and close.
  8. Now the second group, the helperTypes:
     1. Add a new fact type based on:
  9. This fact will hold info about the current state of the process
  10. The state field will be of the Text type and will get values only from a specified list
  11. To add this kind of enumarated type:
      1. Create New ⇒ New Enumeration.
      2. Then:
         • Create new,
         • give it a name, e.g. sthuc-enums,
         • Create in Package: ⇒ select our package
         • upewniamy się że obiekt zostanie utworzony w naszym pakiecie.
      3. In case we were asked to edit the object after creating it, we put in:

         'State.state' : ['initial', 'formal']

      4. In case we were asked to fill a simple form, we fill it in a following way:
         • Fact: State
         • Field: state
         • Contex: ['initial', 'formal']
      5. Then: File ⇒ Save and close!

• We will need four following rules:
  1. rule that would initialize the knowledge base
  2. rule that asks user a question and store the answer
  3. rule that checks if we should proceed to the next step of the process
  4. rule that would refuse the offer if didn't pass the formal requirements
• Let's start with the first rule:
  1. Create New ⇒ New Rule.
     1. Create new,
     2. fill in the name, e.g. initial,
     3. from Type (format) of rule: we choose Business Rule (Guided Editor),
     4. Create in package and make sure you select a good package
  2. Another window…
     1. Because this is an initializing rule, it doesn't need a conditional part. We only define the decisive part of the rule:
        1. THEN ⇒ PLUS
        2. If the new window doesn't contain an action that would satisfy us, we can always add a new action manually by choosing Add free form drl. In our case however ther will be no need for such a drastic measure. Our rule will just add one instance of fact per every type. To create a fact one should:
           1. Insert fact reqsFormalAcquisition… (or other name)
           2. OK.
           3. We fill initial values of the fact's fields:
              • Asked = false because it wasn't asked yet
              • ProceedAnswer should a positive value by default.
              • Question should have a form of a question specified in natural language (e.g. Is the aquisition possible [true/false]
           4. To put an initial value:
              1. we select the new action
              2. we choose a field we want to modify
              3. the Bound variable field should be left empty
              4. press the pencil button next to the field and choose a Literal value (so we can put a constant). To use variables or other expressions we would have to select Forumla
        3. After creating all the Type 1 fact, we add a new auxiliary fact State, with a field state set to formal (because it's an initial state of the process).
        4. The rule should look similiar to:
  3. File ⇒ Save and close.
• Second rule will display questions and gather the answers:
  1. Let's give it a name: reqsFormalFill.
  2. There are two conditions that have to be meet before firing the rule:
     1. There is a State fact with a fieldstate set to formal,
     2. There are still fact based on reqsFormal, that user hasn't answered yet (Asked == false).
  3. For every fact of this type, the rule should:
     1. display the querstion contained in the fact
     2. get the answer
     3. modify the processed fact
  4. To do this:
     1. We add the first conition: There exists a fact of type State with field state set to formal.
        1. WHEN ⇒ PLUS
        2. In the familiar dialog we choose State…, then OK.
        3. There should be a new condition now, There is a State:.
        4. We click on it, then press Add a restriction on a field ⇒ state.
        5. Name of the field should be now added to the condition
        6. W choose equal to from the list and define the constraint
     2. In the same way we add condition: There exist facts of type reqsFormal (or deriverative), that weren't answered yet (Asked == false).
     3. In order to have access to the fact that triggered the rule, we put a name into a Variable name field:
     4. The conditional part of the rule should look similiar to
     5. Now we can define a decisive part.
     6. First action: display question. We will use a terminal to do thatl, so we choose Add free form drl….
        1. Now we put the java code:

           System.out.println(r.Question + "?");

           Notice that we can refer to the fact via the variable r.

     7. Second action will read the answer. Again: Add free form drl… and

        java.io.InputStreamReader rd = new java.io.InputStreamReader(System.in);
        java.io.BufferedReader bfr = new java.io.BufferedReader(rd);
        java.lang.Boolean val = Boolean.valueOf(bfr.readLine());
        r.setAnswer( val );

     8. Third and the last action will be to update the Asked field's value.
        1. we add new action: Modify r…
           Question: (how does it differ from Change field values of r…?),
        2. we choose a field a new value.
     9. The complete rule should look like:
• Third and fourth rules are triggered when all the decision have been already made, i.e.
  • reqsFormalOK: offer can be processed if every answer is equal to the ProceedAnswer of the related fact.
  • reqsFormalFail: otherwise

Precisely, the reqsFormalOK rule is triggered by the following conditions:

1. There is a fact State with state field set to value formal.
2. There is no fact of type reqsFormal (or derived), that:
   1. would have Asked field equal false.
   2. Asked == true and at the same time Answer not equalt the ProceedAnswer.

• The reqsFormalFail is fired if any of those conditions is not met.
• The decisive parts of both the rules create a new fact formalDecision with a corresponding Decision value
• Both rules should also display their results in the terminal. The reqsFormalFail rule should also display reason, why the offer was rejected.