Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.6.3)

Part Number E10224-15
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

60 Creating Oracle BAM Alerts

This chapter describes how to create and use alerts in Oracle Business Activity Monitoring (Oracle BAM). It describes how to define rules that specify the events and conditions under which an alert fires, include messages with alert rules, manage nested rules with dependent rules, and create custom actions for rules using external actions.

This chapter contains the following topics:

60.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 and viewed in both the Oracle BAM Architect and Oracle BAM Active Studio web applications: In Oracle BAM Architect, select Alerts from the function list as shown in Figure 60-1. In Oracle BAM Active Studio, select the Alerts tab as shown in Figure 60-2.

Figure 60-1 Oracle BAM Architect Function List

Description of Figure 60-1 follows
Description of "Figure 60-1 Oracle BAM Architect Function List"

Figure 60-2 Oracle BAM Active Studio Function Tabs

Description of Figure 60-2 follows
Description of "Figure 60-2 Oracle BAM Active Studio Function Tabs"

In Oracle BAM Architect, alerts are displayed in a table, which may include an Alert Owner column that shows the users who created the alerts, as shown in Figure 60-3. The Alert Owner column displays only if the current user is a member of the administrative role (that is, an admin user). Admin users are able to see alerts they have created and alerts created by other users (admin and non-admin).

Figure 60-3 Alerts Table with Alert Owner Column

Description of Figure 60-3 follows
Description of "Figure 60-3 Alerts Table with Alert Owner Column"

In Oracle BAM Active Studio, alerts are shown in the Alert Rules table (Figure 60-4), which includes a Last Launched column that indicates the last time the alert rule was fired. As in Oracle BAM Architect, each alert name is accompanied by an icon indicating its status as described in Table 60-1, and non-admin users only see the alerts they have created. If the current user is an admin user, the table displays all alerts and includes the Alert Owner column that shows the users who created the alerts.

Figure 60-4 Alert Rules Table in Oracle BAM Active Studio

Description of Figure 60-4 follows
Description of "Figure 60-4 Alert Rules Table in Oracle BAM Active Studio"

Table 60-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.


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, 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.

60.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.

60.2.1 How to Create an Alert Rule

The procedure to create Oracle BAM alert rules in Oracle BAM Architect and Oracle BAM Active Studio is the same.

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 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.

60.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.

Administrative role users can change the activity status of their own alerts and alerts created by other admin and non-admin users.

To change the activity status of an alert rule:

  1. Select the alert you want to change.

  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.

60.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.

If an administrative role user modifies an alert created by another user, the alert is only saved in the name of the original alert owner.

To modify an alert rule:

  1. Select the alert rule to edit.

  2. Click Edit in the Alert Actions list or Edit alert in the Actions list.

    The Rule Creation and Edit dialog box opens.

  3. Make changes to the alert and click OK.

60.2.4 How to Delete an Alert

Administrative role users can delete their own alerts and alerts created by other admin and non-admin users.

To delete an alert:

  1. Select the alert to delete.

  2. Click Delete in the Alert Actions list or Delete alert in the Actions list.

    A dialog box opens to confirm alert deletion.

  3. Click OK.

    The alert is deleted.

60.2.5 What You May Need to Know About Modifying Alerts

Administrative role users are able to activate or deactivate, edit, and delete all alerts, that is, alerts that they own and alerts created by other admin users and non-admin users.

When admin users edit a non-admin user's alert that involves selecting a report, they are able to see and select only the reports of the alert owner (and not their own reports) in the Select Report dialog. In Oracle BAM Architect and Oracle BAM Active Studio, the option to select a report appears when editing an alert that involves any of the following events, conditions or actions:

  • when a report changes

  • when a data field in a report meets specified conditions

  • when sending a report by email

  • when sending a report by email and escalating to another user after a specific amount of time

  • when creating a message that includes a hyperlink to a report

  • when sending a parameterized message

  • when sending a parameterized message for every matching row in a data object

For example, when admin users edit a non-admin user's alert that uses the When a report changes event, they are able to see and select only the reports of the alert owner (and not their own reports) in the Select Report dialog (Figure 60-5). Similarly, when editing a message in the Alert Message - WebPage dialog, admin users are able to add a link to a report of the alert owner only, to send in the message body (Figure 60-6).

Figure 60-5 Select a Report Dialog

Description of Figure 60-5 follows
Description of "Figure 60-5 Select a Report Dialog"

Figure 60-6 Alert Message - WebPage Dialog

Description of Figure 60-6 follows
Description of "Figure 60-6 Alert Message - WebPage Dialog"

Also, when editing a non-admin user's alert in the Rule Creation and Edit dialog, admin users are not able to add the "run as <user name>" option and other admin-specific options in the Rule Expression box (Figure 60-7).

Figure 60-7 Rule Creation and Edit Dialog

Description of Figure 60-7 follows
Description of "Figure 60-7 Rule Creation and Edit Dialog"

60.3 Creating Alert Rules From Templates

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

60.3.1 How to Create Alert Rules From Templates

The procedure to create Oracle BAM alert rules from templates in Oracle BAM Architect and Oracle BAM Active Studio is the same.

To create an alert rule from a template:

  1. Click Create A New Alert.

    The Rule Creation and Edit dialog 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.

60.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.

60.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.

60.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:

60.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 an 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 an 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.

60.6 Using Alerts History

The Alerts History table is available in Oracle BAM Active Studio. It provides a list of alert rules triggered and their status messages.

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

60.6.1 How to View the Alerts History List

You can view a 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.

60.6.2 How to Clear the Alerts History List

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

To clear the alerts history list:

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

    A message is displayed to confirm to clear the alerts history list.

  2. Click OK.

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

60.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.

60.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.

60.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 Business Process Management 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