Using the Decision Table Operator

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 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, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Enable Error Output Port: Select this check box 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.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow 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.

Loading from an Artifact Management Server or loading from a local file system is mutually exclusive.

Loading Decision Table Files From an Artifact Management Server

Load from AMS: Select the check box to indicate whether the decision table's rules should be loaded from a TIBCO Artifact Management Server (AMS).

Note

For more information about AMS, refer to TIBCO Artifact Management Server user documentation.

Field Name Field Description
Host Name AMS host name.
Port Number AMS port number.
Secure Channel Check to enable SSL.
Username AMS username.
Password AMS user's password. Can be enciphered using the sbcipher utility.
Project Name Project folder in AMS where the decision table is located.
Decision Table Path Path in AMS where the decision table is located.
Decision Table Version Specify this value if you want to load a specific decision table version from the AMS, or leave it empty to load the latest artifact version.

Loading Decision Table Files Locally

Decision Table File: 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 Decision Table File link, Studio opens the New StreamBase Decision Table wizard to help you create a new 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 successfully edit a decision table in Excel, you must have Excel 2007 or later on the same machine as Studio, and you must have the TIBCO 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 Decision Table File 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 Decision Table File 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 resource search path. Only files with the three extensions described above are shown.

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.
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
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's a matching rule or not. 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 will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL. 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. 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.

    • UploadRules — Uploads the decision table specified in the decisiontable field. This is an impractical method of uploading a decision table file, except for experts.

    • 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 TIBCO 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.
    filename 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.
    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 operator with the UploadRules 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 Application Output view.

    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.