Oracle Workflow Guide
Release 2.6.2

Part Number A95265-03
  Go to previous page Go to next page       Go To Table Of Contents Go To Index Go To Table Of Contents

                     Contents  Index  Glossary Master Index Feedback


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:


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

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, 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 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.

Database Version SQLNET Protocol HTTP/HTTPS Protocols Integration with Third Party Messaging Solutions
Oracle8i Oracle Advanced Queuing Oracle Message Broker Oracle Message Broker
Oracle9i Oracle Advanced Queuing Oracle Advanced Queuing Oracle Advanced Queuing Messaging Gateway feature

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.

Assigning a Queue to an Agent

You must associate each agent 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 queue listener on the queue.

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 with Oracle8i 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

When you install Oracle Workflow, four 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.

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

However, you must schedule listeners for the WF_DEFERRED and WF_ERROR agents to enable deferred subscription processing and error handling for the Business Event System, respectively. Also, if you want to use the WF_IN and WF_OUT agents for event message propagation, schedule a listener for WF_IN and propagations for WF_OUT as well. See: Scheduling Listeners for Local Inbound Agents and Scheduling Propagations for Local Outbound Agents.

Additionally, a standard agent named WF_SMTP_O_1_QUEUE is defined for the Notification Mailer SMTP queue. This agent appears in the Check Setup page and the Event System Local Queues page, enabling you to use these pages to check the number of notification messages on the Notification Mailer queue. The WF_SMTP_O_1_QUEUE agent is not used by the Business Event System, however, so its status is Disabled and no queue handler is defined for it. You must not run an agent listener for this agent. See: Implementing the Notification Mailer, Checking the Business Event System Setup, and Reviewing Local Queues.

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_OUT agent.

Agent Property Value
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_DEFERRED agent.

Agent Property Value
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
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_SMTP_O_1_QUEUE agent.

Agent Property Value
Display Name WF_SMTP_O_1_QUEUE
Description This is the Mailer Queue - do not submit the Agent Listener Concurrent Program on this Agent.
Protocol SQLNET
Address <workflow schema>.WF_SMTP_O_1_QUEUE @<local database>
System <local system>
Queue Handler  
Queue Name <workflow schema>.WF_SMTP_O_1_QUEUE
Direction In
Status Disabled

See Also

To Define an Agent

To Find Agents

To Update or Delete an Agent

         Previous  Next          Contents  Index  Glossary

Copyright © 1996, 2002 Oracle Corporation.

All Rights Reserved.