57 Creating Oracle BAM Alerts

This chapter describes how to create alerts in Oracle BAM.

This chapter contains the following topics:

57.1 Introduction to Creating Alerts

Alerts are launched by a set of specified events and conditions, known as a rule. Alerts can be launched by data changing in a report or can send a report to users daily, hourly, or at set intervals. Events in an alert rule can be an amount of time, a specific time, or a change in a specific report. Conditions restrict the alert rule to an event occurring between two specific times or dates. As a result of events and conditions, reports can be sent to users through email.

Alerts can be created in both the Oracle BAM Architect and Oracle BAM Active Studio web applications.

Alerts are shown in the Alert Rules table. In Oracle BAM Active Studio the table includes a Last Launched column that indicates the last time the alert rule was fired. Each alert name is accompanied by an icon indicating its status as described in Table 57-1.

Figure 57-1 Alert Rules Table in Oracle BAM Architect

Description of Figure 57-1 follows
Description of "Figure 57-1 Alert Rules Table in Oracle BAM Architect"

Table 57-1 Alert Rule Icons

Icon Description

normal alert icon

Normal indicates that the alert is active and fires under the conditions specified in the rule.

invalid alert icon

Invalid indicates that an alert has become orphaned or broken due to some error. This icon is displayed when an alert cannot be loaded properly into the Event Engine. The rule might require correction.

For example, when a report is deleted and an alert based on this report still exists, that alert cannot be loaded properly.

This icon appears only when rules are loaded into the Event Engine (on restarts). Alerts displayed with this icon do not fire again until they are edited and corrected.

expired alert icon

Expired means that the alert does not fire again. This icon is seen in time based alerts which fire only one time, after the alert has fired. However, these alerts can be edited and reused, resetting the state to Normal.


Note that inactive and expired alerts behave differently. An alert can be deactivated only if it is running. This behavior is a benefit to users who do not want to receive alerts for some time interval, but want to retain the ability to activate the alert at a convenient time. Alerts that are not active, but still valid (displayed with the Normal icon) can be activated again.

Those alerts that are expired have run for the specified condition and do not run again. They cannot be activated to run again. However, if you want to reuse an expired alert, double click the alert, update the definition to make it a valid rule, and save the alert rule definition. The alert is reloaded and is ready to fire again.

Note:

If any changes to the time or time zone are made on the Oracle BAM Server system, the Oracle BAM Server application must be restarted or time-based alerts misfire.

57.2 Creating Alert Rules

A rule specifies the events and conditions under which an alert fires.

Note:

An alert fires only if its triggering event conditions are met from the point in time the alert is defined (or reenabled) and forward. An alert does not fire if its conditions were met before it was defined, or while it was disabled.

57.2.1 How to Create an Alert Rule

This section describes how to create Oracle BAM alert rules in Oracle BAM Architect. The procedure is the same in Oracle BAM Active Studio.

To create a rule:

  1. Select Alerts in the Oracle BAM Architect function list.

    In Oracle BAM Active Studio, select the Alerts tab.

  2. Click Create A New Alert.

    The Rule Creation and Edit dialog box opens.

  3. Click Create A Rule.

  4. Enter a name for the rule.

    Caution:

    A single or double quotation mark in an Oracle BAM object name, such as a data object, report, or enterprise message source name, causes a runtime error.

    Do not include single or double quotation marks in an Oracle BAM object name.

  5. Select an event that launches the alert.

    See Section F.1, "Events" for descriptions of each event.

  6. Click Next.

  7. Select one or more conditions, if needed.

    See Section F.2, "Conditions" for descriptions of each condition.

  8. Select one or more actions. See Section F.3, "Actions" for descriptions of each action.

  9. In the rule expression, click each underlined item and specify a value to complete the alert rule.

    For example, click select report, and choose a report in the dialog box that opens. Other values you define include user names receiving reports, dates and times, time intervals, and filter expressions for a specific field. To continue adding conditions or actions, click the last line in the expression and then select another condition or action.

    You can click the Back and Next buttons to go between the events page and the page containing actions and conditions, and make changes to those parts of the rule expression you have constructed.

  10. You can click the Frequency Constraint button to set a limit to how often an alert can launch.

    The default frequency constraint for alerts is five seconds. Type a number and select a time measurement such as seconds, minutes, or hours, and click OK. To turn off the frequency constraint, uncheck the Constraint Enabled checkbox. For more information about frequency constraint see Section F.4, "Frequency Constraint."

  11. Click Delete this expression to remove lines from the alert rule.

  12. Click OK.

    The alert rule is added to list and is active.

57.2.2 How to Activate Alerts

When you create an alert rule, it is automatically active. If you want an alert to be temporarily inactive but you do not want to delete it, you can turn it off by deselecting the Activate checkbox.

To change the activity status of an alert rule:

  1. Select Alerts from the Oracle BAM Architect function list.

  2. Select the Activate checkbox for the alert rule.

A checked box means the alert rule is active.

An unchecked box means the alert rule is inactive.

Selecting the Activate checkbox does not cause an alert to launch, it only enables the rule so that if the specified event occurs, the alert launches.

An exclamation mark on the alert icon indicates it has launched and is not valid again, or because items that it references are missing and it cannot launch.

57.2.3 How to Modify Alert Rules

When you modify alert rules created from a template, you can add new lines and select conditions and actions the same as when you build alert rules without templates.

To modify an alert rule:

  1. Select the alert rule to edit.

  2. Click Edit in the Alert Actions list.

    The Rule Creation and Edit dialog box opens.

  3. Make changes to the alert and click OK.

57.2.4 How to Delete an Alert

To delete an alert:

  1. Select the alert to delete.

  2. Click Delete in the Alert Actions list.

    A dialog box opens to confirm alert deletion.

  3. Click OK.

    The alert is deleted.

57.3 Creating Alert Rules From Templates

Alert rule templates are a convenient preselected group of events and conditions based on some common use cases.

57.3.1 How to Create Alert Rules From Templates

To create an alert rule from a template:

  1. Click Create A New Alert.

    The Create Alert Rule dialog box opens.

  2. Click Create A Rule From A Template.

  3. Enter a name for the alert rule.

  4. Select a template from the list.

  5. In the Rule Expression box, click each underlined item and specify a value to complete the alert rule. For example, click select report, and choose a report in the dialog box that opens. Other values you define include user names receiving reports, dates and times, time intervals, and filter expressions for a specific field.

  6. You can click Frequency Constraint to specify how often an alert can launch. The default frequency constraint for alerts is five seconds. Enter a number and select a time measurement such as seconds, minutes, or hours, and click OK.

  7. You can click Modify this rule to modify the rule without using the template. This provides more options for creating rules.

  8. Click OK.

    The alert rule is added to list and is active.

57.4 Creating Alert Rules With Messages

You can create alert rules that send messages. The messages can contain information such as report names, links to reports, and user names. Messages can also include variables that are set when the alert is launched, such as the time that an event occurred and the data that launched the event. To use data variables, the event must be based on data.

57.4.1 How to Create an Alert Rule With a Message

You can create alert rules that send messages. The messages can contain information such as report names, links to reports, and user names. Messages can also include variables that are set when the alert is launched, such as the time that an event occurred and the data that launched the event. To use data variables, the event must be based on data.

To create an alert rule that includes a message:

  1. Start building an alert rule.

  2. Select the action Send a message via email.

  3. Click create message in the rule expression.

    The Alert Message dialog box opens.

  4. Enter a subject in the Subject line.

  5. Enter the message in the Message Text box.

  6. Include special fields into the message.

    Special fields are listed in the box in the lower left corner of the Alert Message dialog box. The special fields listed change when reports are selected on the right side of the dialog box.

    To insert a special field into the message:

    1. Select a special field from the list.

    2. Click Insert into subject or Insert into text.

    You can insert multiple values of the same type, for example, multiple links to different reports.

    • Send Report Name inserts name of selected report.

    • Send Report Owner inserts owner name of selected report.

    • Send Report Link inserts link to selected report.

    • Changed Report Name inserts name of the changed report.

    • Changed Report Owner inserts Owner Name Of Changed Report.

    • Target User inserts user name of message recipient.

    • Date/Time Sent inserts date and time of message sent.

  7. Click OK.

57.5 Creating Complex Alerts

You can create nested rules with many actions and chained rules that launch other rules.

You can chain rules by creating two types of rules:

  • A dependent rule that must be launched by another rule.

  • A rule with an action to launch a dependent rule.

57.5.1 How to Create a Dependent Rule

To create dependent rules:

  1. Create a rule that includes the event When this rule is launched. No value is required for this event.

  2. Create a rule that includes the action Launch a rule or Launch rule if an action fails. The Launch rule if action fails applies to any of the actions contained in the rule.

  3. Click select rule in the action.

    The Select Dependent Rule dialog box opens.

  4. Select a dependent rule. Only rules that include the When this rule is launched event are displayed in the list.

  5. Click OK.

To handle a failing action, add the action Launch rule if action fails. For example, if a rule is supposed to send a message, and for some reason the message does not send, you could launch another rule to notify you.

57.6 Using Alert History

Alert history is available in Oracle BAM Active Studio providing a list of alert rules triggered and their status messages.

Description of bam_alerthistmsg.gif follows
Description of the illustration bam_alerthistmsg.gif

57.6.1 How to View Alert History

You can view recent history of alert activity on the Alerts tab in Oracle BAM Active Studio. The Alerts History list displays the 25 most recent alerts launched.

In the Alerts History list, you can view the names of recently launched alerts, any messages associated with the alerts, the users who created the alerts, and the time and date that the alert rules were triggered.

In the case of alert rules that send e-mail, the Alerts History list only displays the alert if the user currently logged in is an alert e-mail recipient. It is not listed in the Alerts History list--even if the user is the creator of the alert--if the user is not a recipient of the alert.

However, if an alert fails to send a message to an alert recipient, the message is logged with the alert owner's name, so that the owner can see the error message in the Alerts History pane and take corrective action if necessary. A non-existing name cannot be logged as the alert recipient's name.

Alerts History Messages

The Message column of the Alerts History list provides information about the success or failure of alert delivery. The successful alert is shown with a green checkmark next to the message. The unsuccessful alert is displayed with a red x icon and a message indicating how the alert failed at the time of loading or processing. Click the x icon for additional information about the error.

If a report is deleted that is referenced by an alert, there is no warning to the user. When the alert is triggered, the error message "Error occurred while sending e-mail" is given with no specific error regarding broken references to the deleted report. When deleting reports, it is important to verify that the report is not referenced by an alert, or this error occurs.

57.6.2 How to Clear Alert History

When many alerts are actively launching and the alert history list becomes long, you might want to clear your alert history list.

To clear the alert history:

  1. On the Alerts tab, click Clear alert history.

    A message is displayed to confirm to clear alert history.

  2. Click OK.

    The alert history list is deleted. New alerts launched after clearing appear in the alert history list.

57.7 Launching Alerts by Invoking Web Services

You can use the alerts web service to manually launch alerts. For more information, refer to:

http://host:http_port/OracleBAMWS/WebServices/ManualRuleFire?wsdl

You define the rule name using the format:

username.alertname

Note:

Oracle BAM Active Studio URLs used in alerts and report links contain a virtual directory using the product build number for caching and performance purposes. This directory must be included in links, and it is not recommended to edit these links. Links created with a previous version of Oracle BAM do not work after a product upgrade. The alert requires editing or the report shortcut must be copied again.

57.8 Calling an External Action

Call an External Action is used to develop a custom action. For users whose requirements cannot be fulfilled by the actions provided by Oracle BAM, this feature is used to extend the action set.

External actional actions are not seen in the Oracle BAM Alerts user interface by default. They must be registered with Oracle BAM before they are seen in the user interface.

To do this task, the EventEngine interface must be implemented and you must develop an action around it. That means you must write Java code, bundle the compiled code in a JAR file. Then register it in Oracle BAM Architect as an action in the System/Alerts/External Actions data object.

Call an External Action action is not required to invoke Web services. The action was used in this way in pre 11g releases, but was replaced by Call a Web Service action in Oracle BAM 11g. Call a Web Service action has a more sophisticated Web services client, which is dynamic and can invoke any service by reading WSDLs at runtime.

57.9 Sending Alerts to External E-mail Accounts

Alerts from Oracle BAM can be sent to e-mail accounts that are unknown to Oracle BAM if a property is set in the Oracle BAM common configuration file.

This feature is available only for the actions Send a report via email and Send a message via email.

To send alerts to external e-mail accounts:

  1. Set the property AlertActionAllowExternalEmail to true in the BAMCommonConfig.xml configuration file.

    See "Configuring Advanced Properties" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for information about editing Oracle BAM configuration files.

  2. Restart Oracle BAM.

  3. Create an alert rule containing an action that sends messages to users.

  4. Click select user and enter the e-mail addresses in the And/Or external email addresses box, separating the addresses with semicolons.

    Description of bam_alert_ext.gif follows
    Description of the illustration bam_alert_ext.gif