Authoring Business Rules in IBM Case Manager 5.2 Create and use text-based rules and tablebased business rules in IBM Case Manager 5.2 This article covers creating Business Rules in IBM Case Manager, the different Completion Menu options available, and authoring text-based rules and table-based rules. It also describes the different sections of a rule and using Business rules in workflows. Table-based rules features like Gaps, Overlaps and Otherwise is explained. Using custom parameters in a rule and configuring values for the custom parameters in Process Designer is also covered. Nagabhushan & Latha Ramakrishnaiah 11/21/2013 Nagabhushan is a Senior Software Engineer with more than 16 years of experience in Software Testing. Over the last three years, he has been working on Functional testing of IBM Case Manager. In addition to IBM Case Manager, he has worked on Data Servers and Master Data Management products. Reach out to him at bbhushan@in.ibm.com. Latha Ramakrishnaiah is a Software Test Engineer with IBM India software Labs. She is currently working with IBM Case Manager Team in Enterprise Content Management. She has also worked in FileNet Image Services Resource Adapter product on L3 support and Testing. Reach out to her at latharamakrishnaiah@in.ibm.com.
Introduction Business scenarios require validity checks and conditional processing based on business rules and more often, these business rules are included in the process workflow. Considering the dynamics of today s business world, the ease of defining, and maintaining a business rule, is a very much required component of any Case Management system. The IBM Case Manager 5.2 is bundled with IBM Business Rules Embedded for easy definition of a business rule while designing the solution. The IBM Business Rules Embedded is a SDK, a component of the IBM Operational Decision Manager product. Unlike earlier versions, no separate installation of ILOG JRules Studio and Rule Execution server is required the SDK is installed as part of ICM installation. The Business Rules Embedded SDK allows seamless authoring of Rules within IBM Case Manager Builder, and associating defined rules with Rule Steps in the workflow. There is no need of defining the rules in a Rules server, and manually configuring the related WSDL in Process Designer. The Embedded Rules in IBM Case Manager supports definition of business rules in the form of Text-based Rules and Table-based Rules (also known as Decision Tables), referencing Case Properties and external values through Custom Rule Parameters. Text-based rules are written in Business Action Language (BAL) and consist of three parts: definitions, conditions, actions. Of these, an action is mandatory, where as the other two are optional. Table-based rules are used to express sets of similar conditions and actions in business rules. Each row in a table-based rule can be considered as a text-based rule. A table-based rule can have multiple condition columns and multiple action columns. An option for checking gaps and overlaps in the value ranges also exist. Table-based business rules also support Custom Rule Parameters. This article shows a simple example of authoring text-based rules and table-based rules in a solution, capabilities and features of the Rule editors, and mapping values to Custom Parameters in Process Designer. It also covers calling a business rule in a task workflow through a rule step. Usecase The first example is a scenario of Loan Request Processing. It consists of a text-based rule which automates the process of setting value for a Boolean case property based on validations. This Boolean case property can be further used for automating the workflow, 2
for example, sending an approval email. The example also shows using custom parameters and configuring the custom parameters in Process Designer. The second example is a table-based rule which automates the process of deciding the Fixed Deposit Interest rate based on value ranges of business decision factors, such as, Age, Term of the deposit, etc. Creating the Solution The following properties are created while designing the solution in Case Builder. Table 1. Case Properties for Usecase Property Name Type Description Account Holder Name String Name of the Account Holder Account Number Integer Account Number Age Integer Age of the Account Holder Gender String Account Holder Gender, associated with the string choice list, Gender List. Customer Category String Customer Category, associated with the string choice list, Customer Category List Is Salary Account Boolean Is this account a Salary account of the customer? Relationship Start Date DateTime Date on which the customer started his relationship with the bank Account Balance Float Balance in Account FD Deposit Amount Float Amount the customer is depositing as Fixed Deposit FD Interest Rate Float FD Interest Rate decided by the business rule FD Deposit Term Integer Term of the FD Deposit in days Requested Loan Amount Float Loan Amount requested by the customer Remarks String For capturing processing remarks, with maximum length of 1333 characters Approval Status Boolean Set to True if the loan is approved The Gender List choice list has the following options: MALE FEMALE 3
The Customer Category List choice list has the following options: GOLD SILVER NORMAL While all the properties are defined with the default values, for the Remarks string property, the maximum length is set to 1333 characters. A role, Loan Processor, is created. The Loan Processor role inputs the required data for either loan processing or Fixed Deposit processing, and subsequently validates the outputs from the rules, which are authored to suit the business requirements. A case type, Bank Processes is created in the solution. To this case type, all the properties are added. A new interface, Rules has been introduced in the Case type menu. Similar to creating properties, Rules can be created and stored in the solution. In IBM Case Manager, two types of rules can be created, text-based rule and table-based rule. The table-based rule is the same as Decision Tables in Jrules. The dialog for adding a rule presents an interface for: Rule name Rule Description Unique identifier Type of rule (whether a text-based rule and a table-based rule) Figure 1. Add Rule Dialog The following two rules are created in the solution: Table 2. Rules for Usecase Rule Name Rule Type Rule Description Loan Approval Text-based Rule Business Rule for validating conditions for loan approval FD Interest Calculator Table-based Rule Business Rule for determining FD Interest based on different conditions Text-based Rules Text-based Rule Editor 4
For a text-based Rule, clicking on the rule name brings up the text-based editor for authoring the rule. While the editor is open, other interfaces to the solution are inaccessible. The text-based rule editor consists of three sections a toolbar in the top, an editing section in the middle, and an error and warning section at the bottom. The toolbar at the top has Completion Menu Options and Custom Parameters definitions in addition to Undo and Redo Buttons. As in an Integrated Development Environment, the SDK embedded prompts the user with code snippets and associated documentation / help. The nature of the prompting is decided by the options set in the Completion Menu Options, accessible from the Toolbar. An example of a Completion Menu is shown below. Figure 2. Completion Menu Example The Completion Menu Options has the following options: 5
Figure 3. Completion Menu Options Some of the frequently used Completion Menu Options are explained below. Enable on Spacebar : brings up context sensitive Completion menu as and when Spacebar is keyed in as part of authoring the rule. Another way to bring up the completion menu is by Ctrl+Spacebar. Enable template mode : When selected, inserts a template into the code, with place holders for relevant sections. In the below example, after selecting the set statement from the completion menu, <a casetype> and <a number> are templates, clicking on which brings up the filtered context sensitive content. Figure 4. Template Mode Example 6
Use Hierarchical View : This option arranges the keywords grouped and arranged in a hierarchical manner, thereby searching for a keyword made easier. Case related keywords are arranged under the group casetype. Alternatively, hierarchical arrangement can be forced by clicking on the icon in the toolbar of the completion menu. Also, a particular keyword can be searched from the Search option in the menu completion. More information about Completion Menu options can be found here. Custom Parameters are used to map external data, for example, credit rating of a customer, or currency exchange rate, from an external service, to be used in the business rule. Custom parameters can be read, that is, they can be used to make decisions in condition statements, but cannot be written, that is, custom parameters cannot be modified using set statements in the rule. Custom parameters can be defined in all the supported data types, and also, it can be single value and multiple valued, similar to properties. Figure 5. Defining a Custom Parameter The editing section in the middle is where the rule authoring is done. The editor has syntax highlighting, and prompting the user for relevant code with Completion Menu as per the options set in the Completion Menu Options. 7
The errors and warnings appear in real-time, as when the rule is being authored in the rule. IBM Case Manager allows rules with errors and warnings to be saved in the solution, but deploying a solution with erroneous rules will result in deployment errors. 8
Figure 6. Errors and Warnings Loan Approval Text-based Rule The Business requirements for approving a loan are: Requested Loan Amount should be less than 1,500,000. This might change as decided by the management, and hence should be easily editable Credit Rating of the Account Holder should be more than 80. The bank is sourcing the credit ratings from an external agency. The Account Holder name does not appear in a list of defaulters. An external agency maintains this list of defaulters. Either the Account Holder should have a Salary account in the bank, or, he should have opened his account before 36 months and he should be a GOLD category customer of the bank If all the above conditions are satisfied, then the Boolean case property Approval Status is set to true. Also, instructions are added to the rulereturnvalue data field of the rule as Remarks. A status message of person processing the case is also appended to the rulereturnvalue. 9
The mechanism of obtaining the Credit Rating of the Account Holder and the list of defaulters is outside the scope of this article. We will be populating the Credit Rating and the list of defaulters using a Assign step in Process Designer before the Rule steps. The following three Custom Parameters are defined. Table 3. Custom Parameters Name Data Type Single Value / Multiple Values Credit Rating From External Agency Relationship Duration in Months Integer Integer Single Value Single Value List Of Defaulters String Multiple Values Figure 7. Custom Parameters For the scope of this article, all the three values of the Custom Parameters will be coming from a Assign System Step before the rule step. Let us consider the requirements one by one: Requested Loan Amount should be less than 1,500,000. This might change as decided by the management, and hence should be easily editable 10
For this requirement, we will define an integer variable Loan Threshold and assign it the value of 1,500,000. As it is defined as a variable, it can be easily modified as decided by the management. All variables declared in the definitions section of the rule are available only in the scope of the rule. The data type of the variable is decided by the value assigned to the variables. The value of the variables can be assigned to case properties. Figure 8. Definitions in Rule Considering the remaining requirements: Requested Loan Amount should be less than 1,500,000. This might change as decided by the management, and hence should be easily editable Credit Rating of the Account Holder should be more than 80. The bank is sourcing the credit ratings from an external agency. The Account Holder name does not appear in a list of defaulters. An external agency maintains this list of defaulters. All of the conditions are included in an if condition: Figure 9. if condition in Rules 11
Considering the next requirement: Either the Account Holder should have a Salary account in the bank, or, he should have opened his account before 36 months and he should be a GOLD category customer of the bank This check is included by adding another if condition within the previous if Fig 10. if condition within a if condition Please note that the Boolean Case property Is Salary Account starts with the Case type, Bank Processes and then proceeds to the Boolean Case property, unlike other data types, which start with the Case property and is then suffixed by the Case type. Also, since Customer Category is a String Case property associated with a choice list, it can be seen that the Completion Menu prompts by providing the choices in the Completion Menu. Please note that this kind of prompting is available for only String Choice lists. 12
Fig11. Completed nested if We now proceed to authoring the action section of the rules: If all the above conditions are satisfied, then the Boolean case property Approval Status is set to true. Also, instructions are added to the rulereturnvalue data field as a comment. A status message about the case worker (Last Modifier of the case) is also appended to the rulereturnvalue. Figure 12. then and else in Rules The actions are defined by the then and else sections. 13
The outputs of the print statements are assigned to the data field, rulereturnvalue. This data field is added to the workflow when a Rule step is added to the workflow. This behaves as any other user defined data field and can also be used for workflow routing. When there are multiple print statements in the rule, the contents are appended and then assigned to rulereturnvalue. Since there are no formatting options available for processing the print statements, in this case, we are using for separating the output from the two print statements. Case System Properties can also be used in the rule. The following Case System properties are available: Case Identifier Case State Creator Date Created Date Last Modified Last Modifier All of the above Case System Properties can be read they can be used for reference, or capturing the status. Other than the Case Identifier, Case System Properties cannot be set. In this example, the Last Modifier Case System Property is used. It is a good practice to check that all the Case Properties which are retrieved in the rule have values. This is done to avoid receiving possible dereferencing errors during run time. For String and DateTime data types, the check for null values is done using the not null keyword. For Integer and Float data types, the check for null values is done by mapping to an equivalent variable, which in turn will be used in the rule. In the example, the following Case Properties and Custom Parameters are retrieved: Requested Loan Amount Credit Rating From External Agency Account Holder Name List of Defaulters Relationship Duration In Months Customer Category Hence, Requested Loan Amount is mapped to Requested Loan Amount in Rule Credit Rating From External Agency is mapped to Credit Rating From External Agency in Rule Relationship Duration in Months is mapped to Relationship Duration in Months in Rule 14
These three definitions would be used in the rule instead of the original Case properties or Custom parameters. Account Holder Name and Customer Category is checked for not null. The List Of Defaulters is checked that it holds valid content by verifying the count of number of elements in the multiple-value custom parameter. 15
Figure 13. Completed Text-based Rule Workflow definition A task, Loan Request Process, configured to be started manually, is created in the Case Type, Bank Processes. This will have the workflow which will be using the business rule. Figure 14. Task for Text-based Rule The workflow in the Loan Request Process is designed as below: 16
Figure 15. Workflow definition with Text-based Rule At the Step Enter Details, the following case properties are added : Figure 16. Case Properties for Enter Details step At the Step Verify, the Loan Processor verifies the entered details, and the state of Approval Status which shows whether the loan is approved. As the Loan Processor will not be inputting any values, the properties are added as "Read-only" 17
Figure 17. Case Properties for Verify Step Modifications in Process Designer For the scope of this article, we will be adding the following data fields to the workflow, and assigning values to the data fields in the Assign step. In other implementations, these can be values from external resources like Web Services, or calculated values, for example, SystemTime. Table 4. Assigning values to data fields Data Field Name Data Type Values CreditRating Integer 100 RelationshipDuration Integer 40 Defaulters String [] John Smith, John Doe, Alice, Bob 18
Figure 18. Assigning values to data fields Next, the custom parameters defined in the Business Rule associated to Loan Approval Rule step needs to be configured to these data fields. Figure 19. customruleparameternames and customruleparametervalues The Custom Parameters added to the rule, are seen in the String array, customruleparameternames. The values for each of these Custom Parameters have to be added to the String array, customruleparametervalues, exactly in the same order as in customruleparameternames. As it is a string array, the values passed to the customruleparametervalues should be string values. If the values are of a different data type other than string, convert function would have to be used to convert the values to string data type. Table 5. Examples for converting data types to strings Data Type Data Field (Example) Converting to String Boolean DF_Bool1 convert (DF_Bool1, string) DateTime DF_DateTime1 timetostring (DF_DateTime1,"yyyymm-dd hh:tt:ss") Float DF_Float1 convert(df_float1, string) Integer DF_Int1 convert(df_int1, string) String DF_Str1 No need of conversion, as the expected 19
Multiple Value Properties DF_StrArray value is a string arraytostring(df_strarray,"{","}",",") For this example, the mappings are as below: Table 6. Data Fields mappings to Custom Parameters Custom Parameter Mapping CreditRatingFromExternalAgency RelationshipDurationInMonths ListOfDefaulters convert(creditrating,string) convert(relationshipduration,string) arraytostring(defaulters,"{","}",",") Figure 20. Custom Parameters mappings Please note that if there are any modifications to the business rule in terms of custom parameters, for example, adding a new custom parameter, the newly added parameter will not be available in Process Designer until the Rule Step is again newly added to the workflow. Any customruleparametervalues configured before will have to be reconfigured. rulereturnvalue is a string data field which is available in the workflow whenever a Rule Step is added to the workflow. This data field holds the consolidated output of the print statements in the rule. Since, in the example, there are print statements, the rulereturnvalue is added as a parameter to the Verify step. 20
Figure 21. Adding rulereturnvalue to a step The changes can be committed and deployed. Any errors in Business Rules or Workflow definition would be caught either during validation or during deployment, and can be corrected for successful deployment. If there are any changes to the Business Rules, the solution will have to be deployed again for the modified business rule to be effected. Table-based Business Rule Table-based rules are more suitable for defining rules which are similar, but working on different ranges of values. A table-like interface is presented with the columns being the conditions and actions, and each row with a range of values, and hence, each row can be considered as a rule. Table-based Rule Editor The Table-based Rule editor has a toolbar, condition columns, action columns, and a Refresh button. The toolbar at the top has a button for defining Custom Parameters the functionality and the interface for defining Custom Parameters is the same as for text-based rule. The Table-based Rule Editor by default has three Condition Columns and one Action Column. The Condition columns are named A,B, C, and the Action column is named D. The Condition columns and Action columns are differentiated by different colors in the column header. 20 rows are available by default. 21
As was said before, each row of the Table-based rule is equivalent to a text-based rule. For the actions defined in all the condition columns, all the actions specified in the action columns are executed. The Refresh button is situated at the top-left corner of the table, and is used for: Validating the content of the Condition columns and Action columns Removing un-used rows Sorting the data Merging cells with similar content in condition columns The headers and the cells have different right-click options, which can be used for adding more columns, defining the column (condition / action for that column), clearing the contents, defining cell content, etc. 22
Figure 22. Table-based Rule Editor FD Interest Calculator Table-based Rule The following is the conditions and actions for determining the FD Interest. The action is the same determining the FD Interest, which is different for a different set of ranges. Along with that, we are populating a String case property with related comments, and also printing the value of the Last modifier. Similar to text-based rule, the content of print statements will be used to populate rulereturnvalue data field. Table 6. Business Conditions for table-based rule Age Gender FD Deposit Amount Term in Days FD Interest Remarks 0 to 59 FEMALE 0 to 50,000 0 to 90 8 Women Appreciation Print Last Modifier 0 to 59 FEMALE More than 0 to 90 8.5 Women Last Modifier 23
50,000 Appreciation 0 to 59 MALE 0 to 50,000 0 to 90 7.5 Last Modifier 0 to 59 MALE More than 50,000 60 to 79 Not Applicable More than 79 Not Applicable More than 10,000 More than 10,000 0 to 90 8 Last Modifier 0 to 90 8.5 Senior Citizen Last Modifier 0 to 90 9 Super Senior Citizen Last Modifier In the above table, the first four columns, Age, Gender, FD Deposit Amount, and Term in Days are condition columns. The last three columns, FD Interest, Remarks, Print are action columns. In the Table-based Rule editor, along with the default 3 conditions columns and 1 action column, additionally, 1 condition column and 2 action columns are required. These can be added by right-clicking in the column header, and clicking on Insert Column, for both condition and action columns. Figure 23. Columns added to Table-based rule Next, meaningful column headers are provided. This can be done by double-clicking on the column header, and typing in the new column headers. 24
Figure 24. Meaningful Column headings Next, the conditions for each of the Condition columns have to be defined. This is done using the Define Condition Column dialog which is shown by right-clicking on the column header and selecting Define Column. Please note that, for the first time only, the menu option is Define Column and the dialog is Define Condition Column. For subsequent modifications, the menu option will be Update Column and the dialog will be Update Condition Column. Figure 25. Define Condition Column dialog The Define Condition Column dialog has three sections toolbar at the top, an editing section, and an Errors and Warnings section. The toolbar at the top has Undo, Redo and 25
Completion Menu Options, the functionality of each of these buttons are the same as in Text-based Rule editor. For example, the Condition Column Definition for Age column is the Age of Bank Processes is between <min> and <max>. This has to be understood as if the Age of Bank Processes is between <min> and <max>. Even though, values can be added to <min> and <max> right here, it should be kept in placeholder mode as different ranges for the Age has to be defined in the rows, unless the user wants to specify the values. At least one of the values has to be a placeholder, the value for which has to be defined in the rows. Figure 26. Defining Condition The Condition definitions for the four condition columns are as below. Table 7. Definitions for all the Condition columns Column Condition Age Gender the Age of 'Bank Processes' is between <min> and <max> the Gender of 'Bank Processes' is not null 26
FD Deposit Amount Term In Days and the Gender of 'Bank Processes' is <an object> the FD Deposit Amount of 'Bank Processes' is between <min> and <max> the FD Deposit Term of 'Bank Processes' is between <min> and <max> Similarly, the Action columns are defined. The Define Action Column dialog can be brought up by right-clicking on the header column and selecting Define Column. Here too, the Define Action Column has three sections a toolbar at the top, an editing section in the middle, and Errors and Warnings section below. For example, the Action Column Definition for FD Interest column is set the FD Interest Rate of 'Bank Processes' to <a number>. The <number> is left as a variable to be filled with values in the rows. The Action definitions for the three action columns are as below. Table 8. Actions for all the Action columns Column Action FD Interest set the FD Interest Rate of 'Bank Processes' to <a number> Remarks set the Remarks of 'Bank Processes' to <a string> Print print "Processed by: " + <a string> After the columns are defined, data can be added to the individual cells. The prompting for the data in the individual columns is based on the definition for that particular column. For example, for the Age column, since we have defined it as the Age of 'Bank Processes' is between <min> and <max>, the prompt is two inward closing brackets having two fields, separated by a colon. The two fields are for the minimum and maximum value. 27
Figure 27. Inputting values to cells Clicking on the left bracket brings up a menu which can be used to override the operator of the condition column, in this example, the operator between <min> and <max>. 28
Figure 28. Context menu for condition column input An alternate way of defining the content is by right-clicking in the cell, and selecting Edit Custom Value. This brings up a dialog with the definition section already in place. The values have to be filled in using the Completion Menu. 29
Figure 29. Edit Custom Value dialog Another useful feature is, for condition columns and action columns associated with a string choice list, the user is prompted with a drop down list of the possible values, that is, the value of the string choice list. The same is the case is with Boolean case properties prompting with a drop-down list having true and false values. In this example, the Gender has a choice list having MALE and FEMALE values, and hence the cell has a drop-down list with these values. 30
Figure 30. Drop-down list for properties with choice lists The Table-based rule with all the business requirements is as shown below. Figure 31. Table-based rule with business requirements The blank cells are for conditions and actions which are not applicable. The data in the table-based rule can be validated by clicking on Refresh button in topleft corner. Along with validating the content, the data is sorted, and unwanted rows are removed. 31
Figure 32. Table-based rule after validation The Condition columns have the options of checking for gaps and overlaps. This is enabled by default, and can be disabled through the right-click menu on the condition column header. Figure 33. Gaps and Overlaps in context menu In the example, we have gaps in the Age column, as we have not considered negative values. There are overlaps too. For the Gender column, we have not considered NULL value. 32
Figure 34. Gaps and Overlaps in the Table-based rule After validation, any warnings in the table will be shown with an orange colored corner tag at the bottom left corner of the cell, and any errors will be shown with a red colored corner tag at the top left corner. While the solution can be deployed with warnings in Rules, the errors have to be corrected before deployment. For resolving the overlap warnings, we will include a check for NULL in the condition definition: the Gender of 'Bank Processes' is not null and the Gender of 'Bank Processes' is <an object> Otherwise will be used in condition columns for addressing values which are not satisfying the conditions in the other rows, thereby addressing gaps in the values. Disable will be used in action columns wherever a value cannot be specified due to business conditions. The final table-based rule looks like below. 33
Figure 35. Completed Table-based rule Even though there are overlap warnings for Age, they can be ignored as the overlaps are required as per the business requirements. Table-based rule editor allows checking the conditions and actions as tooltips by hovering the cursor over the column headers. Figure 36. Condition Definition as tooltip By hovering on the row number, the equivalent rule for that particular rule can be seen as a tooltip. 34
Figure 37. Row rule as a tooltip Workflow Definitions and modifications in Process Designer Including a table-based business rule in a task workflow is similar to the way in textbased rules A rule step is added and the table-based rule is picked up from the dropdown menu. Custom parameters, if used, are also mapped to values in Process Designer in the similar manner as was explained for Text-based rules. Conclusion This article described in detail about the features of text-based rule editor and table-based rule editor. It also described the steps for authoring rules by means of an example. Configuring values for Custom Parameters in Process Designer was also discussed. With the integration of IBM Business Rules Embedded SDK in IBM Case Manager, defining and configuring business rules in solutions has greatly improved. 35