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 propagation by scheduling listeners for local inbound agents and propagations for local outbound agents. See: Scheduling Listeners for Local Inbound Agents and Scheduling Propagations for Local Outbound Agents.

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 either use AQ itself to perform the propagation of messages by the SQLNET protocol which it supports, or you can implement an external service, such as Oracle Message Broker, to propagate messages by a different protocol.

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 Define 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 ORA816.US.ORACLE.COM, you must enter that complete name in the address of an agent on that database. You cannot abbreviate the name to ORA816.

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.

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. You must assign each agent a PL/SQL package called a queue handler that translates between this standard Workflow format and the format required by the agent's queue. See: Event Message Structure.

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 queue handler called WF_EVENT_OMB_QH, which you can use if you implement Oracle Message Broker to propagate messages between systems by another protocol such as HTTP. See: Setting Up the WF_EVENT_OMB_QH Queue Handler and Mapping Between WF_EVENT_T and OMBAQ_TEXT_MSG.

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.

Standard Agents

• WF_IN--Standard inbound agent

• WF_OUT--Standard outbound agent

• WF_ERROR--Standard agent for error handling

You can enable or disable the WF_IN, WF_OUT, and WF_ERROR agents, but you must not make any other changes to their definitions. However, you must schedule a listener for the WF_ERROR agent to enable error handling for the Business Event System. Also, if you want to use the WF_IN and WF_OUT agents for event message propagation, schedule a listener for WF_IN and a propagation for WF_OUT as well. See: Scheduling Listeners for Local Inbound Agents and Scheduling Propagations for Local Outbound Agents.

The standard agents have the following default properties:

WF_IN

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

WF_OUT

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

WF_ERROR

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_EVENT_QH
Queue Name	<workflow schema>.WF_ERROR
Direction	In
Status	Enabled

See Also

To Find Agents

To Update or Delete an Agent