About Triggers
A trigger is a resource that initiates a specific system activity to be performed when specified conditions occur. Triggers use a JMS event, a system event, a timer event, or a user-defined event to initiate specific system actions like:
• Execute a procedure
• Gather statistics
• Re-introspect data sources
• Send an email
Triggers can be scheduled to be performed periodically or can occur based on specified conditions. The triggering conditions can cause actions without requiring user interaction. When you create a trigger, it appears in the Studio resource tree.
Triggers provide the following benefits:
• One user can set multiple schedules (using separate triggers) on one resource.
• Many users with appropriate privileges can share the same schedule on a resource.
• Users can define their own events to trigger several actions asynchronously.
• Tasks and actions can be triggered in response to a system event, such as a request failure or the status of a data source.
• Procedures can be executed without sending notifications.
• Views and procedures can be executed and the results can be sent to one or more recipients.
Condition Types for a Trigger
This section describes the trigger condition types that Studio supports: JMS events, system events, timer events, and user-defined events.
• JMS Event—Enables the firing of an action based on the receipt of a JMS message on the specified queue or topic connection. The firing of the trigger is contingent on the match with the particular selector property specified using SQL condition syntax.
• System Event—Enables the firing of an action based on any system-generated event. User tasks can listen for such events. Two APIs—GetEnvironment and SetEnvironment—are available at /lib/util/, and can be called at any time to listen for a system-generated event.
When you specify System Event as the condition type for your trigger, the system provides a dynamic list of all available events for you to select from. The following System Events can be used for a trigger.
System event | When triggered or generated |
CacheRefreshFailure | Triggered when a cache fails to refresh. |
CacheRefreshSuccess | Triggered when a cache refresh is performed successfully. |
ClusterServerConnected | Generated when a cluster node is connected. |
ClusterServerDisconnected | Generated when a cluster node is disconnected. |
ClusterServerShunned | Generated when a cluster node fails to send a heartbeat signal to the cluster timekeeper and has been shunned (temporarily excluded) from the cluster. |
DataSourceDown | Generated when a data source connection is lost. Data source connections are tested in any of the following cases: • Studio restart tests all data sources • New data source, configurations, and connections • Resource execution checks connection status • Committing/rolling back a transaction All reports of a data source being in DOWN status generate an event regardless of whether that data source was reported as down previously. |
DataSourceUp | Generated when a data source connection is re-established. Data source connections are tested in any of the following cases: • Studio restart tests all data sources • New data source, configurations, and connections • Resource execution checks connection status • Committing/rolling back a transaction A Data Source Up event is generated only when the data source is first connected or when the status is changed from DOWN to UP. |
ErrorsSpike | Generated when errors pass a predetermined number. |
FailedLoginSpike | Any ten failed sign-in attempts within a ten minute period generate a FailedLoginSpike event. |
MetricRestoreFailure | Generated when the metrics are trying to be restored, but they fail. |
MetricsBackupFailure | Generated when the metrics backup fails. |
MetricsPersistentFailure | Generated when metrics data fails to persist. |
MetricsTruncationFailure | Generated when the truncation of metrics data fails. |
RequestFailure | Generated when a request results in failure. Whenever any SOAP call or SQL execution is not accepted, produces an exception, or results in an error, this event is logged. This event is generated when closing any unsuccessful request. |
RequestInactive | Generated when a request is inactive. A request is considered inactive when it has no incoming or outgoing byte change beyond a configurable number of minutes. The value of the inactivity period is a server configuration parameter that can be configured using Request Inactive Time. By default there is no setting for the inactivity time. |
RequestRunForTooLong | Generated when: • Enable All Events is set to true. • Request Run Time is enabled. |
RequestsSpike | Generated when requests pass a predetermined number. |
ResourceLock | Generated when resource locks are set on a resource so that only one person can modify the locked set. |
ResourceUnlock | Generated when a resource is unlocked so that any user with sufficient rights and privileges can edit it. |
ServerStart | Event is generated when TDV starts. |
ServerStop | Event is generated when TDV stops. |
StatisticsGatheringFailure | Event is generated when an attempt to gather statistics on a data source fails. |
TransactionFailure | Event is generated on any transaction failure. |
UserLogin | Event is generated when user logs in to TDV. |
TableCreate | Event is generated when table is created using DDL.. |
Making a trigger based on a system event does not enable a disabled event. All system events are enabled by default, but if they are disabled they require a manual server configuration change to enable them. For more information, see the TDV Administration Guide.
Triggers cannot enable a disabled data source.
• Timer Event—Lets you schedule periodic timed trigger events. Actions that can be timed to start are: executing a procedure, gathering relevant data from a data source for query processing, re-introspecting a data source, or sending email with the results of a procedure/view execution.
To set a timer event, you define the start time, optionally specify a period or window of daily or periodic activity, and set the frequency of the trigger refresh to get the wanted periodicity. Triggers can be set to begin operation in the future and end after a predefined activity period.
You can optionally specify a recurrence restriction. If Recurrence Restriction is enabled, the trigger fires only on the selected days of the week and during the time window specified by the Start and End times, subject to the following rules:
— If Start and End time are identical, no time restriction is applied.
— If End time is greater than Start time, the trigger is restricted to fire only within the time window starting at Start time (inclusive) and ending at End time (inclusive).
— If End time is less than Start time, the trigger is restricted to fire only within the time window starting at End time (inclusive) and ending at Start time on the next day (inclusive).
• User Defined Event—Utilizes a built-in procedure named GenerateEvent which is available at /lib/util/. This procedure can be called at any time to insert a user-defined event into the trigger system. You can use this functionality for letting an ongoing procedure call GenerateEvent to trigger a wanted action asynchronously.
See
Condition Pane for more information about the options for each condition type.
Action Types for a Trigger
Executing a procedure, gathering statistics on a data source, re-introspecting a data source, and sending email are the trigger action types that can be triggered for certain conditions.
• Execute Procedure—Lets you specify a procedure to be executed without sending any notification.
— Exhaust output cursors—If the procedure is a SQL script that contains a PIPE cursor, and if the pipe needs to fully execute and load all rows to complete execution of a trigger (for example, to email a result set) checking this box forces the trigger to wait until all the rows are buffered and read before completing. If you leave this unchecked, the trigger returns while the pipe is buffering, cutting off the buffering of the pipe.
• Gather Statistics—Lets you specify a data source whose data statistics are to be gathered.
• Reintrospect Data Source—Lets you specify a data source to be re-introspected.
• Send email—Lets you specify a procedure or view to be executed, and send the results through email to one or more specified recipients.
See
Action Pane for more information about the options for each condition type.