LiveView Alert Configuring Output Adapter

Contents

Introduction
Properties
Using the Adapter in a StreamBase Application
Typechecking and Error Handling
Suspend and Resume Behavior

Introduction

The Spotfire LiveView Alert Configuring Output Adapter allows a StreamBase application to list, create, modify, and remove alerts from LiveView servers.

Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view for the adapter's icon in StreamBase Studio.

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.

Adapter: A read-only field that shows the formal name of the adapter.

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.

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.

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.

Adapter Properties Tab

This section describes the properties on the Adapter Properties tab in the Properties view for the LiveView Alert Configuration adapter.

Property Description
Set Server URI to encapsulating LiveView Select this checkbox when the adapter is part of a LiveView project. In this case, the adapter connects to the port of the running LiveView server. When authentication is enabled, the credentials used to connect to the LiveView server are retrieved from the liveview.internal.username and liveview.internal.password system properties. The corresponding LiveView user must be configured with the appropriate permissions to allow this adapter to perform its operations.
LiveView Server URI A LiveView server URI, or an expression or variable that resolves to a LiveView server URI. For example, the URI for the local machine and default port is lv://localhost:11080.
Use Runtime URIs Enables an additional input port to this adapter. The input port expects tuples of the schema (ControlAction: string, URI: string). The author time URI options are greyed out and the adapter will wait to connect until it receives a Connect tuple. If the connection fails, the adapters will continue to try and connect. If the adapter receives a Disconnect tuple, it will disconnect from its current connection, if it has one, or stop trying to connect if it’s currently in failure.
Connection Key Only enabled if Use Runtime URIs and Share LiveView Connection are enabled. If both are enabled, this is a required property which defines groups of adapters that will share connections. An author-defined string of alphanumeric characters is expected here like Pool1 or Pool2. All adapters set to share connections and use runtime URIs with the Connection Key Pool1 will connect and disconnect using a single shared connection as Connect/Disconnect tuples are received by any one of the adapters in the group.
Share LiveView Connection When selected (the default), this instance of the adapter shares a single LiveView connection to the configured LiveView server with all other LiveView adapters in the same container that also have the Share LiveView Connection property selected.
Enable Compressed Connection If checked, compress this adapter's LiveView connection. Not enabled if Use Runtime URI is also selected. To compress a connection defined at runtime, see the "ConnectCompress" control action defined in the Runtime URI Schema
Connect Inline If the adapter is not currently connected to the configuration LiveView server, a new attempt is made when a command tuple arrives. When not connected the adapter periodically tries to connect to the server, so Connect InLine is simply a means of forcing an immediate attempt.
Log Level Controls the level of verbosity the adapter 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.

Cluster Aware Tab

Use the settings in this tab to enable this operator or adapter for runtime start and stop conditions in a multi-node cluster. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Using the Adapter in a StreamBase Application

The LiveView Alert Configuration adapter provides one input port and two output ports. It also provides an optional Use Runtime URI control input port.

  • The main input port sends commands and configuration information to the adapter to list, create, update, or delete alerts.

  • The optional Use Runtime URI port receives Connect/Disconnect tuples along with URIs to connect to.

  • The Status output port emits tuples that provide information about each command, and the status of the connection to the configured LiveView server.

  • The other output port provides alert configuration information, such as when listing alerts.

As with Spotfire Streaming adapters and operators, you can optionally enable an Error Output Port, as described in Using Error Ports and Error Streams.

Each successful input tuple command results in an output tuple from the result output port. For get, create, and update commands, the output AlertRuleList will have the resulting AlertRule tuples. If a command is unsuccessful the Status port emits a tuple with information regarding the failure.

LiveView Alert Configuration Adapter Input Port

The input port requires two fields be defined. The first is a string Command field and the second is a tuple field that contains all the Alert configuration information.

Field Data Type Description
Command string The table command to run which must be one of the following strings:
getalertrules—Requests one or more alert rules. These are send to the output port one alert at a time. updatealertrule—Requests an existing alert rule be updated. Non-null fields in the AlertRule tuple will be updated.
createalertrule—Requests an alert rule be created. The AlertRule tuple field must have the configuration information. deletealertrule—Requests an existing alert rule be deleted.
AlertRule tuple A tuple that contains all the alert rule configuration information.

The adapter can import a proposed schema for the input port that you can use as a starting point.

To import an input schema, click the Import proposed schemas hyperlink in the top right corner above the Adapter Properties tab. From the dialog, click Browse to select an existing destination interface file, or click New File to save a Named schema file to a project folder.

The AlertRule tuple has all the Alert configuration information. The tuple fields are defined in the table below. Note that for updatealertrule only non-null fields are updated.

Field Data Type Description
AlertID string AlertID is used to identify a specific alert you wish to delete, update, or get. AlertID is ignored when creating an alert as the server generates the AlertID.
AlertName string The name of the alert.
AlertGroup string The alert group.
User string For getalertrules return alerts for this user name. For createalertrule and updatealertrule use this user name if auth is not enabled.
StatusMessage string Set by the server to indicate the current status of an alert. A string of OK means the alert is good.
QueryConfig tuple The QueryConfig to use with this alert see QueryConfigSchema below.
CronString string A Quartz Scheduler cron string.
Description string The description of the alert.
Message string The message that will be used for the alert.
Severity int The severity of the alert—a somewhat arbitrary number.
Quiescence int The amount of time in milliseconds to ignore conditions after the alert has triggered.
IsEnabled boolean Indicates if the entire alert is enabled or not.
Created timestamp The creation time of the alert. Set only by the server.
LastUpdated timestamp The last updated time of the alert. Set only by the server.
IsValid boolean Set by the server to indicate if an alert is valid or not.
AlertActionPublish list A list of AlertActionPublishSchema tuples the define the publish actions for the alert.
AlertActionJava list A list of AlertActionJavaSchema tuples the define the Exec Java actions for the alert.
AlertActionOS list A list of AlertActionOSSchema tuples the define the Exec OS actions for the alert.
AlertActionDelete list A list of AlertActionDeleteSchema tuples the define the Delete actions for the alert.
AlertActionLvPublish list A list of AlertActionLVPublishSchema tuples the define the LiveView publish actions for the alert.
AlertActionEmail list A list of AlertActionEmailSchema tuples the define the email actions for the alert.
AlertActionSendTuple list A list of AlertActionSendTupleSchema tuples the define the publish actions for the alert.
AlertActionInvokeHTTP list A list of AlertActionInvokeHTTPSchema tuples the define the invoke HTTP actions for the alert.

The QueryConfigSchema tuple has QueryConfig settings for the alert.

Field Data Type Description
Predicate string The simple predicate used to trigger the alert.
Projection string Used for aggregate alert expressions.
TableName string The table name the predicate applies to.
QueryType string One of snapshot, snapshot_and_continuous, or continuous. Continuous is the default.

The AlertActionPublishSchema tuple configures the Alert action.

Field Data Type Description
Description string The description of what this action is for.
IsEnabled string True if the action is enabled, false if the action disabled.
MessageTemplate string Sets the value of the actions messageTemplate.
AlertKey string The primary key value that will be used in the LVAlerts table. A null value result in a unique key generated on the server for each Alert publish action.
Recipient string The value used in the LVAlert Recipient field.

The AlertActionJavaSchema tuple configures the Alert Exec Java action.

Field Data Type Description
Description string The description of what this action is for.
IsEnabled string True if the action is enabled, false if the action disabled.
ClassName string The name of the Java class to execute. This class must implement the ExecJavaAction interface.
Params list A list of AlertParamSchema tuples. Used to supplied parameters to the implementing ExecJavaAction class.

The AlertActionOSSchema tuple configures the Alert run OS command action.

Field Data Type Description
Description string The description of what this action is for.
IsEnabled string True if the action is enabled, false if the action disabled.
Command string The command string to execute.

The AlertActionDeleteSchema tuple configures the Alert Delete Query action.

Field Data Type Description
Description string The description of what this action is for.
IsEnabled string True if the action is enabled, false if the action disabled.
TableName string The name of the table to issue the delete query on.
Predicate string The predicate to use for the delete.

The AlertActionLVPublishSchema tuple configures the Alert LiveView Publish action.

Field Data Type Description
Description string The description of what this action is for.
IsEnabled string True if the action is enabled, false if the action disabled.
LVURI string The LiveView URI to publish to.
TableName string The name of the table to publish to.
Substitutions list A list of AlertParamSchema tuples. Used to supplied field value substitutions for the published LiveView tuple.

The AlertActionEmailSchema tuple configures the Alert Email action.

Field Data Type Description
Description string The description of what this action is for.
IsEnabled string True if the action is enabled, false if the action disabled.
To list A string list of email addresses to send to.
CC list A string list of email addresses to send carbon copy.
BCC list A string list of email addresses to send blind carbon copy.
Subject string The subject of the email.
Body string The body of the email.

The AlertActionSendTupleSchema tuple configures the Alert Send Tuple action.

Field Data Type Description
Description string The description of what this action is for
IsEnabled bool True if the action is enabled, false if the action disabled.
SBURI string Sets the value of the actions messageTemplate
InputStream string The primary key value that will be used in the LVAlerts table. A null value result in a unique key generated on the server for each Alert publish action.
Substitutions list A list of AlertParamSchema tuples. Used to supplied field value substitutions for the tuple being sent.

The AlertActionInvokeHTTPSchema tuple configures the Alert Invoke HTTP action.

Field Data Type Description
Description string The description of what this action is for
IsEnabled bool True if the action is enabled, false if the action disabled.
URL string The URL to where the request is sent.
Method string Request type. Must be one of the supported types: GET, POST, PUT, PATCH, DELETE.
Header list An optional list of AlertParamSchema tuples. Used to set HTTP request header information.
QueryParameters list An optional list of AlertParamSchema tuples. Used to set HTTP query strings that carry identifying information.
Body string An optional string that defines content that should be sent to the receiver.

The AlertParamSchema tuple provides key value pairs for parameter substitutions

Field Data Type Description
ParamName string The name of the parameter
ParamValue string The value of the parameter

Runtime URI Input Port

When Use Runtime URIs is enabled on this adapter, so is this port.

This port accepts tuples of the below schema.

Field Data Type Description
ControlAction string A value of either
Connect ConnectCompress Disconnect
If Connect or ConnectCompress, the adapter (and any adapters with whom it shares a connection) will connect to the LiveView server specified in the URI field. If currently connected (or attempting to connect) to a URL, that will be closed and the new URL attempted. If Disconnect, this adapter or adapter group will disconnect from its currently connected LiveView server. ConnectCompress will initiate a compressed connection, and Connect will initiate an uncompressed connection.
URI string The URI of a LiveView server such as lv://localhost:11080. The adapter will attempt to connect to the LiveView server at this address if Connect or ConnectCompress is supplied in this tuple's ControlAction. If Disconnect is supplied as the ControlAction, a value for URI need not be supplied and will be ignored.

LiveView Alert Configuration Adapter Output Ports

The LiveView Alert Configuration adapter has two output ports—one output status port and one AlertOut port.

The status port reports connection issues with the LiveView server and problems that may arise from alert configuration commands.

  • A CONNECTION message shows the success or failure of the connection to the LiveView server.

  • For failing Alert commands, an ALERT* message shows FAILED or ERROR it its Action field, with an explanatory note in the Message field.

The status port uses the fields shown in the following table:

Field Data Type Description
Type string The basic state reported, always one of the following:
CONNECTION ALERT_LIST
ERROR ALERT_DELETE
ALERT_SET ALERT
Object string The name on the EventFlow canvas of the adapter reporting the status.
Action string The action that occurred, one of the following:
CONNECTED ERROR
FAILED  
Message string A human-readable string that provides additional context for the status message.
Time timestamp The time the publish request or error occurred.

The Alert output port has the Command sent by the input tuple and a list of AlertRuleSchema tuples.

Field Data Type Description
Command string The table command to run which must be one of the following strings:
getalertrules—Requests one or more alert rules. These are send to the output port one alert at a time. updatealertrule—Requests an existing alert rule be updated. Non-null fields in the AlertRule tuple will be updated.
createalertrule—Requests an alert rule be created. The AlertRule tuple field must have the configuration information. deletealertrule—Requests an existing alert rule be deleted.
AlertRule tuple A tuple that contains all the alert rule configuration information.

Adding the Adapter to an EventFlow Application

Add an instance of the adapter to a new EventFlow application with the following steps:

  1. In StreamBase Studio, create a project, including an empty StreamBase EventFlow application file to host the adapter.

  2. From the Operators and Adapters drawer of the Palette view, drag the Adapters, Java Operators icon to the canvas. This opens the Insert an Operator or Adapter dialog.

  3. In the search field, type a string such as liveview to narrow the list of adapters. Select the icon for the LiveView Alerts adapter, then click OK.

  4. Double-click the adapter's icon and select the Adapter Properties tab in the Properties view.

  5. Next, either:

    1. If this adapter is part of an EventFlow module that is itself part of a LiveView project, select the Set Server URI to encapsulating LiveView check box. This check box tells the adapter to connect to the host and port for the current project's LiveView server.

    2. Or specify the URI for a local or remote LiveView server to connect to (or accept the default URI, lv:/localhost:11080).

  6. Add an Input Stream and connect an arc from it to the LiveView Alert adapter's input port.

  7. Specify the schema for the Input Stream as described in the LiveView Alert adapter input port.

  8. Add an Output Stream and connect an arc to it from the LiveView Alert adapter's output port.

  9. At runtime, send a tuple to this module's input port, specifying the alert command you wish to perform.

Typechecking and Error Handling

The LiveView Alert Configuration adapter uses typecheck messages to help you configure the adapter.

The adapter generates warning messages at runtime under various conditions, including:

  • The configured LiveView server is not available.

Suspend and Resume Behavior

When suspended, the adapter stays connected to the LiveView server, but no longer processes input tuples. On resume, the adapter continues to process new input tuples.