F Oracle BAM Alert Rule Options

This appendix describes the events, conditions, and actions that are used in defining Oracle Business Activity Monitoring (Oracle BAM) alert rules.

This appendix includes the following sections:

For information about modifying alerts when the user is a member of the administrative role, see Section 60.2.5, "What You May Need to Know About Modifying Alerts."

F.1 Events

Events launch the rule and trigger the action. Each rule contains only one event. Oracle BAM provides the following events:

F.1.1 In a specific amount of time

When you select the event In a specific amount of time, you must complete the rule expression by selecting a time interval in seconds, minutes, or hours.

F.1.2 At a specific time today

When you select the event At a specific time today, you must complete the rule expression by selecting the time at which to launch the alert.

F.1.3 On a certain day at a specific time

When you select the event On a certain day at a specific time, you must complete the rule expression by selecting both the date and the time at which to launch the alert.

F.1.4 Every interval between two times

When you select the event Every interval between two times, you must complete the rule expression by configuring the following settings.

  • select time interval

    Set the number of minutes, hours, or days between each alert launch.

  • select time

    Set the times of day between which the rule is valid and the alert is launched.

F.1.5 Every date interval starting on certain date at a specific time

When you select the event Every date interval starting on a certain date at a specific time, you must complete the rule expression by configuring the following settings.

  • select date interval

    Set the alert to launch every Day, Week, Month, or Year.

  • select date

    Set the date on which the rule is valid and the alert is launched.

  • select time

    Set the time of day at which the rule is valid and the alert is launched.

F.1.6 When a report changes

When a report changes is launched when runtime changes in a report occur (not changes in the report definition), that is every time a change list is delivered to the report from the Oracle BAM Server. Report changes can include changes to data in data objects and changes due to Active Now settings.

When you select the event When a report changes, you must complete the rule expression by configuring the following settings.

  • select report

    Select the report to monitor for changes.

  • run as <user_name> (This option appears only if the user creating the alert is a member of the administrator role.)

    Select the Oracle BAM user who the selected report runs as. You can select only one run as user. The default run as user is the logged in Oracle BAM user who is creating the alert.

    Only recipients who have security permissions that are the same or higher than the run as user receive the notification for report changes, honoring row level security as implemented by the Oracle BAM Architect in the data objects used in the report.

    Names that are preceded with a hash (#) are distribution lists.

    If there are changes in a report's data object rows that none of the alert recipients have permissions to access, no recipients are notified.

F.1.7 When a data field changes in data object

When you select the event When a data field changes in a data object, you must complete the rule expression by configuring the following settings.

Note:

The event When a data field in a data object meets specified conditions responds only to row inserts and row updates, but it does not respond to row deletes; however, the event When a data field changes in a data object responds to row deletes.

  • select data field

    Select the data object field to monitor for changes. In the Field Selection dialog box, locate the data object in the top left section of the dialog box, then select the field in the top right section of the dialog box. Finally, select one or more fields to group by and an aggregate function for the selected field.

  • run as <user_name> (This option appears only if the user creating the alert is a member of the administrator role.)

    Select the Oracle BAM user who the selected report runs as. You can select only one run as user. The default run as user is the logged in Oracle BAM user who is creating the alert.

    Only recipients who have security permissions that are the same or higher than the run as user receive the notification for report changes, honoring row level security as implemented by the Oracle BAM Architect in the data objects used in the report.

    Names that are preceded with a hash (#) are distribution lists.

    If there are changes in a report's data object rows that none of the alert recipients have permissions to access, no recipients are notified.

F.1.8 When a data field in a report meets specified conditions

When you select the event When a data field changes in a data object, you must complete the rule expression by configuring the following settings.

  • select report

    Select the report to monitor for changes.

  • this data field has a condition of x

    In the Alert Rule Editor dialog box, select the data object to monitor. Then you can set the condition under which the alert should fire.

    • Row Filter - Create a filter on a field in the data object to express a condition that, when met, launches the rule. All of the functionality available in report filters is provided. See "Filtering Data" in Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring for more information.

    • Group Filter - The Group Filter is similar to the Row Filter in that it provides all of the filtering functionality available in report filters. The special feature here is that it allows filters to be created on a field where a summary function has been applied. See "Filtering Data" in Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring for more information about building filter expressions.

    • Group - Choose one or more fields on which to create a grouping, adding further complexity to any filters created in the Row Filter or Group Filter tabs.

  • run as <user_name> (This option appears only if the user creating the alert is a member of the administrator role.)

    Select the Oracle BAM user who the selected report runs as. You can select only one run as user. The default run as user is the logged in Oracle BAM user who is creating the alert.

    Only recipients who have security permissions that are the same or higher than the run as user receive the notification for report changes, honoring row level security as implemented by the Oracle BAM Architect in the data objects used in the report.

    Names that are preceded with a hash (#) are distribution lists.

    If there are changes in a report's data object rows that none of the alert recipients have permissions to access, no recipients are notified.

F.1.9 When a data field in a data object meets specified conditions

When you select the event When a data field in a data object meets specified condition, you must complete the rule expression by configuring the following settings.

Note:

The event When a data field in a data object meets specified conditions responds only to row inserts and row updates, but it does not respond to row deletes; however, the event When a data field changes in a data object responds to row deletes.

  • this data field has a condition of x

    In the Alert Rule Editor dialog box, select the data object to monitor. Then you can set the condition under which the alert should fire.

    • Row Filter - Create a filter on a field in the data object to express a condition that, when met, launches the rule. All of the functionality available in report filters is provided. See "Filtering Data" in Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring for more information.

    • Group Filter - The Group Filter is similar to the Row Filter in that it provides all of the filtering functionality available in report filters. The special feature here is that it allows filters to be created on a field where a summary function has been applied. See "Filtering Data" in Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring for more information about building filter expressions.

    • Group - Choose one or more fields on which to create a grouping, adding further complexity to any filters created in the Row Filter or Group Filter tabs.

  • run as <user_name> (This option appears only if the user creating the alert is a member of the administrator role.)

    Select the Oracle BAM user who the selected report runs as. You can select only one run as user. The default run as user is the logged in Oracle BAM user who is creating the alert.

    Names that are preceded with a hash (#) are distribution lists.

    Only recipients who have security permissions that are the same or higher than the run as user receive the notification for report changes, honoring row level security as implemented by the Oracle BAM Architect in the data objects used in the report.

    If there are changes in a report's data object rows that none of the alert recipients have permissions to access, no recipients are notified.

F.1.10 When this rule is launched

The event When this rule is launched is used to create a rule dependent on another rule which uses the Launch a rule action. Several rules can be created using When this rule is launched in a hierarchy.

F.2 Conditions

Conditions are optional settings for constraining the time period in which the alert is fired. You can select any number and combination of conditions. Oracle BAM provides the following conditions:

F.2.1 If it is between two times

Select two times between which the rule should launch.

F.2.2 If It is between two days

Select two dates between which the rule should launch.

F.2.3 If it is a particular day of the week

Select a day of the week on which the rule should launch.

F.3 Actions

Actions are the results of the conditions and events of the rule expression having been met. You can configure any number and combination of actions. Oracle BAM provides the following actions:

F.3.1 Send a report via email

Select a report, select to send the report as a report link or as a rendered report, and select a recipient.

Recipients can be selected from Oracle BAM users, or, if a property is set in Oracle BAM, external e-mail accounts. See Section 60.9, "Sending Alerts to External E-mail Accounts" for more information.

F.3.2 Send a message via email

Create an email message to send and select a recipient.

Recipients can be selected from Oracle BAM users, or, if a property is set in Oracle BAM, external e-mail accounts. See Section 60.9, "Sending Alerts to External E-mail Accounts" for more information.

F.3.3 Send a report via email and escalate to another user after a specific amount of time

Select a report to send to the specified user. Select a secondary recipient to receive the message if the first recipient does not respond within the specified time period. The secondary recipient can be a single user or a distribution list.

When the condition of the alert rule is met, a report link is sent to the recipient. To respond to this alert, the recipient must click the report link and view the report. If the recipient does not view the report, it is escalated to the secondary user (or distribution list).

Recipients can be selected from Oracle BAM users, or, if a property is set in Oracle BAM, external e-mail accounts. See Section 60.9, "Sending Alerts to External E-mail Accounts" for more information.

F.3.4 Send a parameterized message

This option enables you to email reports that require parameter inputs to Oracle BAM users. This action enables you to create a fully configurable email message and the parameter values that are passed to the report.

For information about creating prompts and parameters in Oracle BAM dashboards see "Using Prompts and Parameters" in Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring.

You can use this option to send reports to other users under the conditions specified in the alert message. This action is available for the events When a data field changes in data object and When a data field in a data object meets specified conditions.

There are two properties that must be configured in this alert action: create message and set parameters.

Description of bam_alert_param_expr.gif follows
Description of the illustration bam_alert_param_expr.gif

To create the message:

  1. Click create message in the rule expression.

  2. Enter a subject and message to send to the recipient. You can also select links to reports to send in the message body as shown in Figure F-1.

    Figure F-1 Alert Message dialog box

    Description of Figure F-1 follows
    Description of "Figure F-1 Alert Message dialog box"

To configure the parameter values that are passed to the report when it is opened by the recipient:

  1. Click set parameters in the rule expression.

  2. In the Alert Action Parameter Creation and Edit dialog box, populate the User and Report fields with either predefined values or dynamically from a Data Object field. Use the buttons to set the field values. Select Field enables you to select a field in a data object as a value.

    Figure F-2 Alert Action Parameter Creation and Edit dialog box

    Description of Figure F-2 follows
    Description of "Figure F-2 Alert Action Parameter Creation and Edit dialog box"

    • User field

      If you populate this field using the Select User button, the recipients are selected from Oracle BAM users listed in Oracle BAM Administrator as shown in Figure F-3.

      Figure F-3 Select Names dialog box

      Description of Figure F-3 follows
      Description of "Figure F-3 Select Names dialog box"

    • Report field

      If you populate this field with the Select Report button, the value that appears in this field is the display name of the report.

      If you populate this field from a Data Object, the value must be the report ID of that report, and not the display name. To get the report ID, click the report and click the Copy Shortcut link. A window opens with a link such as:

      http://myServer/oraclebam/ReportServer/default.aspx?Event=ViewReport&
      ReportDef=1&Buttons=False
      

      In this link the ReportDef value, 1, is the report ID of the report Emp_Report. Every report in Oracle Business Activity Monitoring has a unique report ID.

  3. Configure the Report Parameter Values.

    Enter all of the parameters required by the report.

    Click New in the Report Parameter Values list to configure the parameter.

    Description of bam_alert_para_cfg_cr.gif follows
    Description of the illustration bam_alert_para_cfg_cr.gif

    Enter the parameter name in the Name field, and click Select Field to select the field on which the parameter acts.

    Description of bam_alert_para_cfg_nm.gif follows
    Description of the illustration bam_alert_para_cfg_nm.gif

    Key in the parameter value, or select the field from the Field Selection dialog box, and click OK.

    For special values use the underscore (_), for example, _ALL_, _BLANK_, and _NULL_.

    Description of bam_alert_para_cfg_fld.gif follows
    Description of the illustration bam_alert_para_cfg_fld.gif

    The selected field ID appears in the Value text box. Click OK to confirm and return to the parameters list.

    Description of bam_alert_para_cfg_sel.gif follows
    Description of the illustration bam_alert_para_cfg_sel.gif

F.3.5 Send a parameterized message for every matching row in a data object

This action can pick up recipients, message content, and the message subject from rows of a static data object. You can specify filter conditions in the configuration screen to choose data object rows for conditional notification. This action can be configured with any event, condition, or action.

When this action is invoked, the rows in the data object that match the filter criteria are used to construct an e-mail message (using the data object parameters specified in the action) which is sent out to the recipients. Message creation is similar to that in Section F.3.4, "Send a parameterized message."

To configure the action:

  1. Click the this data field has a condition of X link and select the data object and filter condition to select the desired rows.

    Note:

    The data object and filter conditions must be selected first so that the data object fields appear.

  2. Click the create message link, and compose the e-mail message, with data object fields if required, similar to Section F.3.4, "Send a parameterized message".

  3. Click the set parameters link and select a recipient (in User) and a report (optional), similar to Section F.3.4, "Send a parameterized message".

  4. Click OK to save the rule.

F.3.6 Launch a rule

Select a dependent rule that includes the when this rule is launched event. For an example of constructing a dependent rule see Section 60.5, "Creating Complex Alerts."

F.3.7 Launch rule if an action fails

Select a dependent rule to launch if any of the actions included in the rule fail. For an example of constructing a dependent rule see Section 60.5, "Creating Complex Alerts"

F.3.8 Delete rows from a Data Object

Select the data object, and construct a filter entry such that when the filter condition is met the row is removed from the data object.

If the data being deleted is more than 10,000 rows, be aware of the following items:

  • If any reports that are dependent upon the data object from which data is being deleted are open at the time the Delete rows from a Data Object action executes, the active data is stopped on the viewsets and reloaded after deletion is complete. Also, if a user attempts to open a report while the delete action for a dependent data object is in process, the report gets stuck or the outcome may be undefined. It is recommended that users do not open reports dependent on the data object while this action is in process. The reports continue to receive active data when the action is finished.

  • In addition, during Delete rows from a Data Object execution, any alerts that are dependent on that data object are temporarily disabled internally. While this action is being run, any new alert created using that data object, or any dependent existing alerts that are disabled and reenabled, results in the system getting stuck. It is recommended that users do not create, disable, or reenable any alerts dependent on the data object while this action is in process. The alerts continue to function normally after the action is finished.

F.3.9 Call a Web Service

When this action is selected, do the following steps to configure the web service:

  1. Enter the web service or WSIL endpoint URL. The URL must begin with the http scheme and must end in a valid extension (?WSDL,  .WSDL or .WSIL).

    For example:

    http://host_name:port_number/OracleBAMWS/WebServices/DataObjectOperationsByID?WSDL
    
    http://api.google.com/GoogleSearch.wsdl
    
    http://host_name:port_number/inspection.wsil
    

    If it is a secure web service select the box and enter the required credentials.

    Note:

    Oracle BAM cannot determine if the web service is hosted on a server which is behind a secure server. It is your responsibility to indicate whether the web service is behind an HTTP basic authentication based server, and you must enter valid credentials if they are required.

    To accomplish one-way SSL, the alert web service client must be pointed to a trust store in which it can look up, to determine if the certificate presented to it exists in it or not. This can be done by setting properties in BAMCommonConfig.xml. See "Calling Secure Web Services" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for more information.

  2. If it is a secure web service check the Secure Web Service checkbox and enter the required credentials.

  3. Click Display Services to display the available services of the URL entered in the field.

  4. The Endpoint URL field, which is initially disabled and empty, is populated after you enter the WSDL/WSIL and credentials, get the list of operations, and select an operation.

    It is populated with the endpoint URL defined in the WSDL file of the web service. If you find this endpoint URL outdated (for example, the web service implementation moved to a different endpoint but you do not have the new WSDL, but know the new endpoint URL) or incorrect, or want to override it, you can edit this URL. When the web service is invoked by Oracle BAM Event Engine, the configured endpoint URL is used to invoke the web service.

  5. Click Map Parameters.

    When the event is based on a data object change (for example, When a data field changes in data object, When a data field in a report meets specified conditions, When a data field in a data object meets specified conditions), a selection list of fields to which the parameter can be mapped is displayed.

    To map the parameters choose the Data Object Field option, and select a data object field from the list next to each web service parameter listed in the Alert Web Service - Parameter Mapping dialog box.

    When the event is not based on a data object change, the value is entered in a text box.

  6. Click OK to close the Alert Web Service - Parameter Mapping dialog box and the Alert Web Service Configuration dialog box.

See Section F.3.9.1, "How to Use Call a Web Service: An Example" for a specific example.

Note:

If the web service does not respond to the call, then there are no logs available pertaining to the non-response or failure.

F.3.9.1 How to Use Call a Web Service: An Example

The following procedure details the steps to create a alert which invokes a web service, using the sample Employees data object to insert a row in a data object.

To use Call a Web Service:

  1. Ensure that the /Samples/Employees data object exists in your Oracle BAM instance.

  2. Log in to Oracle BAM web applications, and open Oracle BAM Active Studio.

  3. Select the Alerts tab, and click Create a New Alert.

  4. Click Create a Rule.

  5. In the Select an Event list, select the first option: In a specific amount of time.

  6. Click select time interval in the Rule Expression panel, and select 1 Second as the time.

  7. Click OK and Next.

  8. In the Select an Action list, select the action Call a Web Service.

  9. Click configure web service in the Rule Expression panel.

    The Alert Web Service Configuration dialog opens.

  10. Provide the WSDL of the DataObjectOperationByName web service on your instance. The URL looks like:

    http://host_name:port_number/OracleBAMWS/WebServices/
    DataObjectOperationsByName?WSDL
    

    where host_name and port_number are substituted with your Oracle BAM instance's host name and port number.

  11. Select the Secure Web Service checkbox, and provide the credentials.

  12. Click Display Operations, and in the operations listed, select the operation Insert.

    This populates the endpoint URL of your web service. If the endpoint your of your web service has changed, or you want to override it with some other implementation, provide the new endpoint URL, otherwise, leave it as it is.

  13. Click Map Parameters to provide the values that map to the parameters in this web service.

    The web service operation in this example requires a value for only one parameter, an XML payload containing the row to insert in the data object.

    Enter the following text in the xmlpayload value and click.

    <DataObject Name="Employees" Path="/Samples"><Contents><Row><Column
     Name="Salesperson" Value="Greg Guan Gan" /><Column Name="Sales Area"
     Value="Northeast" /><Column Name="Sales Number" Value="1234"
     /></Row></Contents></DataObject>
    
  14. Click OK to close the Alert Web Service Configuration dialog, and click OK in the Rule Creation and Edit dialog.

  15. After one second, open Oracle BAM Architect and check the contents of the /Samples/Employees data object to verify that the new row with Salesperson name Greg Guan Gan is inserted in the data object.

F.3.10 Run an Oracle Data Integrator Scenario

Use this action to trigger a scenario in Oracle Data Integrator. This action is only available if the integration files for Oracle Data Integrator have been installed. See "Installing the Oracle Data Integrator Integration Files" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for more information.

Ensure that the Oracle Data Integrator agent is running and that the agent host, port, and login credentials are properly configured in Oracle Enterprise Manager Fusion Middleware Control. Oracle BAM cannot verify that the Oracle Data Integrator agent is running, and if it is not running, the alert fires, but the action is not carried out as expected. Also, Oracle BAM alerts that trigger Oracle Data Integrator scenarios do not track the success or failure of the Oracle Data Integrator scenario call, and it is not logged on the Oracle BAM side. See "Configuring Oracle Data Integrator Properties," in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for more information.

In the alert creation dialog box, select the Oracle Data Integrator scenario to invoke by selecting the scenario name and version from the dropdown list.

If the scenario uses variables in it, choose the values (type in a value or choose a field value from the data object) to pass to Scenario Variables in the same screen.

F.3.11 Call 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.

See Section 60.8, "Calling an External Action" for details on how to configure this action.

F.4 Frequency Constraint

The Frequency Constraint feature prevents a user's email inbox from being flooded with alerts by limiting the number of alert messages that can be sent out during a given time interval.

Frequency Constraint can be edited only if it is appropriate for the event selected. otherwise it is disabled. It can be set to a value of time which could be in seconds, minutes, or hours.

This limits the number of times the rule launches in a given time period. With real-time data, transactions can occur every millisecond, so alerting frequency must be controlled.