Decision Table Structure

Open the example, DT Output Order Example.json, on either the Editor tab on RASON.com or in the RASON IDE. The decision table contained within this example returns the number of holidays apportioned to an employee based on his/her age and number of years in service. This file defines the regions of the decision table as illustrated in the screenshot below. A visual representation of the decision table is shown below.

A decision table is created in RASON using the newly introduced decisionTables RASON section as shown in the example code below, however additional sections such as data, formulas, or dataSource will also be called into play to pass the calculation parameters, get results and import data respectively. According to the rules of the table, a 58 year old employee with 31 years of service is allotted 27 + 3 + 5 vacation days via rules 1, 3 and 6, respectively. However, since the Hit Policy specifies that the results must be returned priority order, the result collection is listed as 27, 5 and 3.

This example code creates the decision table shown above.

{
  modelName: "DTOutputOrderExample", 
  modelDescription: "'O' output order policy example",
  modelType: "calculation",
  data: {
age: { value: 58 },
service: { value: 31 }
},
  decisionTables: {
tblHolidays: {
  hitPolicy: 'outputOrder',
  inputs: ['age', 'service'],
  outputs: ['holidays'],
  refTypes: [‘number’, ‘number’, ‘’],
  outputValues: [27, 5, 3, 2]
  rules: [
		['-', '-', age-service],
		['>=60', '-', 3],
		['-', '>=30', 3],
		['<18', '-', 5],
 		['>=60','-', 5],
		['-', '>=30', 5],
		['[18..60]','[15..30]',	2],
		['[45..60]','<30', 2]
],
default: [1]
   }
},
formulas: {
result: { formula: "tblHolidays(,,age, service)", finalValue: [] }
}
}

modelName

RASON V2020 supports named and unnamed models. A named model includes the modelName: "name" property in its text. "name" must be a string that can be URL encoded and must be unique among models within a user's account. It is strongly recommended that a model be named to allow for easy recognition and retrieval when multiple models, instances and versions exist in a user's account. See the topic "Using the REST API" for more information on named and unnamed models.

modelDescription

This optional high level property offers users the ability to enter a user – defined string containing a description of the RASON model.

modelType

A new optional top-level property "modelType"={"optimization", "simulation", "datamining", "calculation"} has been introduced in RASON Decision Services V2020 for use with decision flows and standalone models. This property defines the model type as optimization, simulation, datamining or calculation within the RASON script. Since this model is a decision table model, the modelType is set to "calculation". For more information on this property, see the next chapter, Using the REST API.

data

The data section passes the parameters required to evaluate, or calculate, the decision table: age (58) and service (31). Note: Decision tables only accept scalar (constant) arguments as inputs. (No components of a decision table can be bound to an external database.)

decisionTables

In RASON, tables are defined as objects in the newly introduced section decisionTables: { }. Each table component is defined as a component with a scalar or array value assigned to it.

The steps required to create the decision table above are listed below.

Step 1:

Enter a unique Name to define the table and create the decision table object. In this example, the table name is specified as tblHolidays.

Step 2:

Enter a Hit Policy.

hitPolicy: 'outputOrder'

Specifies how the table will be evaluated when multiple rules are applicable and hence, multiple output values are returned.

The Hit Policy value identifies the supported policies by a capital letter and an operator, when applicable. You may enter the 1st letter of the policy or the whole word. The currently supported Hit types and their meanings are:

Unique (U): A unique rule must be successful, or "hit", evaluating to a unique result. If multiple rules are "hit", an error will be returned.

Any (A): If rules overlap, but point to the same result, that unique result is returned.

Priority(P): If multiple rules are "hit" and multiple results collected, the result with the highest priority is returned. Priorities are defined by their order in the outputValues component (see below).

First (F): Only 1 result is returned for this policy. Once a rule is evaluated successfully, or a hit occurs, the search stops.

Rule Order (R) - If multiple rules are hit, the collection of results is returned according to the rule order, as specified in outputValues.

Output Order (O) – If multiple rules are hit, return the collection of results in the priority order as listed for outputValues.

Collect (C) – The same as (R). However, we may make this policy more specific by adding an operator to it in order to allow aggregation.

Note: If aggregating a date, a scalar is returned. If using an operator, output must not be a string, but only a numerical value.

C+ - sum the matched output values

C< - return the min of matched output values

C> - return the max of matched output values

C# - return the number of matched output values

Step 3:

Enter Input Parameters.

inputs: ['age', 'service']

Two headers are contained in the table above, age and service. These are the input components, or the input data that will be passed to the decision table during calculation.

Step 4:

(Optional) Enter Data Types using refTypes.

refTypes: [‘number’, ‘number’, ‘’],

The component refType describes the data type for each input. When defining refTypes, all input and output columns must be included. It's possible to enter empty strings or null for any input or output column. This example uses the refTypes component to stipulate that the age and service input parameters will be of type "number" and passes an empty string to the output parameter. The output parameter's domain is defined using the outputValues component (see below.)

Data Types

Boolean: The entered words TRUE and FALSE are interpreted as Boolean reserved words, not strings.

Number: May be an integer or fraction.

Text: Any string

Date: Any valid date, such as 05-05-1964

Time: Any valid time

Duration: There are two formats for duration, one measuring periods in months and another measuring periods in seconds. For example, P1DT1H2M3S denotes:

• P for "period"
• 1D for 1 day
• T for "time"
• 1H for 1 hour
• 2M for 2 minutes
• 3S for 3 seconds

Step 5:

Optional: Enter Input Values using inputValues.

The component inputValues describes the domain covered by all input entries in the decision table rules (see below). Each input value must relate to a given input parameter. Input Values may be a list of values separated by commas (i.e. 27, 5, 3, 2), a list of unary tests (i.e. <10, >=20, [18..20]), or a data type (i.e. boolean, number, text, data, time and duration).

Both refValues and inputValues/outputValues may exist within the same RASON model but inputValues will override the refValues component. Use refValues when stipulating the value type accepted by the column and input/outputValues when stipulating the domain of the column.

When testing a value against a list of values or unary tests, the OR operator is used. A list of values is evaluated as 27 OR 5 OR 3 OR 2. Likewise, the list of unary tests is evaluated as <10 OR >=20. It's possible to negate a list as well. For example, NOT(27, 5, 3, 2) would result in a selection of a record that does not includes 27 OR 5 OR 3 OR 2. Similarly, NOT(<10, >=20) would equate to neither <10 OR >=20 being selected.

All input entries in the relevant input column should cover the entered domain, otherwise, an error will be generated indicating that the table is not complete. If an input value does not exist, the completeness test is not performed.

Step 6:

Enter Output Parameters

outputs: ['holidays']

In this example, holidays is the output parameters. After calculation, a decision table returns a few selected or all output parameter values in the form of an array. If a decision table has a single output or a single output has been selected, the result will be a scalar value. These input parameters belong to the local scope of this table.

Step 7:

(Optional) Enter the Output Values

outputValues: [27, 5, 3, 2]

An output value may be a list of values separated by commas (i.e. 27, 5, 3, 2) listing the priority of returned results. If a value appears in the table that does not match the output value, an error will be returned.

In this example, the list "27, 5,3,2" is entered beneath "holidays" and "text" is entered beneath "rule". The Output Values list (27, 5, 3, 2) specifies the priority when returning the results. In other words, the results are to be returned largest to smallest.

Both refValues and outputValues may exist within the same RASON model but outputValues will override the refValues component. Use refValues when stipulating the value type accepted by the column and input/outputValues when stipulating the domain of the column.

All output entries in the relevant output column should cover the entered domain, otherwise, an error will be generated indicating that the table is not complete. If an output value does not exist, the completeness test is not performed.

Step 8:

Enter the Decision Table Rules (or Unary tests).

rules: [
		['-', '-', 22],
		['>=60', '-', 3],
		['-', '>=30', 3],
		['<18', '-', 5],
 		['>=60','-', 5],
		['-', '>=30', 5],
		['[18..60]','[15..30]',	2],
		['[45..60]','<30', 2]
],

Rules consists of Input Entries and Output Entries. These entries consist of unary tests which return information (true or false) about the rule. Supported unary tests may have one of the following syntax forms: value(Boolean, number, text, date, time, duration), < value, > value, <= value, >= value, [value..value], (value..value], [value..value), (value..value), "-". Note: Currently, rules may only be entered as rows.

The first test examines whether the value being tested is equal to the value inside the parenthesis. For example, if the Unary test consists of the single value 'medium', the resulting test would ensure that the variable being tested was equal to 'medium'. The forms, [value..value], (value..value], [value..value) and (value..value), are interval tests. The [ ] operators denote a closed interval while the ( ) operators denote an open interval. The last test, "-" returns TRUE against any value.

Step 9:

(Optional) Define a default result.

default: [1]

There are two ways to return a default value for a decision table.

1. Simply use "-" for all unary tests.
2. Use the default component as shown in the example above.

In this example a default of "1" holiday is returned if no tests are successful.

Expressions

Variables and constants can be combined through operations called literal expressions. Literal expressions in S-FEEL are similar to formulas in Excel and in the RASON modeling language.

The following operators are supported in combination with decision table rules: addition (+), subtraction (-), multiplication (*), division (/) and exponentiation (**). Variables and constants can be combined using only these supported operators and parentheses. An example of an expression is: 2 * age – service where two variables, age and service and a constant, 2, are linked by two arithmetic operations (* and -). Note that an expression is a FEEL expression, NOT an Excel formula. In this example, the expression "age – service" appears in the first rule where "age" and "service" refer to 58 and 31, respectively, as defined in the data section. This expression does not refer to any appearances of "age" or "service" outside of the scope of this table. For more information on supported conversion expressions, please see Decision Tables in the RASON Reference Guide.

See the Decision Table Containing Duration section below for an illustration on using expressions within decision table rules. For a complete list of supported operators, see the Decisions Table section within the Rason Reference Guide.

formulas

Use the formulas section to obtain the final results from a decision table. The complete signature of the decision table function is:

"tblDecTable(,[string ret_output], [bool ret_header], variant Input1, variant Input2, …, variant InputN)"

where:

• The first argument [string ret_output] is an optional argument that, when passed, returns only the desired columns in the output.
• The second argument [bool ret_header] is an optional argument that, when True, returns the column headings in the output.
• The third and remaining arguments pass the input parameters to the decision table.

In this example, we are passing the parameters age and service (defined within the data section) to the decision table, tblHolidays. In return, we are asking for the finalValue, the result, from the table. Notice the two placeholders for ret_output and ret_header.

formulas: {
	result: { formula: "tblHolidays(,,age, service)", finalValue: [] }
	}
}

Output

As with optimization, simulation and data science models written in the Rason modeling language, RASON Decision Table models can be ran by calling the RASON REST server by using the Editor page on the website www.rason.com or by using the RASON REST API from within your own application. As with optimization, simulation and data science, no matter how you solve the model, the result will always be valid JSON. See the topic, Solving RASON Models, for step by step instructions on how to solve a decision table in RASON.

If solving on the Editor page on www.rason.com, click POST rason.net/api/model to POST the model and POST rason.net/api/model/{nameorid}/decision to calculate the table. According to the rules of the table, a 58 year old employee with 31 years of service is allotted 27 + 3 + 5 vacation days via rules 1, 3 and 6, respectively. However, since the Hit Policy specifies that the results must be returned in priority order, the result collection is listed as 27, 5 and 3.

{
  "status": {
    "code": 0,
    "id": "2590+DTOutputOrderExample+2020-02-25-19-16-35-647046",
    "codeText": "Solver has completed the calculation."
  },
  "observations": {
    "res": {
      "value": [27, 5, 3]
    }
  }
}

Optional Arguments

To return the result for a given output only, pass the output heading in quotes. For example, to only receive the number of holidays, rather than both holidays and the rule, add "holidays" as the second argument to the existing formula:

{
result: { formula: "tblHolidays('holidays',,age, service)", finalValue: [] }
}

In this instance, only the result collection for "holidays" will be returned, 27, 5, 3.

You can pass as many output arguments as needed.

A 2nd optional argument, ret_header, is a Boolean argument, that, if True, returns a header for the result collection.

{
result: { formula: "tblHolidays('holidays', True, age, service)", finalValue: [] }
}

In this instance, the result collection will include only the "holidays" output parameter with the header "holidays" as the first element in the collection: "holidays", 27, 5, 3.

To only include the optional ret_header argument and not both optional arguments, use:

{
result: { formula: "tblHolidays(,True, age, service)", finalValue: [] }
}