Previous	Next		Contents	Index	Glossary

You should define each agent that you will use to communicate events in the Event Manager. Each agent's name must be unique within its system. The agent can be referenced in code within Oracle Workflow by a compound name in the following format:

<agent_name>@<system_name>

For example, the agent WF_IN within the system HUB could be referenced as WF_IN@HUB.

After defining the agents on your local system, you should set them up for event message communication by scheduling agent listeners for local inbound agents and propagation for local outbound agents. You can use Oracle Enterprise Manager to schedule propagation and the Workflow Manager component of Oracle Applications Manager to run agent listeners. In Oracle Workflow Manager you can also view the distribution of event messages on different agents, drill down to view details about individual event messages, and review queue details for the agents. For more information, please refer to the Oracle Applications Manager online help, Oracle Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference, Distributed Management, Oracle Enterprise Manager Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.

You can run a diagnostic test through Oracle Diagnostics to verify the status of your agents. See: Oracle Workflow Diagnostic Tests, Oracle Workflow Administrator's Guide.

Assigning a Direction to an Agent

• In--Inbound communication to the system. The agent receives messages in a specific protocol and presents them to the system in a standard format.

• Out--Outbound communication from the system. The agent accepts messages from the system in a standard format and sends them using the specified protocol.

Assigning a Protocol to an Agent

A protocol can represent a network standard, such as SQLNET. It can also represent a business-to-business standard that defines the higher-level message format and handshaking agreements between systems in addition to the network standard.

The Business Event System interacts with an agent through an AQ queue. You can use AQ to perform the propagation of messages by the SQLNET protocol which it supports. In Oracle9i Database and higher, AQ also includes Internet access functionality that lets you perform AQ operations over the Internet by using AQ's Internet Data Access Presentation (IDAP) for messages and transmitting the messages over the Internet using transport protocols such as HTTP or HTTPS. Additionally, the Messaging Gateway feature of AQ in Oracle9i Database and higher enables communication between applications based on non-Oracle messaging systems and AQ, letting you integrate with third party messaging solutions. You can also implement other services to propagate messages by different protocols.

To implement a custom protocol, you must perform the following steps:

1. Define AQ queues to hold pending inbound and outbound messages.

2. Provide code that propagates messages to and from the AQ queues.

3. Define a lookup code for the new protocol in the Event Protocol Type (WF_AQ_PROTOCOLS) lookup type, which is stored in the Standard item type. The Event Manager uses the Event Protocol Type lookup type to validate the protocol for an agent. See: To Create Lookup Codes for a Lookup Type.

4. Define agents with the new protocol. See: To Create or Update an Agent.

<schema>.<queue>@<database link>

In this format, <schema> represents the schema that owns the queue, <queue> represents the queue name, and <database link> represents the name of the database link to the instance where the queue is located.

Note: You must enter the database link name exactly as the name was specified when the database link was created. For example, if a database link is named ORA10.US.ORACLE.COM, you must enter that complete name in the address of an agent on that database. You cannot abbreviate the name to ORA10.

The names of the database links that you want to use for the Business Event System should be fully qualified with the domain names. To confirm the names of your database links, use the following syntax:

			SELECT db_link FROM all_db_links

See: Creating Database Links, Oracle Workflow Administrator's Guide.

Assigning a Queue to an Agent

Event messages within the Oracle Workflow Business Event System are encoded in a standard format defined by the datatype WF_EVENT_T, or, in Java, the BusinessEvent object. You should assign each agent a PL/SQL or Java package called a queue handler that translates between the standard Workflow format and the format required by the agent's queue. Define only one queue handler for an agent, either PL/SQL or Java. See: Event Message Structure, Oracle Workflow API Reference.

Note: Even if the agent's queue uses WF_EVENT_T as its payload type, a queue handler is still required in order to set native AQ message properties.

Oracle Workflow provides two standard queue handlers, called WF_EVENT_QH and WF_ERROR_QH, for queues that use SQLNET propagation and use the WF_EVENT_T datatype as their payload type. You can use WF_EVENT_QH with queues that handle normal Business Event System processing, while WF_ERROR_QH should be used exclusively with error queues.

Oracle Workflow also provides a standard queue handler called WF_EVENT_OJMSTEXT_QH for queues that use the SYS.AQ$_JMS_TEXT_MESSAGE datatype as their payload type. This queue handler enables communication of JMS Text messages through the Business Event System. See: Mapping Between WF_EVENT_T and SYS.AQ$_JMS_TEXT_MESSAGEE, Oracle Workflow API Reference.

If you want to use queues that require a different format, create a custom queue handler for that format. Your custom queue handler must include a set of standard APIs to enqueue and dequeue messages in the custom format. See: Standard APIs for a Queue Handler.

• If you define a PL/SQL queue handler, then you can run both PL/SQL and Java agent listeners on this agent. The PL/SQL queue handler is used during both Java and PL/SQL event message processing. Java agent listeners will execute the PL/SQL queue handler through Java Database Connectivity (JDBC).

• If you define a Java queue handler, then you can run only Java agent listeners on this agent. The Java queue handler is used during Java event message processing. You cannot run a PL/SQL agent listener on this agent, because a PL/SQL agent listener cannot execute a Java queue handler.

Agent Groups

Agent groups can only be used for inbound communication. All agent groups have a direction of In, and only individual agents with a direction of In can be members of an agent group.

You must associate each agent group with a system to which it belongs. However, you can include agents on other systems within the group.

Ensure that you run an agent listener for each agent within the group to receive inbound messages.

Note: You cannot run an agent listener for an agent group. Agent listeners can be run only for individual agents.

Standard Agents

• WF_CONTROL - Oracle Workflow internal agent, not for customer use

• WF_DEFERRED - Standard agent for deferred subscription processing in the database

• WF_ERROR - Standard agent for error handling in the database

• WF_JAVA_DEFERRED - Standard agent for deferred subscription processing in the middle tier

• WF_JAVA_ERROR - Standard agent for error handling in the middle tier

• WF_IN - Default inbound agent

• WF_JMS_IN - Default inbound agent for JMS Text messages

• WF_JMS_OUT - Default outbound agent for JMS Text messages

• WF_NOTIFICATION_IN - Standard inbound agent for e-mail notification responses

• WF_NOTIFICATION_OUT - Standard outbound agent for e-mail notifications

• WF_OUT - Default outbound agent

• WF_WS_JMS_IN - Default inbound agent for Web service messages

• WF_WS_JMS_OUT - Default outbound agent for Web service messages

You can enable or disable the WF_IN, WF_JMS_IN, WF_WS_JMS_IN, WF_OUT, WF_JMS_OUT, and WF_WS_JMS_OUT agents, but you must not make any other changes to their definitions. You must not make any changes to the definitions of the other agents.

Oracle Workflow automatically runs PL/SQL agent listeners for the standard WF_DEFERRED, WF_ERROR, and WF_NOTIFICATION_IN agents in order to perform deferred subscription processing, error handling for the Business Event System, and inbound e-mail processing for notification mailers, respectively. Oracle Workflow also automatically runs Java agent listeners for the standard WF_JAVA_DEFERRED and WF_JAVA_ERROR agents in order to perform deferred subscription processing and error handling in the middle tier. Additionally, Oracle Workflow provides a Java agent listener named Web Services IN Agent that you can optionally start for the WF_WS_JMS_IN agent. If you want to use the WF_IN and WF_JMS_IN agents for event message propagation, schedule listeners for those agents as well.

Likewise, if you want to use the WF_OUT and WF_JMS_OUT agents for event message propagation, schedule propagation for those agents. You do not need to schedule propagation for the WF_CONTROL, WF_NOTIFICATION_OUT, or WF_WS_JMS_OUT agents, however. The middle tier processes that use WF_CONTROL dequeue messages directly from its queue, and notification mailers send messages placed on the WF_NOTIFICATION_OUT queue. For WF_WS_JMS_OUT, you can optionally start a Web services outbound component named Web Services OUT Agent, provided by Oracle Workflow. For more information, please refer to the Oracle Applications Manager online help, Oracle Enterprise Manager online help, Oracle Enterprise Manager Support, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference, Distributed Management, Oracle Enterprise Manager Administrator's Guide, and Setting Up the Business Event System, Oracle Workflow Administrator's Guide.

You can run a diagnostic test through Oracle Diagnostics to verify that the WF_DEFERRED queue and the WF_ERROR each have only one subscriber rule defined. No custom subscribers should be added to these queues. See: Oracle Workflow Diagnostic Tests, Oracle Workflow Administrator's Guide.

Note: Oracle Workflow also includes three additional agents named WF_REPLAY_IN, WF_REPLAY_OUT, and WF_SMTP_O_1_QUEUE, which are not currently used.

The following table lists the default properties for the standard WF_CONTROL agent. See: Cleaning Up the Workflow Control Queue, Oracle Workflow Administrator's Guide.

Agent Property	Value
Name	WF_CONTROL
Display Name	Workflow Control Out Queue
Description	Workflow JMS Text Message Queue used to signal messages to middle tier processes
Protocol	SQLNET
Address	<workflow schema>.WF_CONTROL@<local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_CONTROL
Direction	Out
Status	Enabled

The following table lists the default properties for the standard WF_DEFERRED agent.

Agent Property	Value
Name	WF_DEFERRED
Display Name	WF_DEFERRED
Description	WF_DEFERRED
Protocol	SQLNET
Address	<workflow schema>.WF_DEFERRED@<local database>
System	<local system>
Queue Handler	WF_EVENT_QH
Queue Name	<workflow schema>.WF_DEFERRED
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_ERROR agent.

Agent Property	Value
Name	WF_ERROR
Display Name	WF_ERROR
Description	WF_ERROR
Protocol	SQLNET
Address	<workflow schema>.WF_ERROR@<local database>
System	<local system>
Queue Handler	WF_ERROR_QH
Queue Name	<workflow schema>.WF_ERROR
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_JAVA_DEFERRED agent.

Agent Property	Value
Name	WF_JAVA_DEFERRED
Display Name	Workflow Java Deferred In Queue
Description	Workflow Java Deferred In Queue
Protocol	SQLNET
Address	<workflow schema>.WF_JAVA_DEFERRED@ <local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_JAVA_DEFERRED
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_JAVA_ERROR agent.

Agent Property	Value
Name	WF_JAVA_ERROR
Display Name	Workflow Java Error In Queue
Description	Workflow Java Error In Queue
Protocol	SQLNET
Address	<workflow schema>.WF_JAVA_ERROR@<local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_JAVA_ERROR
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_IN agent.

Agent Property	Value
Name	WF_IN
Display Name	WF_IN
Description	WF_IN
Protocol	SQLNET
Address	<workflow schema>.WF_IN@<local database>
System	<local system>
Queue Handler	WF_EVENT_QH
Queue Name	<workflow schema>.WF_IN
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_JMS_IN agent.

Agent Property	Value
Name	WF_JMS_IN
Display Name	Workflow JMS In Queue
Description	Workflow JMS Text Message Queue
Protocol	SQLNET
Address	<workflow schema>.WF_JMS_IN@<local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_JMS_IN
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_JMS_OUT agent.

Agent Property	Value
Name	WF_JMS_OUT
Display Name	Workflow JMS Out Queue
Description	Workflow JMS Text Message Queue
Protocol	SQLNET
Address	<workflow schema>.WF_JMS_OUT@<local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_JMS_OUT
Direction	Out
Status	Enabled

The following table lists the default properties for the standard WF_NOTIFICATION_IN agent. See: Implementing Notification Mailers, Oracle Workflow Administrator's Guide.

Agent Property	Value
Name	WF_NOTIFICATION_IN
Display Name	Workflow Notification In Queue
Description	Workflow inbound notification response queue
Protocol	SQLNET
Address	<workflow schema>.WF_NOTIFICATION_IN@ <local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_NOTIFICATION_IN
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_NOTIFICATION_OUT agent. See: Implementing Notification Mailers, Oracle Workflow Administrator's Guide.

Agent Property	Value
Name	WF_NOTIFICATION_OUT
Display Name	Workflow Notification Out Queue
Description	Workflow notification outbound queue
Protocol	SQLNET
Address	<workflow schema>.WF_NOTIFICATION_OUT@ <local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_NOTIFICATION_OUT
Direction	Out
Status	Enabled

The following table lists the default properties for the standard WF_OUT agent.

Agent Property	Value
Name	WF_OUT
Display Name	WF_OUT
Description	WF_OUT
Protocol	SQLNET
Address	<workflow schema>.WF_OUT@<local database>
System	<local system>
Queue Handler	WF_EVENT_QH
Queue Name	<workflow schema>.WF_OUT
Direction	Out
Status	Enabled

The following table lists the default properties for the standard WF_WS_JMS_IN agent.

Agent Property	Value
Name	WF_WS_JMS_IN
Display Name	WebServices JMS In Queue
Description	WebServices JMS Text Message Queue for Inbound
Protocol	SOAP
Address	<workflow schema>.WF_WS_JMS_IN@<local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_WS_JMS_IN
Direction	In
Status	Enabled

The following table lists the default properties for the standard WF_WS_JMS_OUT agent.

Agent Property	Value
Name	WF_WS_JMS_OUT
Display Name	WebServices JMS Out Queue
Description	WebServices JMS Text Message Queue for Outbound
Protocol	SOAP
Address	<workflow schema>.WF_WS_JMS_OUT@<local database>
System	<local system>
Queue Handler	WF_EVENT_OJMSTEXT_QH
Queue Name	<workflow schema>.WF_WS_JMS_OUT
Direction	Out
Status	Enabled

Agents on External Systems

For communication between two systems that both have Oracle Workflow installed, Oracle Workflow provides an external system registration procedure that you can use to automatically copy the inbound agent definitions for the other system into the Event Manager of your local system. See: Registering External Systems.

If your local Workflow-enabled system will communicate with a non-Workflow system, the non-Workflow system must provide its own external propagation agents to handle Business Event System event messages.

• An inbound agent on a non-Workflow system must be able to dequeue event messages from a Business Event System outbound queue and process the contents of those messages. The inbound agent must have an address at which systems can communicate with the agent.

• An outbound agent on a non-Workflow system must be able to enqueue event messages in the appropriate format on a Business Event System inbound queue.

1. Before defining agents for a non-Workflow system, you must define the system itself using the Create System page. See: To Create or Update a System.

2. You can then use the Create Agent page to define an agent for the non-Workflow system, following the same steps as for any other agent. See: To Create or Update an Agent.

• You must associate the agent with the non-Workflow system to which it belongs.

• You must specify the protocol by which you will communicate with the agent.

• For an inbound agent, you must also specify the address at which you will communicate with the agent.

• You can leave the queue name and queue handler blank if the agent is not implemented as an Oracle Advanced Queueing queue.

See Also

To Create or Update an Agent

To Create or Update an Agent Group