Being at the heart of any decision model, OpenRules Glossary uses columns “Variable Name”, “Business Concept”, “Attribute”, and “Type” to define all used decision variables. It is recommended to add the optional column “Description” with plain English descriptions of these variables.

Additionally, OpenRules 8.4.1 Glossary may include optional columns “Used As” and “Default Value” that allow you to effectively control the input and output of the decision model. It can be especially important when your decision model is deployed as a RESTful web service, and you want to validate the incoming JSON structure and decide which variables should be included in the outgoing JSON structure.

Column “Used As”

If your glossary doesn’t include this column, then all (!) decision variables (except of those defined in the Glossary’s formulas) will be included in the output.

The column “Used As” allows you to set certain restrictions on the decision variables using the following properties or their combinations:

• in – defines a variable as the decision model’s input
• required – states that the input variable must have a value
• out – defines the variable as the decision model’s output
• const – defines the variable as a constant.

These properties can be listed in the column “Used As” separated by commas. Below is the description of the most useful combinations of these properties.

The property “required” triggers the validation of the decision variable. If the corresponding variable is undefined, OpenRules will produce an error at the execution time. A variable is considered undefined in the following situations:

• If the variable is defined using standard types such as String, Integer, Double, Boolean, etc. or custom business concepts defined in the glossary or Java, then it is undefined when its value is null
• If a numeric decision variable is defined using Java primitive types such as int, long, or double, then it is undefined if its value is zero.

You may specify the default value for the potentially undefined variable in the column “Default Value” (see below).

The property “out” tells OpenRules that this variable will be calculated within the decision model and should be included in the generated output such as the outgoing JSON structure.

If the cell of the column “Used As” is empty (no properties are defined), then the corresponding decision variable will be treated as a temporary variable that will not be included in the generated output. The column “Used As” may be effectively used for security and performance improvement reasons. Only decision variables that are marked as out will be included in the output of the secure decision service and sent over the network back to the client.

Glossary Column “Default Value”

This optional column lets you define the default values of the decision variables. Look at the sample Glossary below:

The decision variable “Start Date of Service” has type Date and is a required input variable. If its actual input value is null, then the date 1/1/2017 will be used.

The constants MaxAge and MinAge are specified as 120 and 16 and can be used in decision tables as regular decision variables instead of hard-coded numbers.

In this glossary, these constants are not marked as out. Therefore, they both (and as a result, the entire concept “Settings”) will not be included in the outgoing JSON.

Dealing with Formulas

Some decision variables can be calculated inside decision models using Glossary’s formulas instead of attributes. For example, in the above glossary, two last rows have a special indicator “:=” in the column “Business Concept”. It means the values for the proper two decision variables “Age in Years” and “Years of Service” will be calculated by using formulas (Java snippets) specified in the 3^rd column:

These variables will be automatically calculated as the number of years from today until “Date of Birth” and “Start Date of Service” correspondingly.

By default, the values of decision variables defined by formulas are being recalculated whenever these variables are used inside the decision service. However, you can notice that the above glossary specifies “Age in Years” as const in the column “Used As”. It directs OpenRules to calculate the value of the variable “Age in Years” only once at its first read and will never recalculate it again. Sometimes it could save recalculation time and improve the overall performance.

Note that all decision variables defined in the Glossary’s formulas will never be included in the outgoing JSON response as they even do not have associated attribute names.

Context-Specific Columns “Used As”

Sometimes our customers want to treat the same decision variables differently in different contexts. Let’s assume that when the above service is invoked from “Premise” we want its response to show all involved decision variables. However, when it is invoked from “Cloud” we want the response to include only  Employee’s Id and the calculated vacation days and omit all other variables. It can be important for performance and/or security reasons.

To satisfy such requirements, we may introduce two different “Used As” columns, one for “Premise” and another for “Cloud”. We also may add a special decision variable “Invocation Source” with possible values  “Premise” or “Cloud”. Here is the properly adjusted glossary:

You can see, a new decision variable “Invocation Source” belongs to the business concept “Settings” with the default value “Premise”. The column “Used As” has been replaced by two columns: “Used As for Premise” and ”Used As for Cloud”. To direct OpenRules which UsedAs-column to choose, we can use the following decision table with the predefined name “UsedAsSelector”:

Now, OpenRules will dynamically decide which UsedAs-column to use based on the value of the decision variable “Invocation Source”. It will select “Used As for Cloud” if Invocation Source is Cloud and “Used As for Premise” in all other cases.

In this decision table you can use any decision variable instead on “Invocation Source” (or even combinations of decision variables) and use any UsedAs-list specified in the glossary. Only the name of the decision table “UsedAsSelector” is predefined.

The standard workspace “openrules.samples” include the decision project “VacationDaysWithAdvancedUsedAs” that demonstrates how the use of multiple UsedAs-lists.

Sample Decision Model “Loan Origination”

OpenRules provides a workspace “LoanOrigination” that implements a library of decision models for the Loan Origination domain using an example from the DMN Section 11 – you can freely download it from here. Its top-level decision service “LoanOriginationResult” is an AWS Lambda function that invokes two AWS Lambda functions “BureauStrategyService” and “RoutingService” as shown on this automatically generated diagram:

These 3 services share the same quite large Glossary but treat key decision variables differently. For example, “BureauStrategyService” does not need BureauData and defines the variable “Bureau Strategy” as its main output – so this variable should be used as out. Contrary, “RoutingService” needs BureauData, don’t care about “Bureau Strategy”, and uses the decision variable “Routing” as its main output. And finally, the top-level service “LoanOriginationResult” calculates all 3 variables and include them in the output:

• Bureau Strategy
• Routing
• Loan Origination Result.

So, we added 3 different UsedAs lists inside the common Glossary calling the proper columns “UsedAs for PreBureau”, “UsedAs for PostBureau”, and “UsedAs for Result”. To inform OpenRules when to use which column, we added another decision variable “Service Stage” which values “PreBureau”, “PostBureau”, and “Result” can be defined by the contexts that invoke these services. In our test cases, this variable is specified in the file Test.xls. Here is a fragment of the glossary:

The UsedAsSelector for this decision model looks as below:

You may download the glossary, all rules, and test cases from here.

Setting Output Properties

OpenRules allows you to specify some output properties in the the configuration file “project.properties”.  By default, OpenRules does not include variables with null values into the response. It happens because by default the following property is non_null:

jackson.default-property-inclusion=non_null

However, you can define this property with the following values:

• always meaning all variables will be always included in the decision service response independently of their values (of course, unless they are specified as out in the Glossary column “Used As”)
• non_default meaning only variables with non-default values will be included in the decision service response. The default values for numbers are 0, for Booleans – false, and String – “”, and for all other types are null.
• non_empty similar to  non_null but additionally it will ignore empty String variables.

P.S. There is another useful property

jackson.serialization.write_dates_as_timestamps=false

It allows you to change the default way to presentation of dates in the generated JSON files and in the decision service response. Instead of the default Date representation as a number of milliseconds since January 1^st, 1970, by setting this property equal to false you direct OpenRules to use a more user-friendly Date timestamp defined by ISO 8601 such as 2021-08-22T17:05:27+00:00.