Using Response Processing

This chapter tells you everything you need to know about response processing in Oracle Alert.

This section includes a summary of the major response processing features and a discussion of response processing concepts. This chapter also contains task essays that explain how you perform typical response-processing tasks.

This chapter covers the following topics:

• Overview of Response Processing
• Defining a Response Processing Alert
• Responding to an Alert Message
• How Oracle Alert Processes Responses

Overview of Response Processing

Oracle Alert can process responses to your alert messages. When Oracle Alert receives a response to a specific alert message, it automatically performs the actions you define. Optionally, respondents can supply values that Oracle Alert uses to perform these actions. Response processing lets you automate routine user-entry transactions, streamlining your organization's operations.

Note: To enable response processing, ensure that you have performed the required setup steps. See: Setup Steps.

Basic Business Needs

While using Oracle Alert, you should be able to:

• Define a set of possible responses to a particular alert message

• Define one or more actions for Oracle Alert to take when it receives a particular response

• Let the responder to an alert message provide values that Oracle Alert uses when performing response actions

• Define one or more actions for Oracle Alert to take if Oracle Alert receives no response by a specific date

• Define one or more actions for Oracle Alert to take if Oracle Alert receives a response it cannot understand

• Save a complete record of response actions taken, for as many days as you specify

• Use response processing with multiple Oracle Alert installations

Major Features

User-Definable Responses

Oracle Alert lets you define the valid responses that a recipient of an alert message can send back to Oracle Alert. If you define responses for an alert message, Oracle Alert includes the valid responses in the message, so that one of them can serve as a template for the recipient's actual response.

Response Actions

Oracle Alert lets you define actions that it performs automatically when it receives a particular response to an alert message. You can define actions that execute a SQL statement or operating system script, submit a concurrent program request, or send an electronic mail message.

Response Variables and Response Variable Values

Oracle Alert lets you define responses that may include response variables whose values are provided by the responder. Oracle Alert uses these response variable values when performing the actions associated with the response.

No Response Follow-Up Actions

Oracle Alert lets you define follow-up actions that Oracle Alert takes if the message recipient does not respond. Oracle Alert waits for a response to an alert message for the number of days you specify. If Oracle Alert receives no response within that time period, then Oracle Alert automatically initiates the follow-up actions.

Related Topics

Defining a Response Processing Alert

Defining a Response Processing Alert

You must complete the following tasks in the order listed to define a response processing alert:

1. Define an alert

2. Create an alert message action that solicits a response

3. Create response actions

4. Define an action set

5. Create a response set

6. Define possible responses

7. Attach the response set to the alert message action

To define a response processing alert

1. Navigate to the Alerts window.

2. Create either an event or a periodic alert. See: Overview of Alerts.

   Tip: Include in your alert Select statement all the outputs you need to create the alert message action that solicits a response. Also make sure you include all the outputs you need to create the actions to the valid and invalid responses you plan to define.

   Note: You do not have to save history to use response processing, but you can save history for your response processing alerts. See: Response Processing History.

3. Save your work.

To create a message action that solicits a response

1. Choose Actions in the Alerts window.

2. Define a message action in the Actions and Action Details windows that solicits a response from the recipient. Your message can be either a summary or detail level action. See: Creating Alert Actions.

3. Format the message however you like, and include the outputs that represent the exceptions you want. See: Formatting Summary Message Actions.

   When Oracle Alert sends out your message, it automatically appends two pieces of text:

   • Response Text-tells the recipient exactly how to reply to the alert message. This text originates from the Message Elements tabbed region of the Oracle Alert Options form. Your Oracle Alert installation is supplied with the following default text, which you can customize to your needs:

     Your response to this mail note will be processed
     electronically.  For successful processing, you must:
     - Include this note in your reply by using your mail 
     system's Reply With Original feature.
     - Make your actual response EXACTLY like ONE of the 
     following; however, you should replace the question mark 
     (?) with the value you want to specify.
     Choose one of the following responses:
     

   • Valid Response Text-lists the possible responses that the recipient must reply with. You define these possible responses in the Valid Responses block of the Response Sets window, which we describe later in this essay. Oracle Alert appends this Valid Response Text to your message, so the recipient knows the exact text he or she must respond with.

     To summarize, the alert message that solicits a response contains three sections of text. In order of appearance in the message, they are:

   • Text you create in the Action Details block located in the Actions window of the Alerts form that reports the exceptions found, and asks for a response

   • Response text that originates from the Oracle Alert Options form that instructs the recipient how to reply to the message

   • Valid response text of possible valid responses, one of which the recipient must include in his or her response

4. Save your work.

To create the response actions

1. Display the Actions window of the Alerts form.

2. Define the response actions in this window. Response actions are the actions you want Oracle Alert to take when it receives a reply to the alert message action you created in the previous task. You define your response actions before defining your responses. Create as many response actions as you need. See: Creating Alert Actions.

   Note: You can define response actions only as detail level actions.

3. In any of the response actions you define, you can use both outputs and response variables in the action details. Response variables are variables whose values are assigned by the respondent.

   Identify your response variables with an ampersand before the name, for example, &VARIABLE_NAME. Oracle Alert reads the value for a response variable from the message response and reads the value of an alert output from the original alert message, then substitutes the values when executing the action. If the response message does not include the response variable, Oracle Alert uses the default value from your response variable definition.

   Tip: You can create actions for Oracle Alert to take when it receives a response it does not recognize, or when it does not receive a response at all. For example, define a message action that tells the recipient that Oracle Alert did not understand their response.

4. Save your work.

To define an action set for a response processing alert

1. Choose Action Sets in the Alerts window.

2. Define an enabled action set that contains the alert message action that you want to use to solicit a response. See: Creating an Action Set for an Alert.

3. Save your work.

To create a response set for a response processing alert

1. Choose Response Sets in the Alerts window.

   The Response Sets Window

   

   Use the Response Sets window to define the set of valid, invalid, and no response responses your alert message might receive, and tell Oracle Alert which response action it should perform when it receives one of those responses.

2. Enter a response set name (up to 30 characters) and description (up to 240 characters). See: Oracle Alert Naming Conventions.

3. Check Enabled to enable your response set. If you uncheck Enabled, you cannot attach this response set to a message action to solicit responses. If the response set is already attached to a message action, you can uncheck Enabled to prevent Oracle Alert from processing any new responses for that alert.

4. Enter a current or future date in the End Date field to disable your response set by a certain date.

5. Save your work.

6. Choose Response Variables in the Response Sets window to define the response variables that you used in the response actions that you created earlier.

   The Response Variables Window

   

7. Enter a name for the response variable (up to 30 characters), omitting the ampersand. Enter a description for your response variable (up to 240 characters).

   Important: Response variables and outputs cannot have the same names. When you define a response variable, Oracle Alert verifies that the name you assign does not conflict with any defined output names. Oracle Alert displays an error message if your response variable name conflicts with an output name.

8. Specify the data type of the response variable: Character, Number, or Date, in the Type field. Oracle Alert uses the data type to validate default values you enter in the Default field and responses from message recipients.

9. Enter the maximum number of characters you want to display for this response variable in the Max Length field. If the response variable value contains more characters than the maximum length you specify, Oracle Alert:

   • Truncates character and date data

   • Displays a row of pound signs (######) for numeric data

10. Enter a default value to a response variable in case a respondent does not specify a value for the response variable.

11. Save your work.

To define the possible responses to a message action

The Valid Responses Window

1. Choose Valid in the Response Sets window to define your valid responses. A valid response is a response that you expect from an alert message recipient, and one that initiates the alert actions you specify. You can define any number of valid responses as you may have several possible courses of action you allow the user to take.

2. Enter a name for your valid response (up to 240 characters).

3. In the Text field, enter the actual text that you want the respondent to reply with. This becomes the Valid Response Text that Oracle Alert appends to the original alert message.

   If you are defining several valid responses for the same alert, make the first word of each valid response unique. When interpreting an actual response, Oracle Alert uses the first word to identify which valid response it is. In the original alert message, Oracle Alert displays the text of every valid response you define.

   Important: Your response must not include a blank line, so limit your response to one paragraph. Oracle Alert interprets a blank line as the end of the response.

4. If you want the respondent to specify a particular value for a response variable in her/his response, enter the response variable in the Text field, followed by an equal sign and a question mark between a set of quotation marks (="?").

   Note: Including a response variable in your response text is optional.

   For example, suppose you have an alert that sends a message soliciting a reorder quantity from its recipient. You first specify a numeric response variable called &QUANTITY in the alert SQL Select statement and define the variable in the Response Variable window. Then you specify the text of your 'Reorder' valid response as:

    Reorder QUANTITY="?" 
   

   Oracle Alert appends this text to the bottom of your alert message, and expects a response beginning with the word 'Reorder', and including the characters QUANTITY="n", where n is the amount the recipient wants to order. When Oracle Alert performs any actions that include the response variable &QUANTITY, Oracle Alert substitutes the value of n for the response variable.

   Your valid response can include as many response variables as you need.

5. In the Actions block of the Valid Responses window, you assign one or more of the response actions you defined earlier for each of the valid responses that you define in the Responses block.

6. Enter a number in the Seq field representing the sequence in which you want this action to perform relative to the other actions identified for this response.

7. Choose a response action from the list of predefined actions in the Action field. If you select an action that uses alert outputs or response variables that are not defined for this alert or response set, a warning message appears.

8. Check Enabled to enable the action.

9. Enter a current or future date in the End Date field to disable this action by a certain date.

10. Save your work.

11. You can optionally add invalid response actions to your response set by choosing Invalid from the Response Sets window. An invalid response action can be a message action that tells the respondent their reply was not understood.

    The Invalid Response Actions Window

    

12. In the Invalid Response Action window, enter a number in the Seq field representing the sequence in which you want this action to perform relative to the other actions for the invalid response.

13. Choose a response action from the list of predefined actions in the Action field. If you select an action that uses alert outputs or response variables that are not defined for this alert or response set, a warning message appears.

    Note: You can also choose the original alert message action as an Invalid Response Action to resend the original message that asks for a response.

14. Check Enabled to enable the action.

15. Enter a current or future date in the End Date field to disable this action by a certain date.

16. Save your work.

17. You can also optionally choose None from the Response Sets window to add No Response follow-up actions for Oracle Alert to perform if the recipient does not respond at all.

    Note: You must run the No Response Action Processor concurrent program to check for alert messages whose specified response days have passed without receiving a valid response. See: Processing No Response Actions.

    The No Response Actions Window

    

18. The No Response Actions window is similar to the Invalid Response Actions window. Follow the same steps to define a no response follow-up action.

To attach the response set to the alert message action

1. For Oracle Alert to perform response processing on an alert, you must attach your response set to a message action. Go to the Actions window in the Alerts form.

2. Display the Action Details window for the message action that you want to use to solicit a response.

   The Action Details Window

   

3. In the Response Set field, enter the name of your response set. Oracle Alert uses this response set to compose the response template that it appends to this message and to process the responses it receives for this message.

   You cannot remove a response set from a message action if there is an outstanding response.

4. In the Response Days field, specify the number of days that you want Oracle Alert to wait before it performs the no response follow-up actions defined in your response set for each outstanding exception.

   For example, suppose you enter 1 in this field. Oracle Alert waits one full day after sending the message for a response from the original message recipient. If no response is received, it performs the no response action the first time the No Response Action Processor runs on the following day. The default value for this field is 7 days. If you leave this field blank, Oracle Alert never performs the no response actions on the outstanding responses.

5. Save your work. Your response processing alert is ready for use.

To delete a response set

1. Display the existing response set in the Response Sets window of the Alerts form.

2. Choose Delete Record from the Edit menu.

3. If the response set is attached to a message action, an error message followed by a References window appears.

   The References Window

   

   You can also choose References from the Tools menu in the Response Sets window at any time to display the References window.

4. The References window shows you which actions reference the current response set.

   You must navigate to the Action Details window and remove the response set from the message action that references the response set before you can delete the response set.

5. Once you delete your response set, save your changes.

   Note: You also cannot delete a response set if it has outstanding responses.

Related Topics

Creating a Periodic Alert

Creating an Event Alert

Creating Alert Actions

Creating an Action Set for an Alert

Responding to an Alert Message

When Oracle Alert sends the original alert message action that solicits a response, it automatically appends a unique identifier - a message handle - to the end of the message. Oracle Alert uses this message handle to identify responses to the message. If a response does not include the original message (with its message handle), Oracle Alert cannot perform any of the response actions for that alert. See: Message Handles.

To respond to an alert message

1. Use your mail program to reply to the alert message action.

   Important: You must use Reply-with-Original or Forward to include the original message and message handle with your response, for Oracle Alert to locate the message handle and interpret the response.

2. Your response must match one of the possible valid responses listed in the original message action for Oracle Alert to recognize it as a valid response.

3. Oracle Alert considers any message that contains the appropriate message handle and that does not match one of the possible valid responses, an invalid response.

4. If the original message action includes a response variable as part of the valid response text, Oracle Alert expects you to supply a response variable value in your reply. For example, if the valid response text is:

    Print at PRINTER="?" 
   

   You need to reply with the exact same text, but replace the question mark with the value you want Oracle Alert to use. For example:

    Print at PRINTER="UNX138"
   

5. If you do not supply a response variable value, Oracle Alert uses the default value assigned to the response variable. If a default value was not assigned to the response variable, Oracle Alert performs the response action, but without using a response variable value.

   Important: Oracle Alert identifies response variables in the text of a response by the word that immediately precedes the equal sign (=) in the text. Oracle Alert cannot identify a response variable if no equal sign follows it. If the respondent supplies a response variable value, but does not include the response variable itself, Oracle Alert cannot process the response.

How Oracle Alert Processes Responses

Oracle Alert leverages the Workflow Notification Mailer to send alert e-mail messages and process responses.

Processing Responses with the Workflow Notification Mailer

The Workflow Notification Mailer is a Java program provided by Oracle Workflow that performs e-mail send and response processing using the JavaMail API. Oracle Alert leverages the Workflow Notification Mailer to send alert e-mail messages and process responses.

Before implementing Oracle Alert response processing, check that the Workflow Notification Mailer is set up and that its configuration meets your alert requirements. In particular, ensure that the Workflow Notification Mailer has inbound processing enabled and has an e-mail account for receiving messages on an IMAP4 compliant mail server. You may also want to check that the From and Reply-to Address mailer configuration parameters are set to appropriate values for alert messages. See: Setting Up a Notification Mailer, Oracle Workflow Administrator's Guide.

The Workflow Notification Mailer uses three folders in its e-mail account for response processing: one to receive incoming messages, one to store processed messages, and one to store discarded messages. When the Workflow Notification Mailer logs into its IMAP e-mail account, it checks the inbox folder for messages. If a message exists, the notification mailer reads the message, checking for an identifying string called the notification ID (NID) line. If the NID line contains an Oracle Alert message handle, the Workflow Notification Mailer identifies the e-mail as an alert response message. See: Message Handles.

Important: An alert recipient must use Reply-with-Original or Forward to include the original message with her or his response so that Oracle Workflow and Oracle Alert can locate the message handle and interpret the response.

The Workflow Notification Mailer also verifies that From address of the response message matches the e-mail address for the recipient of the original alert. Otherwise, the notification mailer moves the message to the discard folder and treats it as an unsolicited message. In some cases the notification mailer sends a warning back to the sender of the response message. For more information about how the notification mailer handles unsolicited messages, see: Inbound Notification Mailer Processing, Oracle Workflow Administrator's Guide.

The Workflow Notification Mailer uses a Java-based e-mail parser to interpret the text of the message and create an XML representation of it. Then the Workflow Notification Mailer places the XML message, in the form of a business event called oracle.apps.alr.response.receive, on an Oracle Workflow Business Event System agent called WF_NOTIFICATION_IN. Finally, the notification mailer moves the e-mail message to its processed folder.

Note: If the parser finds a string of text in the message that matches a tag pattern specified in the mailer configuration parameters, the Workflow Notification Mailer immediately moves the message to the discard folder instead. You can use tags to identify unusual messages such as bounced, returned, or auto-reply messages in order to skip unnecessary invalid response processing and avoid a perpetual loop of invalid warning messages and bounced or auto-reply messages. See: Tags, Oracle Workflow Administrator's Guide.

Oracle Workflow provides an agent listener named Workflow Inbound Notifications Agent Listener that runs on the WF_NOTIFICATION_IN agent to continue processing for messages placed on that agent. When the Workflow Inbound Notifications Agent Listener dequeues an oracle.apps.alr.response.receive event message from WF_NOTIFICATION_IN, it executes a seeded Oracle Alert subscription that processes the response.

Oracle Alert reads the XML response message and tries to match the first word or the first 30 continuous characters of the response to any of the defined valid responses. After determining whether the response is valid or invalid, Oracle Alert submits the Alert Action Processor concurrent program to perform the appropriate actions. See: Processing Alert Response Actions.

If the actual response matches a valid response, then the Alert Action Processor performs the actions defined for that valid response. After the Alert Action Processor performs the actions for that valid response, Oracle Alert closes the response so that no other responses are processed for that message.

If the actual response does not match any of the valid responses in that response set, the Alert Action Processor performs the actions associated with the invalid response. The Alert Action Processor performs the invalid response actions each time Oracle Alert receives an invalid response within the response days specified in the original message action.

You must run the No Response Action Processor concurrent program to check for alert messages whose specified response days have passed without receiving a valid response. After the specified response days have passed, if Oracle Alert never received any response to the alert message or if it received only invalid responses, the No Response Action Processor performs the no response follow-up actions for each message and closes responses for all messages in that response set. See: Processing No Response Actions.

Oracle Alert Response Processing Receive Event

The Workflow Notification Mailer uses this event to handle an incoming alert response message.

Variable	Description
Internal Name	oracle.apps.alr.response.receive
Status	Enabled
Owner Name	Oracle Alert
Owner Tag	ALR
Customization Level	Limit

Oracle Alert provides one default subscription to the oracle.apps.alr.response.receive event. When this event is received, this subscription processes the response and performs the appropriate actions as specified in the alert definition. The subscription is enabled by default. The following table lists the properties defined for this subscription.

Subscription Properties

Subscription Property	Value
System	<local system>
Source Type	External
Event Filter	oracle.apps.alr.response.receive
Phase	50
Status	Enabled
Rule Data	Key
Action Type	Custom
On Error	Stop and Rollback
PL/SQL Rule Function	alr_mlr_package.response
Priority	Normal
Owner Name	Oracle Alert
Owner Tag	ALR
Customization Level	Limit

Message Handles

By uniquely identifying each message that is associated with a response set, Oracle Alert can determine which response set a message is linked to, and perform the appropriate response actions.

Oracle Alert automatically attaches a message handle - a unique identifier - to each message that is associated with a response set. A message handle is composed of a number that identifies the Oracle Alert installation where the message originated, and a number that identifies the message itself. The format of a message handle as it appears in an alert message is:

<Oracle_Alert_installation_number>.<message_number>.<Oracle_ID>.<organization_ID> 

For example:

2.347.3.5

The message handle is visible to the message recipient as a number at the end of the message.

Note: The Oracle Alert installation number, which you can review in the Response Processing tabbed region of the Oracle Alert Options form, is set to 1 by default.

In an alert message sent by the Workflow Notification Mailer, the message handle is included within an identifying string called the notification ID (NID) line. The NID line uses the following format:

NID[<message_handle>/0000@<mailer_node_name>]

where <message_handle> is the Oracle Alert message handle and <mailer_node_name> is the mailer node name used to identify the notification mailer that should process the message.

Response Processing History

You can review a complete record of the exceptions found and response actions performed in Oracle Alert, if you save history for your response processing alert. When you define a response processing alert, the value you enter in the Keep _ Days field of the Alerts form determines the amount of history you save. The number you enter in this field should be in addition to the number of response days you enter in the Action Details block of the Actions window.

For example, if you want Oracle Alert to save history for 7 days after it performs the response actions, enter 7 plus the number of follow-up response days you specified for the alert message.

Related Topics

Overview of Oracle Alert History

Reviewing Alert Exceptions

Reviewing Alert Actions

Defining a Response Processing Alert

How Oracle Alert Checks Alerts