Previous	Next		Contents	Index	Glossary

An agent is a named point of communication within a system. Communication within and between systems is accomplished by sending a message from one agent to another. A single system can have several different agents representing different communication alternatives. For example, a system may have different agents to support inbound and outbound communication, communication by different protocols, different propagation frequencies, or other alternatives.

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. You can also view the distribution of event messages on different agents in Workflow Manager, as well as reviewing queue details for those agents. For more information, please refer to the Oracle Applications 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 also use the Event System Local Queues page to review the local queues used by the Business Event System as well as the messages currently being held on those queues. See: Reviewing Local Queues.

Assigning a Direction to an Agent

When you define an agent in the Event Manager, you must specify the direction of communication that the agent supports on its local system.

Assigning a Protocol to an Agent

You must associate each agent with the protocol by which it communicates messages. The protocol specifies how the messages are encoded and transmitted. For a message to be successfully communicated, the sending and receiving agents must use the same protocol.

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. The following table shows which services you can use for various protocols, depending on your database version.

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

If an agent supports inbound communication, you must specify the address by which systems can communicate with it. The format of the address depends on the agent's protocol. For agents that use the SQLNET protocol, the address must be in the following format to enable AQ propagation:

<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, Oracle Workflow Administrator's Guide.

Assigning a Queue to an Agent

You must associate each agent on a Workflow-enabled system with an AQ queue. The local system uses this queue to interact with the agent. To send messages, the system enqueues the messages on the queue and sets the recipient addresses. To receive messages, the system runs a listener on the queue. See:

Setting Up Queues, Oracle Workflow Administrator's Guide.

Event messages within the Oracle Workflow Business Event System are encoded in a standard format defined by the datatype WF_EVENT_T. You should 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, 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.

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

Agent Groups

You can also define agent groups that let you associate several inbound agents with each other and reference them as a group in event subscriptions and Send event activities. An agent group is a type of agent composed of a set of individual member agents. Once you have defined an agent group, you can send event messages to the group rather than having to send the messages separately to each individual agent within it.

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

When you install Oracle Workflow, several standard agents are automatically defined for the Business Event System.

These agents use standard queues that are automatically defined when you install Oracle Workflow. See: Setting Up Queues, Oracle Workflow Administrator's Guide.

You can enable or disable the WF_IN, WF_JMS_IN, WF_OUT, and WF_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 agent listener service components 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 mailesr, respectively. If you want to use the WF_IN, WF_JMS_IN, WF_OUT, and WF_JMS_OUT agents for event message propagation, schedule listeners for WF_IN and WF_JMS_IN and propagation for WF_OUT and WF_JMS_OUT as well. You do not need to schedule propagation for the WF_CONTROL and WF_NOTIFICATION_OUT agents, however, because 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 more information, please refer to the Oracle Applications 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.

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.

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

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

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

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

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

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

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

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

Agents on External Systems

Systems that will communicate events with each other must store each other's inbound agent definitions in order to address event messages to each other.

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.

You must manually define the inbound agents for an external non-Workflow system in the Event Manager of your local system. You can optionally define the external system's outbound agents as well.

See Also

To Create or Update an Agent

To Create or Update an Agent Group

Copyright © 2003 Oracle Corporation.
All rights reserved.