Using the Decision Table Operator

< Previous		Next >

Introduction

Decision tables provide a way to express a complex set of business rules as a table of conditions that apply to incoming tuple fields, with one or more specified actions for each row of conditions. By default, all rows of the table are evaluated against each incoming tuple, with an option to stop evaluation at the first matching row.

Each row can be thought of as a single rule in a table made up of many rules. The individual rules are often straightforward. When built into an EventFlow application, the Decision Table operator allows you to author, test, and publish decision tables.

The Decision Table operator processes tuples on its input port. For each tuple, it evaluates the conditions of the currently loaded rules, and emits an action tuple for each matching rule. A rule matches if all its conditions evaluate to true in the context of the input tuple. If the operator's Single Row Execution property is selected, a single tuple is emitted for the first matching rule.

Emitted tuples contain a copy of the input tuple, an action tuple derived from the rule's action columns, and a copy of the matching rules. Rules can be assigned priorities to determine which rule fires when the conditions of multiple rules match the input tuple.

For further information about decision tables in general, see Using Decision Tables.

Properties: General Tab

Name: Use this required field to specify or change the name of this instance of this component. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. The first character must be alphabetic or an underscore.

Enable Error Output Port: Select this checkbox to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Operator: A read-only field that shows the formal name of the operator.

Class name: Shows the fully qualified class name that implements the functionality of this adapter. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this adapter starts.

Description: Optionally, enter text to briefly describe the purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Decision Table Settings Tab

Use the Decision Table Settings tab to specify the decision table file to load, and, if available, the domain model file to load, when this decision table operator starts. This table also configures the operator's logging level, and provides a schema grid in which to set the schema of the action tuple emitted as part of the operator's output tuple.

Note

On the Decision Table Settings tab, at least one of a Default Decision Table or a ModelOps Decision Table must be specified. You can specify both the tables simultaneously. A ModelOps Decision Table is set using the ModelOps Project Name and ModelOps Decision Table Path fields.

Loading Decision Table Files From ModelOps

Field	Description
Required On Startup	When specified as `true`, the artifacts listed are requested from ModelOps at initialization and the system waits until all artifacts are loaded. Setting the field as blank is the equivalent to the field's default value of `false`. Case-insensitive.
ModelOps Project Name	Project folder in ModelOps where the decision table is located.
ModelOps Decision Table Path	Path in ModelOps where the decision table is located. File extensions are not needed, except when pulling a decision table in Excel file format from ModelOps using the Artifact Distribution Service.

Loading Decision Table Files Locally

Default Decision Table: Use this property to specify or select a decision table file that this operator loads at startup. The operator can load only one decision table at a time. There are several cases for using this control:

If the file name field is empty, and you click the Default Decision Table link, Studio opens the New StreamBase Decision Table wizard to help you create a file. Select the project name, enter the name for your decision table file, and select the type of file:
- On Windows or on a Mac, you can select the .sbdt file type. In this case, clicking Finish opens the Decision Table Editor in Studio that allows you to create a decision table, row by row, then save it to the file name you specified.
- On Windows only, you can select the .xlsx or .xls file type. In this case, clicking Finish attempts to open Microsoft Excel. To edit a decision table in Excel, you must have Excel 2007 or later on the same machine as Studio, and you must have the StreamBase® Add-in for Microsoft Excel, version 2.5.1 or later, installed as an Excel add-in.
If the file name field contains the name of a file with .sbdt, .xlsx, or .xls extension, and you click the Default Decision Table link, Studio attempts to open the appropriate editor for either file type to edit the specified file.
If the file name field contains the name of a file with .rulefunctionimpl extension that was saved from TIBCO BusinessEvents®, the operator accepts the file as a valid decision table file. However, Studio provides no way to edit such files, so clicking the Default Decision Table link attempts to open the file in a plain text editor.
Finally, you can click the Choose button to select an existing decision table file in this project's source/main/resources folder. Only files with the three extensions described above are shown.

Default Decision Table Version: Use this property to assign a version to the Default Decision Table. This property is optional. If not specified, a version with DEFAULT-<path_with_underscores>-<checksum> form is generated.

Default Decision Table Encoding: If the Default Decision Table is Base64 encoded then the BASE64 option must

be specified in this enumeration field.

Domain Model File: Use this property to specify a domain model, which allows you to restrict the set of values that can be placed in a condition or action cell. See domain models.

Summary of Decision Table File Types

The Decision Table File property can make use of three decision table file types with four different origins, as shown in the following table:

File Type	Extension	Origin
StreamBase format decision table	.sbdt	Edited in and saved from the Decision Table Editor in StreamBase Studio.
Excel format decision table	.xlsx, .xls	Edited in and saved from Microsoft Excel on Windows with the StreamBase Excel Add-in installed.
Excel format decision table	.xlsx, .xls	Edited in and saved from Microsoft Excel on Windows, or imported from BusinessEvents WebStudio to StreamBase Studio.
TIBCO BusinessEvents native decision table format	.rulefunctionimpl	Edited in and saved from TIBCO BusinessEvents®. StreamBase Studio can import these files, but cannot edit them.

Additional Properties

The Decision Table operator includes the following additional properties:

Property	Description	Default
Required On Startup	If the option is checked, then startup fails if the operator's decision table cannot be loaded	Unchecked
Emit Non-Matching Tuples	If the option is checked and no matching decision table rules fire, a tuple is emitted. If this option is not selected, no non-matching tuple is emitted. One use case is to avoid breaking the tuple flow across the operator. That is, they want a tuple to flow through the Decision Table operator whether there is a matching rule or not.	Unchecked
Exclude Rule From Output Tuple	When checked, the rule field no longer appears in the operator's output schema.	Unchecked
Exclude Input Tuple From Output Tuple	When checked, the Decision Table operator does not add an in output field with the same schema as the input tuple, and does not copy any input to the output. This is meant to be used for performance reasons (avoiding copies).	Unchecked
Enable Control Port	If the option is checked, then the Control port is added to the Java Decision Table operator in the EventFlow module. If the option is checked then in the EventFlow an input stream with the Control Port's schema should be connected to the Control port. The Control Port's schema can be imported into the EventFlow using the Import proposed schema's ... link that is on the right-hand side of the operator's StreamBase Properties tab.	Unchecked
Enable Status Port	If the option is checked, then the Status port is added to the Java Decision Table operator in the EventFlow module.	Unchecked
Log Level	Controls the level of verbosity the operator uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.	INFO

Properties: Action Schema Tab

Action Schema: Use this property to configure the schema of the action tuple emitted as one of the fields of the operator's outgoing tuple. The action tuple must contain one field to match each action column in your decision table. Action schema fields not present in the decision table get populated with nulls.

Properties: Concurrency Tab

Use the Concurrency tab to specify the use of parallel regions for this instance of this component. Consider selecting the parallel regions check box if this component instance is long-running or compute-intensive, can run without data dependencies on other StreamBase components, and would not cause the containing module to block while waiting for a thread to return. In this case, you may be able to improve performance by selecting this option. This option directs StreamBase Server to process this component concurrently with other processing in the application. The operating systems supported by StreamBase automatically distribute the processing of threads across multiple processors.

Caution

The parallel regions setting is not suitable for every application, and using this setting requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Ports and Streams

The Decision Table operator has the following ports:

One input port, also called the condition port, that accepts the stream of incoming tuples, whose schema is defined by upstream operators. When using non-custom Condition columns, the names of fields in the incoming stream become the names of Condition columns.

One output port, also called the action port, whose schema consists of three fields of type tuple, as shown in the following table:

Field Name	Field Type	Field Description
in	tuple	The `in` tuple's schema is the same as the incoming tuple.
action	tuple	You define the `action` tuple's schema in the Decision Table Settings tab of the operator's Properties view. There must be one `action` tuple field for each Action column in the decision table.
rule	tuple	The `rule` tuple's schema is a complex format not documented here. This tuple contains a record of the row-by-row decisions made by the operator for each incoming tuple, including a list of tuples for each conditionValue, and another list of tuples for each actionValue.

In addition to standard ports, the operator exposes the following streams when the operator is running. The CanvasName component of both stream names is the case-sensitive name of the operator on the EventFlow Editor's canvas. Thus, for an operator named DT1, you would have streams DT1.Control and DT1.Status.

Control stream named CanvasName.Control. This is an input stream that can be used to send commands to a running operator to load or reload a decision table file after the operator has started. This port can be enabled/disabled with the properties mentioned in Additional Properties. If this port are enabled, then the EventFlow module containing the DT operator must be updated to connect streams to this port. The operator's Import proposed schemas... link can be used to import the DecisionTableControlSchema schema required by the Control stream.

The schema for the Control stream is shown in the following table:

Field Name	Field Type	Field Description
command	string	Accepts one of the following string values, which can be entered without regard to case: `LoadRuleFile`—Loads a decision table file into this running operator, replacing the decision table in current use. The decision table file to be loaded must have Column names compatible with the incoming input stream. If the filename property specifies the name of a decision table file from the operator's resource search path in `.sbdt`, `.xlsx`, or `.rulefunctionimpl` formats, then the specified file is loaded, if it can be. If the filename property is blank, the currently loaded file is reloaded from its original location. When using this command, all other fields are ignored. `ValidateRules`—Validates the decision table specified in the decisionTable field `DownloadRules`—Emits a tuple on the operator's status port containing the entire decision table from the running operator. This is intended for use mainly by the StreamBase® Add-In for Microsoft Excel. `ClearRules`—Clears the current decision table from the running operator.
tag	string	An arbitrary string to identify output tuples that use a newly loaded decision table. The tag field is shown in the Status stream.
modelOpsProjectName	string	In ModelOps, the project folder name under which the decision table to be deployed is located.
modelOpsDecisionTablePath	string	In ModelOps, the project directory path for the decision table to be deployed.
defaultDecisionTablePath	string	Used with the `LoadRuleFile` command to specify a decision table file in the current project's resource search path to upload to a running operator.
defaultDecisionTableVersion	string	Used to assign a version to a decision table.
decisionTable	tuple	This field is a tuple with a very complex schema not documented here. You can see the schema in the Manual Input view while the operator is running. The tuple specifies all rows of an entire decision table, field by field, for uploading to the running decision table EventFlow module with the `ValidateRules` command. This feature is of primary interest to decision table experts.
decisionTableContents	string	This field contains the entire contents of a decision table file expressed as a single string in the manner of the `rule` field of the output tuple. Using this field is only of value to decision table experts.

Status stream named CanvasName.Status. This is an output stream that emits one tuple for each command sent on the Control stream, as described above, to report the success or failure of the command. When the Decision Table operator is running in Studio, you can see the tuples of the Status stream in the Output Streams view. This port can be enabled/disabled with the properties mentioned in Additional Properties. If this port are enabled, then the EventFlow module containing the DT operator must be updated to connect streams to this port.

The Status stream's schema is shown in the following table:

Field Name	Field Type	Field Description
command	string	Shows the command string sent on the Control port's command field.
tag	string	Shows the tag string sent on the Control port's tag field.
status	bool	Reports true for a successful command or false otherwise.
message	string	Contains a human readable message that reports the number of rules loaded for a successful command, or the reason for the failure for an unsuccessful command.
domainModelInfo	list(tuple)	This field contains a list of tuples, with each tuple describing one element of a domain model in use, if any.
decisionTable	tuple	This field contains the entire contents of the decision table successfully uploaded with the UploadRules command. The decision table is expressed as a tuple with a very complex schema not documented here. This information is expected to be of value only to decision table experts.