Cross Module - KRMS Basic Rule Setup

Overview

The Kuali Rules Management System allows institutions to drive application behavior in a number of different ways including data validation, workflow logic, and progressive questionnaire display.  It is a robust system that can help minimize effort on the part of end users, and improve data quality.  This guide will take you through the steps of setting up a basic single Proposition business rule, and then in subsequent articles you will see the various ways that business rule can be leveraged in the system, as well as how to setup more complicated Proposition logic.

Setting up an Initial Agenda

First go to All Links in the Dashboard and search for Agenda and select:

This will open the Agenda search.  You can either search for an existing Agenda that you want to add additional rules to, or you can click on the Create New button in the upper right hand corner of the screen to create a new Agenda document.

Once you have initiated your new Agenda document you will need to complete the following fields.

• Namespace: List the module you want the rules in this agenda to apply to.
• Name: This is the name of your agenda. It must be unique and if you are going to make extensive use of KRMS it is a good idea to setup a standard naming convention when you first start building rules to avoid confusion in the future.
• Context: This will drive the rest of your Agenda functionality. Each context is paired with a specific module and you won't be able to fill in any additional Agenda information until you have selected your Context.
• Active: If you uncheck this field then none of the rules in this Agenda will function.  This can be useful for retiring rules as business processes change, or if you accidentally create a rule that creates a problem you can deactivate it immediately and then begin to debug your logic.

Once you have entered your Context the following fields will appear

Type: This tells KRMS when to execute the agenda, there are three options:

• Unit - This Agenda type will be used for Validations, Standard Routing Actions and Notifications. This is available in all Contexts.
• Questionnaire - The logic in these Agendas is reserved for inclusion in a Questionnaire. This is only available in the Proposal Development context.
• Cost Share Agenda - This Agenda Type is required to drive Cost Share routing in Proposal Development. Details on how to setup this functionality is included in more detail in the Cost Share to Account Configuration article. This is only available in the Proposal Development Context.

After entering the Agenda Type the following field will appear

Unit Number: This tells KRMS which unit the Agenda should fire for.  Any document associated with your selected Context with a Lead Unit that reports up to the unit you list in this field will execute the rules included in this Agenda. For Proposal Development any included proposal units that report up to the unit listed in this field will also execute the rules included in this agenda.  This unit driven logic applies to both the Unit and Questionnaire Agenda Types.  Cost Share Agendas will fire based on the cost share units listed in Proposal Development.

Adding a Rule to Agenda

Next click the Add Rule button on the Rules toolbar

This will take you into the new rule editor.  First complete the following fields.

• Type: The only option for this field is Validation Rule.  You can leave this field blank.  If it is left blank the system will ignore any logic you load into the rule, and the action associated with this rule will always execute if this rule is fired by the KRMS system.
• Invalid Rule: This field will appear if you select the Validation Rule type.  The "Action Executed When True" Rule type is recommended, as then your action will execute if the logic you setup is true.
• Name: Each rule in the system must have a unique name. Building a naming convention for your institution will be helpful for keeping track of your Agendas, and for passing maintenance tasks onto future administrators.
• Description: Provide a detailed description of the purpose for the rule, especially if this rule is going to be used for questionnaire. You can see this description in the rule lookup, but you cannot review the actual logic. So this is the one place you can detail the purpose of this rule for future administrators.
• Active: This flag can be used to deactivate specific rules in a larger agenda when business processes change, but the overall agenda needs to remain active.

Next click the Add button on the Propositions toolbar.

Complete the following fields to enter your 

• Description: Create a brief summary of your proposition logic. Only describe the logic of this basic proposition (Example “Proposal Activity Type is Research”).
• Category: This filters the Term list. It is not required, but simplifies finding your term in a large list.
• Term: This is the value used for comparison.  Some of these will be simple values like “Proposal Type Code” while others may be more complex like “Check if Lead Unit Reports Up to  Unit”. The next page will explain how the different types of terms work.
• Comparison: There are a variety of comparisons that can be used here.  The most common one will be = which just checks to see if your term matches the value you enter in the field. < and > can only check numbers or dates and work as mathematical comparisons. != means that the value does not match, and =null or != null does not check the value in the term specifically, but just checks to make certain something is entered. This is important when you just want to make a field required.
• Value: This field is required for every Comparison other than =null and != null. This is the value you are comparing to the selected Term. Different terms expect different types of values in this field. The various expected values are detailed below.

When you are constructing your logic you will use one of three types of Terms.  They each behave a little bit differently, so it is important to understand the data they will be returning.

Properties: These terms will return the exact data that is stored in the database for a specific field in KC. A good example of this is the out of the box “Activity Type Code” Proposal Development Property. This will return a number from the Activity Type Code table that corresponds with the Activity Type the user selected.  Properties are very simple. If you wanted all Clinical Trials to route to a special review group you could set your logic up as shown above. This is based on the out of the box Activity Type Code for Clinical Trials. Your institution has likely changed the values and you should look up the appropriate values for your implementation before creating your proposition.

Functions: Unlike Properties, Functions are required to return information that isn’t stored in a single place in the database. Functions will either check for a single specific thing like “Proposal Narratives Complete” or they will require some additional information such as “Lead Unit Below Rule(_)”. If you see a (_) or (_._) at the end of a function name you will need to enter additional information to use the function. The number of _ characters  indicates how many  additional data points will be needed. Most functions will return either true or false (with no capitalization) depending on if the conditions you set are fulfilled in a document.

Example: A special routing is needed for everyone in the Indianapolis campus (IN-IN), but the medical school is exempt from this requirement. So the Unit on the agenda is set to IN-IN, but we only want to run this validation if the unit is not in the medical school. So the Function “Lead Unit Below Rule(_)” is utilized and the Unit Number listed is IN-MED, which is the code for the medical school. Since we want these units to not include the special routing the Value is set to false.

Questionnaire and Custom Data: Questionnaire and Custom Data Terms are similar to functions in that you must complete additional parameters to use them. To use a Questionnaire term you enter the Question ID and Questionnaire ID that correspond to the question you want to evaluate. To use a Custom Data Term enter the Custom Data ID that correspond to the field you want to evaluate. The term will then return the value stored in the Question or Custom Data field. So you can use any of the Comparison tools available for Property terms.

Example: Your institution has included a question about Chinese involvement on all proposals that receive NASA funding.  If the Aggregator indicates that there will be Chinese involvement then a validation displays directing the user to contact their grant officer to make sure they are not in violation of NASA regulations related to working with Chinese entities.  So the questionnaire and question values for this question are listed in the function parameters, and the comparison value is marked as Y.

If you use a Function. Questionnaire, or Custom Data term that involved the addition of Parameters then the next time you open Agenda a new function will be added to the Term list that reflects this setup you did here, so you don't have to complete all the setup multiple times.  The value you entered in the Name field will appear in the Term dropdown list, so be sure it is appropriately descriptive.

Next Steps

At this point you have a complete proposition.  This rule can be tied to a number of different actions in the system. Choose the next step for your KRMS rule setup below.

Cross Module Functionality - KRMS Validation Setup

Cross Module Functionality - People Flow Adding a Stop to Your Existing Routing Process