The Oracle Workflow Business Event System requires agent listeners to be scheduled to receive inbound event messages. An agent listener monitors a Business Event System agent for incoming messages and dequeues messages using the agent's queue handler. You should run agent listeners for your local inbound agents.
When an event message is dequeued, the Event Manager begins subscription processing for the event. The Event Manager searches for and executes any active subscriptions by the local system to that event with a source type of External, and also any active subscriptions by the local system to the Any event with a source type of External.
The agent listener exits after all event messages on the agent's queue have been dequeued.
The agent listener program is defined as a service component type in the Generic Service Component Framework. This framework helps to simplify and automate the management of background Java services.
Oracle Workflow provides three seeded agent listener service components to process messages on the standard WF_DEFERRED, WF_ERROR, and WF_NOTIFICATION_IN agents. These service components are named Workflow Deferred Agent Listener, Workflow Error Agent Listener, and Workflow Inbound Notifications Agent Listener, and they support deferred subscription processing, error handling for the Business Event System, and inbound e-mail processing for notification mailers, respectively. The configuration parameters for the seeded agent listeners are set to default values which you cannot update. However, you can schedule control events or manually choose control commands to start, stop, suspend, resume, or refresh the agent listeners. When running, the seeded agent listeners will check their agents for messages every five minutes.
You can also optionally create additional agent listener service components. For example, you can configure agent listeners for other inbound agents that you want to use for event message propagation, such as the standard WF_IN and WF_JMS_IN agents, or any custom agents. You can also configure an agent listener that only processes messages on a particular agent that are instances of a specific event.
Before agent listener service components can run, the container which manages them, named Workflow Agent Listener Service, must be first be started. You should ensure that this container is running. Use the Service Instances page to start the container as a service instance in Generic Service Management (GSM). When the Workflow Agent Listener Service container is running, it automatically starts the Workflow Deferred Agent Listener, Workflow Error Agent Listener, and Workflow Inbound Notifications Agent Listener.
The agent listener configuration wizard lets you configure an agent listener service component by defining general and detail attributes and scheduling control events. You can use the configuration wizard to configure a new agent listener service component, or to edit the configuration of an existing agent listener service component.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > (B) Create > (B) Create Service Component
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > (B) Edit
This page lets you define general attributes for the agent listener. Some attributes are already set to required values and cannot be modified. You must set attributes marked with an asterisk (*) to appropriate values for your environment before you can run the agent listener.
ID - When you edit a previously created agent listener service component, the configuration wizard displays the identifier for the service component.
Status - When you edit a previously created agent listener service component, the configuration wizard displays the status of the service component.
Name - The name of the agent listener service component. This name must be unique.
The three seeded agent listeners are named Workflow Deferred Agent Listener, Workflow Error Agent Listener, and Workflow Inbound Notifications Agent Listener.
Startup Mode - Select Automatic, Manual, or On-Demand as the startup mode for the service component. The three seeded agent listeners all use the Automatic startup mode.
Container Type - The container type to which this service component belongs. In Oracle Applications, the container type is always Oracle Applications Generic Service Management (Oracle Applications GSM).
Inbound Agent - The Business Event System agent that you want to monitor for inbound event messages. The inbound agents for the seeded agent listeners are:
Workflow Deferred Agent Listener - WF_DEFERRED
Workflow Error Agent Listener - WF_ERROR
Workflow Inbound Notifications Agent Listener - WF_NOTIFICATION_IN
Outbound Agent - Leave this field blank. Agent listener service components do not use an outbound agent.
Correlation ID - Optionally specify the Oracle Advanced Queuing (AQ) correlation ID of the event messages that you want the agent listener to process. The AQ correlation ID for an event message in the Business Event System is usually specified in the following format:
<event name>
Consequently, by specifying a correlation ID in this attribute, you can dedicate the agent listener to listen only for messages that are instances of the specifed event. You can also specify a partial value to listen for messages that are instances of any event whose name begins with the specified value.
The three seeded agent listeners do not have any correlation ID specified so that they can process all event messages on their respective agents.
Note: The AQ correlation ID is different than the correlation ID contained within the WF_EVENT_T event message structure.
To cancel the configuration without saving any changes, click the Cancel button.
To save these settings and proceed to the next step of the agent listener configuration wizard, click the Next button.
To save these settings and proceed to the last step of the agent listener configuration wizard, click the Finish button.
This page lets you define detail attributes for the agent listener.
ID - When you edit a previously created agent listener service component, the configuration wizard displays the identifier for the service component.
Status - When you edit a previously created agent listener service component, the configuration wizard displays the status of the service component.
Name - The configuration wizard displays the name defined for the agent listener service component.
Container - The container to which the service component will belong. The container for agent listener service components must always be a predefined container provided by Oracle Workflow called Workflow Agent Listener Service.
Maximum Idle Time - If you selected the On-Demand startup mode for the service component, enter the maximum time in minutes that the service component can remain idle before it is stopped. An on-demand component that is stopped in this way will be restarted by its container when it is needed again to process new messages.
To cancel any changes on this page, click the Cancel button.
To return to the previous step of the agent listener configuration wizard, click the Back button.
To save these settings and proceed to the next step of the agent listener configuration wizard, click the Next button.
To save these settings and proceed to the last step of the agent listener configuration wizard, click the Finish button.
This page lets you schedule events to control the running of the agent listener service component. The events are raised at the scheduled time by DBMS jobs. For an agent listener service component, you can schedule the following events:
Start
Refresh
Suspend
Resume
Stop
For each event, the list displays the event name, date and time when the event is first scheduled to be raised, the interval in minutes at which the event is reraised, and, for a refresh event, any parameters to be refreshed.
If no events are currently scheduled, click the Add a Row button to add a new row to the list of events and enter the information for the event.
Select the event for the command you want to schedule. Oracle Workflow provides events to let you start, stop, refresh, suspend, or resume the agent listener.
Select the date when you want the event to be raised first.
Select the hour and minute to specify the time on the specified date when you want the event to be raised first. The hour values are in a twenty-four hour format. For example, select 00 for midnight, or 23 for 11 PM.
If you want to raise the event periodically, enter the time interval in minutes at which you want to raise the event. If you do not specify a repeating interval, the event is raised only once.
If you choose the refresh event, you can optionally enter any parameters you want to include with the event in order to refresh the agent listener configuration parameters with those values when the event is raised. Specify the parameter names and values in the following format, separating the parameters with a colon (:): internal_parameter_name=parameter_value
To schedule another event, click the Add Another Row button and enter the information for the event.
To remove an event, select the event and click the Remove button.
To cancel any changes on this page, click the Cancel button.
To return to the previous step of the agent listener configuration wizard, click the Back button.
To save these settings and proceed to the next step of the agent listener configuration wizard, click the Next button.
To save these settings and proceed to the last step of the agent listener configuration wizard, click the Finish button.
Note: The configuration wizard verifies that an event is specified for every row in the list when you click the Next or Finish button. If you do not want to schedule another event, you should remove any empty rows before proceeding.
This page lets you review the configuration parameter values that you set and the events that you scheduled for this agent listener service component.
To return to the page from which you accessed the agent listener configuration wizard, click the Cancel button.
If you want to change any of these settings, return to the appropriate step in the agent listener configuration wizard to make your changes. To return to the previous step, click the Back button.
To save these settings and finish the configuration, click the Finish button.
The Component Details page lets you review the configuration and control the running of an agent listener service component.
Navigation: Applications Dashboard > (pull-down menu) Workflow Manager > (B) Go > Service Components status icon > (B) View Details
To add the information from this page to your support cart, click the Add to Support Cart button.
To delete this agent listener, click the Delete button.
Note: You cannot delete the seeded Workflow Deferred Agent Listener, Workflow Error Agent Listener, or Workflow Inbound Notifications Agent Listener components. If you want to disable them, you can stop them manually using the Stop command from the command pull-down menu. However, note that stopping the Workflow Deferred Agent Listener disables deferred subscription processing for the Business Event System; stopping the Workflow Error Agent Listener disables error handling for the Business Event System; and stopping any of the three seeded agent listeners disables parts of the notification processing performed by notification mailers.
To review the events that have been scheduled to control the running of the agent listener, click the View Event History button. For each event, the Event History page displays the event name, status, user who requested the event, component status before the event was processed, date the event processing was completed, container for the service component, container type, and any event parameters for a refresh event. You can use this event history as an audit trail to review who scheduled control events for the agent listener. The status of an event may be Pending, Skipped, In Progress, Completed, or Error. In some cases, an event may be skipped if the component is not in an appropriate status at the time for which the event is scheduled. For example, a refresh event cannot be executed if the component is stopped at the scheduled time.
To view the diagnostic log of the Generic Service Management (GSM) service component container in which this agent listener is running, click the View Log button. The log includes log messages for this component and any other component belonging to that container.
To manually control the running of the agent listener service component,
choose the command you want from the command pull-down menu,
and click the Go button. You can choose the following commands:
Refresh
Resume
Start
Stop
Suspend
The Component Details page displays the configuration parameters defined for the agent listener. If you want to change the value of any parameter, edit the configuration using the agent listener configuration wizard.
The Component Details page also displays the control events that are currently scheduled for the agent listener. For each event, the list shows the event name, initial start time, whether the event is currently running, the next scheduled execution time for a repeating event, the last previous execution time for a repeating event, the interval in minutes between executions of a repeating event, the number of times the event has failed, the job ID of the DBMS job used to schedule the event, and the PL/SQL API that DBMS job runs.