- Index

< Previous |  | Next >

# 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 component's name, which must be unique in the current 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.

### Note

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

Field | Description
--- | ---
Load from AMS | Loads a decision table from a TIBCO Artifact Management Server (AMS), which is a separately installed product.
Load from ADS | Loads a decision table from AMS using the artifact distribution service (ADS). If you select this option, the next five fields are grayed out and not required. If you are deploying a decision table from AMS using the `StreamBase Service Name Target Type` option, you must enable ADS here.
Host Name | AMS host name.
Port Number | AMS port number.
Secure Channel | Check to enable an SSL channel to AMS.
Username | AMS username. The user must already exist in the AMS configuration.
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. File extensions are not needed, except when pulling an Excel file from AMS using the Artifact Distribution Service.
Decision Table Version | Enter a string value to load a specific decision table version from AMS, or leave it empty to load the latest 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 `source/main/resources` folder. 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. | 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` — Downloads the entire decision table from the running operator. If the operator is running a decision table loaded from a file in the current project's resource search path, the running decision table is downloaded into and overwriting that file name. This allows you edit the same decision table for those uploaded in `.sbdt` or `.xlsx` formats, using the same editor used to create the file. `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.
  loadFromAMS | bool | Used to permit an Artifact Management Server to push a decision table to the running decision table EventFlow module.
  hostName | string | AMS server hostname
  portNumber | int | AMS server port number
  secureChannel | bool | AMS channel
  username | string | Name of the AMS user with privileges to deploy a decision table's rules from AMS to a running decision table EventFlow module.
  password | string | Password of the AMS user deploying a decision table's rules.
  projectName | string | In AMS, project folder name under which the decision table to be deployed is located.
  decisionTablePath | string | In AMS, project directory path for the decision table to be deployed.
  decisionTableVersion | int | Decision table file version number (currently not supported in AMS).
  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 decision table EventFlow module 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 Output Streams 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.

## Related Topics

- StreamBase Expression Language Functions

- Using Decision Tables

- Studio Preference Settings

Back to Top ^