Workflow Developer Guide

11i/2.6 Workflow BusinessEvent SystemStudent Guide

D11101GC10

Edition 1.0

February 2001

D31495

Copyright © Oracle Corporation, 2001. All rights reserved.

This documentation contains proprietary information of Oracle Corporation. It is provided under a licenseagreement containing restrictions on use and disclosure and is also protected by copyright law. Reverseengineering of the software is prohibited. If this documentation is delivered to a U.S. Government Agency of theDepartment of Defense, then it is delivered with Restricted Rights and the following legend is applicable:

Restricted Rights Legend

Use, duplication or disclosure by the Government is subject to restrictions for commercial computer softwareand shall be deemed to be Restricted Rights software under Federal law, as set forth in subparagraph (c)(1)(ii)of DFARS 252.227-7013, Rights in Technical Data and Computer Software (October 1988).

This material or any portion of it may not be copied in any form or by any means without the express priorwritten permission of the Education Products group of Oracle Corporation. Any other copying is a violation ofcopyright law and may result in civil and/or criminal penalties.

If this documentation is delivered to a U.S. Government Agency not within the Department of Defense, then it isdelivered with “Restricted Rights,” as defined in FAR 52.227-14, Rights in Data-General, including Alternate III(June 1987).

The information in this document is subject to change without notice. If you find any problems in thedocumentation, please report them in writing to Worldwide Education Services, Oracle Corporation, 500 OracleParkway, Box SB-6, Redwood Shores, CA 94065. Oracle Corporation does not warrant that this document iserror-free.

Oracle and all references to Oracle Products are trademarks or registered trademarks of Oracle Corporation.

All other products or company names are used for identification purposes only, and may be trademarks of theirrespective owners.

Author

Clara Jaeckel

Technical Contributors and Reviewers

Mark Craig, Leta Davis, Kevin Hudson

This book was published using:

Oracle Tutor


11i/2.6 Workflow Business Event System Table of Contentsi

Table of Contents

Oracle Workflow Release 2.6................................................................................................1-1Oracle Workflow Release 2.6 ..............................................................................................1-2Objectives ............................................................................................................................1-3Oracle Workflow Release 2.6 ..............................................................................................1-4Inter-Enterprise Business Processes ....................................................................................1-5Business Process Based Integration.....................................................................................1-6Oracle Workflow 2.5 Components ......................................................................................1-7Oracle Workflow 2.6 Components ......................................................................................1-8New Features in Release 2.6................................................................................................1-9Traditional Workflow ..........................................................................................................1-10Event Based Workflow........................................................................................................1-11Subscription Based Processing ............................................................................................1-12Local Event Processing........................................................................................................1-13Event Processing Through AQ ............................................................................................1-14System Integration with Oracle Workflow ..........................................................................1-15Event Based Workflow Processes .......................................................................................1-16Types of Message Based System Integration ......................................................................1-17Summary..............................................................................................................................1-18

Overview of the Oracle Workflow Business Event System................................................2-1Overview of the Oracle Workflow Business Event System ................................................2-2Objectives ............................................................................................................................2-3Business Events ...................................................................................................................2-4Event Subscriptions .............................................................................................................2-5Business Event System Components ...................................................................................2-6Event Manager.....................................................................................................................2-7Business Event System Architecture ...................................................................................2-8Communicating Events Between Systems...........................................................................2-9Event Message Propagation.................................................................................................2-10Oracle Advanced Queuing, an Enabling Technology..........................................................2-11Oracle Message Broker, an Enabling Technology...............................................................2-12Example: Order Processing .................................................................................................2-13Workflow Engine Event Activities......................................................................................2-14Review Questions ................................................................................................................2-15Summary..............................................................................................................................2-16

Events......................................................................................................................................3-1Events ..................................................................................................................................3-2Objectives ............................................................................................................................3-3Business Events ...................................................................................................................3-4Event Properties...................................................................................................................3-5Generate Functions ..............................................................................................................3-6Defining an Event ................................................................................................................3-8Finding an Event..................................................................................................................3-10Updating or Deleting an Event ............................................................................................3-11Business Event System Datatypes .......................................................................................3-12Event Message Structure .....................................................................................................3-13Agent Structure....................................................................................................................3-17Parameter List Structure ......................................................................................................3-18Parameter Structure .............................................................................................................3-19Event Groups .......................................................................................................................3-20Defining an Event Group.....................................................................................................3-21Raising Events .....................................................................................................................3-23


11i/2.6 Workflow Business Event System Table of Contentsii

Raising an Event Manually..................................................................................................3-26Predefined Events ................................................................................................................3-27Practice 1 Overview.............................................................................................................3-32Practice 1: Defining an Event ..............................................................................................3-33Practice 2 Overview.............................................................................................................3-36Practice 2: Raising an Event ................................................................................................3-37Summary..............................................................................................................................3-40

Systems and Agents ...............................................................................................................4-1Systems and Agents.............................................................................................................4-2Objectives ............................................................................................................................4-3Systems................................................................................................................................4-4Local System .......................................................................................................................4-5Defining a System................................................................................................................4-6Finding a System .................................................................................................................4-7Updating or Deleting a System............................................................................................4-8Agents..................................................................................................................................4-9Agent Properties ..................................................................................................................4-11Standard Queue Handlers ....................................................................................................4-15Custom Queue Handlers ......................................................................................................4-16Standard Agents...................................................................................................................4-17Defining an Agent................................................................................................................4-18Finding an Agent .................................................................................................................4-20Updating or Deleting an Agent ............................................................................................4-21Review Questions ................................................................................................................4-22Summary..............................................................................................................................4-23

Event Subscriptions ...............................................................................................................5-1Event Subscriptions .............................................................................................................5-2Objectives ............................................................................................................................5-3Event Subscriptions .............................................................................................................5-4Event Manager Subscription Processing .............................................................................5-5Subscription Properties........................................................................................................5-6Subscription Actions: Running a Rule Function.................................................................5-10Predefined Rule Functions...................................................................................................5-12Custom Rule Functions........................................................................................................5-13Subscription Actions: Sending an Event to a Workflow Process .......................................5-15Subscription Actions: Sending an Event to an Agent .........................................................5-17Defining a Subscription .......................................................................................................5-18Finding a Subscription.........................................................................................................5-21Updating or Deleting a Subscription....................................................................................5-22Predefined Subscriptions .....................................................................................................5-23Event APIs...........................................................................................................................5-27Event Function APIs............................................................................................................5-28Practice 1 Overview.............................................................................................................5-29Practice 1: Defining a Subscription .....................................................................................5-30Summary..............................................................................................................................5-34

Configuring Oracle Workflow for Event Communication ................................................6-1Configuring Oracle Workflow for Event Communication ..................................................6-2Objectives ............................................................................................................................6-3Checking Business Event System Setup..............................................................................6-4Event Message Communication ..........................................................................................6-7Agent Listeners....................................................................................................................6-8Running Listeners................................................................................................................6-10Scheduling Listeners............................................................................................................6-11Updating or Deleting a Listener...........................................................................................6-14Propagations ........................................................................................................................6-15


11i/2.6 Workflow Business Event System Table of Contentsiii

Scheduling Propagations......................................................................................................6-17Updating or Deleting a Propagation ....................................................................................6-20Demonstration......................................................................................................................6-21Signing Up Systems.............................................................................................................6-22Retrieving System Identifier Information............................................................................6-24Signing Up Systems.............................................................................................................6-25Synchronizing Systems........................................................................................................6-26Automatic Replication .........................................................................................................6-28Master/Copy Systems ..........................................................................................................6-29Reviewing Event Messages on Local Agents ......................................................................6-30Review Questions ................................................................................................................6-33Practice 1 Overview.............................................................................................................6-34Practice 1: Sending an Event to an Agent............................................................................6-35Summary..............................................................................................................................6-41

Event Activities in Workflow Processes...............................................................................7-1Event Activities in Workflow Processes..............................................................................7-2Objectives ............................................................................................................................7-3Example: Order Processing .................................................................................................7-4Event Attribute Type ...........................................................................................................7-5Defining an Attribute of Type Event ...................................................................................7-6Event Activities ...................................................................................................................7-7Event Activity Actions.........................................................................................................7-8Receive Event Activities......................................................................................................7-9Raise Event Activities..........................................................................................................7-12Send Event Activities ..........................................................................................................7-13Defining an Event Activity ..................................................................................................7-14Event Details........................................................................................................................7-16Defining Event Details: Receive..........................................................................................7-17Defining Event Details: Raise..............................................................................................7-18Defining Event Details: Send ..............................................................................................7-19Standard Activities...............................................................................................................7-21External Java Function Activities ........................................................................................7-24Defining an External Java Function Activity.......................................................................7-29Practice 1 Overview.............................................................................................................7-31Practice 1: Defining an Item Type with an Event Activity ..................................................7-32Practice 2 Overview.............................................................................................................7-36Practice 2: Defining a Workflow Process with an Event Activity Node .............................7-37Practice 3 Overview.............................................................................................................7-41Practice 3: Launching a Workflow Process from the Business Event System.....................7-42Summary..............................................................................................................................7-47

Sample Business Event Based Workflow Processes............................................................8-1Sample Business Event Based Workflow Processes ..........................................................8-2Objectives ............................................................................................................................8-3Workflow Agent Ping/Acknowledge...................................................................................8-4Master Ping Process.............................................................................................................8-7Detail Ping Process ..............................................................................................................8-8Workflow Send Protocol .....................................................................................................8-9Workflow Event Protocol Process.......................................................................................8-13Example: Order Processing .................................................................................................8-15Practice 1 Overview.............................................................................................................8-18Practice 1: Pinging Agents...................................................................................................8-19Review Questions ................................................................................................................8-22Summary..............................................................................................................................8-23

Error Handling for Subscription Processing.......................................................................9-1Error Handling for Subscription Processing ........................................................................9-2


11i/2.6 Workflow Business Event System Table of Contentsiv

Objectives ............................................................................................................................9-3Rule Function Status Codes.................................................................................................9-4Errors in Subscription Processing........................................................................................9-5WF_ERROR Agent .............................................................................................................9-6Error Handling Subscriptions ..............................................................................................9-7Unexpected Events ..............................................................................................................9-8Default Event Error Process ................................................................................................9-9Event Warnings ...................................................................................................................9-10External Event Errors ..........................................................................................................9-11Local Event Errors...............................................................................................................9-12Default Event Error Process ................................................................................................9-13Practice 1 Overview.............................................................................................................9-15Practice 1: Handling an Error in Subscription Processing ...................................................9-16Summary..............................................................................................................................9-22

Setting Up the Business Event System .................................................................................10-1Setting Up the Business Event System ................................................................................10-2Objectives ............................................................................................................................10-3Business Event System Setup Steps ....................................................................................10-4Step 1 Setting Global User Preferences ...............................................................................10-5Step 2 Starting the Java Function Activity Agent................................................................10-7Step 3 Setting Up Database Links and Queues....................................................................10-9Step 4 Setting Up the WF_EVENT_OMB_QH Queue Handler .........................................10-11Review Questions ................................................................................................................10-12Summary..............................................................................................................................10-13

Business Event System Summary.........................................................................................11-1Business Event System Summary........................................................................................11-2Objectives ............................................................................................................................11-3Business Event System Components ...................................................................................11-4Subscription Processing.......................................................................................................11-5Event Communication .........................................................................................................11-6Business Process Based Integration.....................................................................................11-7Review Question 1...............................................................................................................11-8Answer to Review Question 1 .............................................................................................11-9Review Question 2...............................................................................................................11-10Answer to Review Question 2 .............................................................................................11-11Review Question 3...............................................................................................................11-12Answer to Review Question 3 .............................................................................................11-13Review Question 4...............................................................................................................11-14Answer to Review Question 4 .............................................................................................11-15Review Question 5...............................................................................................................11-16Answer to Review Question 5 .............................................................................................11-17Review Question 6...............................................................................................................11-18Answer to Review Question 6 .............................................................................................11-19Review Question 7...............................................................................................................11-20Answer to Review Question 7 .............................................................................................11-21Review Question 8...............................................................................................................11-22Answer to Review Question 8 .............................................................................................11-23Review Question 9...............................................................................................................11-24Answer to Review Question 9 .............................................................................................11-25Review Question 10.............................................................................................................11-26Answer to Review Question 10 ...........................................................................................11-27Summary..............................................................................................................................11-28


11i/2.6 Workflow Business Event System Table of Contentsv

Preface

Profile

Before You Begin This Course

Before you begin this course, you should have the following qualifications:

• Some experience working with Oracle Workflow

• Thorough knowledge of Oracle8i and Oracle Internet Application Servertechnology

• If you plan to use Oracle Workflow with Oracle E-Business Suite,thorough knowledge of Oracle E-Business Suite

Prerequisites

• 11i/2.5 Workflow, or

• 11i/2.5 Workflow Overview

How This Course Is Organized

11i/2.6 Workflow Business Event System is an instructor-led course featuringlecture and hands-on exercises. Online demonstrations and written practicesessions reinforce the concepts and skills introduced.


11i/2.6 Workflow Business Event System Table of Contentsvi

Related Publications

Oracle Publications

Title Part Number

Oracle Workflow Guide Release 2.6 A87449

Additional Publications

• System release bulletins

• Installation and user’s guides

• read.me files

• Oracle Magazine


11i/2.6 Workflow Business Event System Table of Contentsvii

Typographic Conventions

Typographic Conventions in Text

Convention Element ExampleBold italic Glossary term (if

there is a glossary)The algorithm inserts the new key.

Caps andlowercase

Buttons,check boxes,triggers,windows

Click the Executable button.Select the Can’t Delete Card check box.Assign a When-Validate-Item trigger to theORD block.Open the Master Schedule window.

Courier new,case sensitive(default islowercase)

Code output,directory names,filenames,passwords,pathnames,URLs,user input,usernames

Code output: debug.set (‘I”, 300);Directory: bin (DOS), $FMHOME (UNIX)Filename: Locate the init.ora file.Password: User tiger as your password.Pathname: Open c:\my_docs\projectsURL: Go to http://www.oracle.comUser input: Enter 300Username: Log on as scott

Initial cap Graphics labels(unless the term is aproper noun)

Customer address (but Oracle Payables)

Italic Emphasized wordsand phrases,titles of books andcourses,variables

Do not save changes to the database.For further information, see Oracle7 ServerSQL Language Reference Manual.Enter [email protected],where user_id is the name of the user.

Quotationmarks

Interface elementswith long namesthat have onlyinitial caps;lesson and chaptertitles in cross-references

Select “Include a reusable module component”and click Finish.

This subject is covered in Unit II, Lesson 3,“Working with Objects.”

Uppercase SQL columnnames, commands,functions, schemas,table names

Use the SELECT command to viewinformation stored in the LAST_NAMEcolumn of the EMP table.

Convention Element ExampleArrow Menu paths Select File—> Save.


11i/2.6 Workflow Business Event System Table of Contentsviii

Brackets Key names Press [Enter].

Commas Key sequences Press and release keys one at a time:[Alternate], [F], [D]

Plus signs Key combinations Press and hold these keys simultaneously:[Ctrl]+[Alt]+[Del]

Typographic Conventions in Code

Convention Element ExampleCaps andlowercase

Oracle Formstriggers

When-Validate-Item

Lowercase Column names,table names

SELECT last_nameFROM s_emp;

Passwords DROP USER scottIDENTIFIED BY tiger;

PL/SQL objects OG_ACTIVATE_LAYER(OG_GET_LAYER

(‘prod_pie_layer’))

Lowercaseitalic

Syntax variables CREATE ROLE role

Uppercase SQL commands andfunctions

SELECT useridFROM emp;

Typographic Conventions in Navigation Paths

This course uses simplified navigation paths, such as the following example, todirect you through Oracle Applications.

(N) Invoice > Entry > Invoice Batches Summary (M) Query > Find (B) Approve

This simplified path translates to the following:

1. (N) From the Navigator window, select Invoice > Entry > Invoice BatchesSummary.

2. (M) From the menu, select Query > Find.

3. (B) Click the Approve button.

Notations :

(N) = Navigator

(M) = Menu

(T) = Tab


11i/2.6 Workflow Business Event System Table of Contentsix

(I) = Icon

(H) = Hyperlink

(B) = Button

Typographical Conventions in Help System Paths

This course uses a “navigation path” convention to represent actions you performto find pertinent information in the Oracle Applications Help System.

The following help navigation path, for example—

(Help) General Ledger > Journals > Enter Journals

—represents the following sequence of actions:

1. In the navigation frame of the help system window, expand the GeneralLedger entry.

2. Under the General Ledger entry, expand Journals.

3. Under Journals, select Enter Journals.

4. Review the Enter Journals topic that appears in the document frame of thehelp system window.

Getting Help

Oracle Applications provides you with a complete online help facility.

Whenever you need assistance, simply choose an item from the Help menu topinpoint the type of information you want.

To display help for a current window:

1. Choose Window Help from the Help menu, click the Help button on thetoolbar, or hold down the Control key and type 'h'.

A web browser window appears, containing search and navigation frames onthe left, and a frame that displays help documents on the right.

The document frame provides information on the window containing thecursor. The navigation frame displays the top-level topics for yourresponsibility, arranged in a tree control.

2. If the document frame contains a list of topics associated with the window,click on a topic of interest to display more detailed information.


11i/2.6 Workflow Business Event System Table of Contentsx

3. You can navigate to other topics of interest in the help system, or chooseClose from your web browser's File menu to close help.

Searching for Help

You can perform a search to find the Oracle Applications help information youwant. Simply enter your query in the text field located in the top-left frame of thebrowser window when viewing help, then click the adjacent Find button.

A list of titles, ranked by relevance and linked to the documents in question, isreturned from your search in the right-hand document frame. Click on whichevertitle seems to best answer your needs to display the complete document in thisframe. If the document doesn't fully answer your questions, use your browser'sBack button to return to the list of titles and try another.


Oracle Workflow Release 2.6Chapter 1 - Page 1

Oracle Workflow Release 2.6Chapter 1



Oracle Workflow Release 2.6

Copyright Oracle Corporation, 2001. All rights reserved.®




Objectives


Objectives

After completing this lesson, you should be able todo the following:• Discuss the new features in Oracle Workflow

Release 2.6• Describe the concept of subscription based

processing• Describe the concept of business process based

integration• Discuss different types of message based system

integration supported by the Business EventSystem






• Oracle Workflow Release 2.6 with the BusinessEvent System supports:– Traditional applications-based workflows– E-business integration workflows

• Oracle Workflow enables integration that is:– Business process based– Message based

Oracle Workflow Release 2.6A traditional applications-based workflow may model business rules that areused by a local application, and interact with people using e-mails. For example,the modeling of an approval hierarchy is a common use of Oracle Workflow inthis scenario.For e-business, however, there is a requirement to integrate with externalsystems, such as sending a document to a business-to-business exchange, orother systems external to the local application. Release 2.6 of Oracle Workflowsupports e-business integration workflows by allowing business analysts anddevelopers to model business processes across different systems using agraphical drag-and-drop designer - the Workflow Builder. This support allowsOracle Workflow customers to deal with business objects and their integrationflows powerfully and flexibly, with minimal intrusion into the core application.



Inter-Enterprise Business Processes


Inter-Enterprise Business Processes

Internet

Supplier A

Supplier B

IntegrationHub

IntegrationHub

Logistics

Bank

IntegrationHub

IntegrationHub

Inter-Enterprise Business ProcessesIn e-business, different enterprises need to communicate with each other overthe Internet. Oracle Workflow with the Business Event System can act as anintegration hub that carries out business rules spanning all the enterprisesinvolved in a business process.



Business Process Based Integration



Shipping

HumanResources

AccountingCredit

Management

Web Store

Warehouse

Order EntryData Warehouse

WORKFLOW

Business Process Based IntegrationBusiness process based integration is model-driven.

• Business rules are expressed in a process model.• These rules define the policy for each end-to-end process.• The process model can encompass applications both within and beyond

the enterprise.Business process based integration provides:

• A global, enterprise-level view of business objects• Business process automation

Oracle Workflow supports business process based integration in Release 2.6through the Business Event System.



Oracle Workflow 2.5 Components



WorkflowDevelopment

ClientOracle ServerApplication

ServerBrowser

Client

WorkflowDevelopment

Client

WebNotification

Worklist

WebMonitor

WebAnalysis

Tools

MailApplications

iAS

NotificationServices

WorkflowEngine

DirectoryServices

Users Roles

Oracle WorkflowEnabled Application

WorkflowBuilder

WorkflowLoader

WorkflowDefinition

FilesNotification

Mailer

Oracle Workflow 2.5Workflow Development ClientThe development client is a PC running Windows 95, Windows 98, Windows2000, or Windows NT 4.0 or higher. This platform is used to create and modifyOracle Workflow process definitions.Oracle ServerThe Oracle Server platform is the Oracle RDBMS. This platform hosts thebusiness application integrated with Oracle Workflow, the Workflow Engine,notification services, and directory services.Application ServerThe application server is the environment outside of the RDBMS. Thisenvironment includes ancillary services such as the Oracle Internet ApplicationServer (iAS) as the web server, and the Notification Mailer.Browser ClientThe browser client is the workstation or PC that an end user uses to performdaily tasks. This client includes support for reviewing and responding tonotifications in the Notification Worklist, the Oracle Workflow Monitor, webanalysis tools, and mail applications for reviewing and responding tonotifications by e-mail.






WorkflowDevelopment

ClientOracle ServerApplication

ServerBrowser

Client

WorkflowDevelopment

Client

WebNotification

Worklist

WebMonitor

WebAnalysis

Tools

MailApplications

iAS

NotificationServices

BusinessEvent

System

WorkflowEngine

DirectoryServices

Users Roles

AdvancedQueuing

Oracle WorkflowEnabled Application

WorkflowBuilder

WorkflowLoader

WorkflowDefinition

FilesNotification

Mailer

Oracle Workflow 2.6The Business Event System is a new application service added to OracleWorkflow in Release 2.6. Oracle Workflow now supports both traditionalapplications-based workflows and event-based integration workflows.The Workflow Engine and the Business Event System can functionindependently of each other. You can continue to use the Workflow Engine toexecute the processes that model the business rules in your applications, just asin previous releases. However, you can now achieve the most powerful andflexible processing by using the Workflow Engine and the Business EventSystem together to execute cross-system processes for e-business integration.



New Features in Release 2.6


New Features in Release 2.6

• Business Event System– Subscription based processing– Cross-system processing

• Support for events in Workflow Engine– New activity type: Event– New attribute type: Event

• External Java function activities– New standard activities for event

information– Support for custom Java functions



Traditional Workflow


Traditional Workflow

Create WorkflowAPIs

Notifications

WorkflowProcess Engine

FunctionActivities

Traditional WorkflowTraditional workflow processes are launched from a business application usingthe WF_ENGINE.CreateProcess and WF_ENGINE.StartProcess APIs. Theseworkflow processes are made up of notifications and function activitiesexecuted in the core application’s system.



Event Based Workflow


Event Based Workflow

Raise Event

Notifications

WorkflowProcess Engine

FunctionActivities

Matching Event Subscriptions

Event Based WorkflowThe Business Event System in Oracle Workflow 2.6 provides increasedflexibility through subscription based processing: you raise a business eventfrom an application, but specify the processing to perform for that event as asubscription in Oracle Workflow. For example, you can now launch a workflowprocess when an event is raised by specifying that process in a subscription tothe event. You can also define multiple subscriptions to the same event toperform additional processing for different purposes, without intruding anyfurther on the core application.



Subscription Based Processing


Subscription Based Processing

In the Oracle Workflow Business Event System:• Business events in applications trigger event

subscriptions in Oracle Workflow.• Multiple subscriptions can be defined to perform

different processing for the same event.• Subscriptions can be enabled, modified, or

disabled as necessary without intruding intoapplications.



Local Event Processing


Local Event ProcessingMatching Event Subscriptions

Custom RuleFunction

WorkflowProcess

RaiseEvent

GenerateXML

RuleFunction

SendEvent Transform

DispatchEvent

<<extends>> <<extends>>

<<extends>>

<<extends>>

Local Event ProcessingOracle Workflow provides powerful capabilities for controlling the processingperformed by your subscriptions when an event is raised.

• The Business Event System can handle event information as XMLdocuments.

• Each event subscription has a rule function that specifies the processing itperforms. In addition to launching a workflow process, a subscription canalso run custom code or send a message from one system to another usingOracle Advanced Queuing (AQ) propagation.

• The Business Event System supports performing transformations on eventmessages at propagation time.



Event Processing Through AQ


Event Processing Through AQMatching Event Subscriptions

Custom RuleFunction

WorkflowProcess

Listener

Transform

RuleFunction

SendEvent Transform

DispatchEvent

<<extends>>

<<extends>>

<<extends>>

<<ExternalSystem>>through

AQ

Event Processing Through AQEvent subscriptions can also be triggered when an event message is receivedfrom an external source through AQ. The Business Event System supportsperforming transformations on event messages when they are received.By supporting the communication of messages between systems, OracleWorkflow lets you define processing across different systems encompassingboth your own enterprise and your business partners.The power of this cross-system processing, together with the flexibilityprovided by subscription based processing, enables you to use Oracle Workflowfor e-business integration.



System Integration with Oracle Workflow


System Integration with Oracle Workflow

• E-business accelerates the demand for systemintegration.

• Communication is required between systems bothwithin and beyond the enterprise.

• Oracle Workflow supports e-business integrationworkflows in addition to traditional applications-based workflows.

• Event based workflows allow modelingof cross-system processes,enabling business processbased integration.



Event Based Workflow Processes


Event Based Workflow Processes

Workflow ProcessGet HeaderProperty

Set HeaderProperty

Route on Header

SendEventRaise

Event

ReceiveEvent

TransformXML

Get XMLTag Value

Route onXML

<<BusinessEvent

System>>

Event Based Workflow ProcessesEvent based workflow processes control and route objects between applicationsaccording to business rules. These workflow processes support:

• Receiving events to launch or continue processes• Raising new events• Sending event messages for inter-system communication• Accessing and routing on header properties of event messages• Accessing and routing on XML content within event messages

By letting you model processes across different systems, event based workflowsenable business process based integration.



Types of Message Based System Integration


Types of Message Based SystemIntegration

The Business Event System supports integration inwhich applications are loosely coupled throughasynchronous messaging.• Point-to-point system integration—"Hardwired"

communication between specified systems• Messaging hub system integration—Intersystem

communication routed through a central hub formore complex integration scenarios

• Distributed applications messaging—Master/copyreplication of data for distributed applications



Summary


Summary

In this lesson, you should have learned how to:• Discuss the new features in Oracle Workflow

Release 2.6• Describe the concept of subscription based

processing• Describe the concept of business process based

integration• Discuss different types of message based system

integration supported by the Business EventSystem


Overview of the Oracle Workflow Business Event SystemChapter 2 - Page 1

Overview of the OracleWorkflow Business EventSystemChapter 2



Overview of the Oracle Workflow Business EventSystem


Overview of the Oracle WorkflowBusiness Event System



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Discuss the concepts of a business event and an

event subscription.• Describe how the Business Event System

communicates events between systems.



Business Events


Business Events

• A business event is an occurrence in anapplication or program that might be significant toother objects in a system or to external agents.

• For instance, the creation of a purchase order isan example of a business event in a purchasingapplication.



Event Subscriptions


Event Subscriptions

• An event subscription is a registration indicatingthat a particular event is significant to a systemand specifying the processing to perform whenthe triggering event occurs.

• Subscriptions can include the following types ofprocessing:– Executing custom code on the event

information– Sending event information to a

workflow process– Sending event information to other

communication agents or systems



Business Event System Components



The Business Event System includes:• The Event Manager—Lets you register:

– Business events– Systems– Named communication agents

within systems– Subscriptions to events that are

significant to your systems• Workflow Engine event activities—

Let you model business events withinworkflow processes



Event Manager


Event Manager

LISTENExternal Events

RAISELocal Events

Application

AQ

Event Dispatcher

Matching EventSubscriptions

Phase n

Phase 1

BusinessEvent

BusinessEvent

Event ManagerWhen an event is raised by a local application, or when an event is receivedfrom an external source through Oracle Advanced Queuing (AQ), it isprocessed by a component of the Event Manager called the Event Dispatcher.In both cases, the Event Dispatcher searches for and executes any subscriptionsto that event. If there are multiple subscription to the same event, a subscriptionproperty called the phase value determines the order in which the subscriptionsare executed.



Business Event System Architecture


Business Event System Architecture

SYSTEM

ORACLE8i

Advanced Queuing

Business Event System

Workflow Engine

SYSTEM

Business Events

Business Events

Business Events

Business Events

Business Event System ArchitectureOracle Workflow with the Business Event System can act as a systemintegration messaging hub that relays business event messages among systems.The Business Event System leverages Oracle Advanced Queuing (AQ) to sendmessages from one system to another.For the greatest flexibility in routing and processing business events, you canmodel your business process logic in workflow processes that are executed bythe Workflow Engine. However, the Business Event System can also functionindependently of the Workflow Engine.



Communicating Events Between Systems


Communicating Events Between Systems

• Systems contain named points of communicationcalled agents.

• Communication within and between systems isaccomplished by sending an event message fromone agent to another.

• The Business Event System interacts with anagent through Oracle Advanced Queuing.



Event Message Propagation


Event Message Propagation

• The Business Event System leverages OracleAdvanced Queuing (AQ) to propagate eventmessages by the SQLNET protocol.

• You can also implement an external service, suchas Oracle Message Broker, to propagate messagesby a different protocol.

• Integration with Oracle Message Broker providessupport for HTTP and HTTPS protocols andenables integration with third party messagingsolutions.



Oracle Advanced Queuing, an Enabling Technology


Oracle Advanced Queuing, an EnablingTechnology

MACHINE BOUNDARY

Application

ORACLE

AdvancedQueuing

Propagate

Application

ORACLE

AdvancedQueuing

Propagate

ORACLE

AdvancedQueuing

Application

Application

MACHINE

BOUNDARY

Oracle Advanced Queuing, an Enabling TechnologyOracle Advanced Queuing (AQ) allows queue-to-queue propagation acrossmachine boundaries.



Oracle Message Broker, an Enabling Technology


Oracle Message Broker, an EnablingTechnology

Oracle MessageBroker

Third party messaging solutions

http/https

OMBCompliantMessageFormats

AdvancedQueuing

Oracle8i

Oracle Message Broker, an Enabling TechnologyIntegrate with Oracle Message Broker is critical for supporting communicationby HTTP and HTTPS protocols and integration with third party messagingsolutions.



Example: Order Processing



Example: Order ProcessingThis example shows a workflow process that includes business events. Theexample comes from the Event System Demonstration workflow. This processincludes activities that receive purchase order events to launch the workflow, aswell as activities that send other events in response to the order, such as an orderacknowledgement, advanced shipment notice, and invoice.



Workflow Engine Event Activities


Workflow Engine Event Activities

• Event activities represent business events withinworkflow processes.

• Event activities can:– Receive an event from the Event Manager to

start or continue a workflow process– Raise an event to the Event Manager,

triggering subscriptions to that event– Send an event message to a Business

Event System agent• You can use workflow processes to

model complex processing or routinglogic based on the contents of an event.



Review Questions


Review Questions

1. What is the definition of a business event?2. What is the definition of an event subscription?3. How does the Business Event System interact with

a communication agent on a system?4. What protocols can be used to propagate event

messages?5. What are the three possible actions for an event

activity within a workflow process?

Review Questions and Solutions1. What is the definition of a business event? A business event is an occurrence in an application or program that

might be significant to other objects in a system or to external agents.2. What is the definition of an event subscription? An event subscription is a registration indicating that a particular

event is significant to a system and specifying the processing toperform when the triggering event occurs.

3. How does the Business Event System interact with a communication agenton a system?

The Business Event System uses an AQ queue to interact with anagent.

4. What protocols can be used to propagate event messages? The Business Event System can use AQ to propagate event messages

by the SQLNET protocol. Oracle Workflow also integrates withOracle Message Broker to support propagation by HTTP and HTTPScommunication protocols. Additionally, you can implement anexternal service to propagate messages by a custom protocol.

5. What are the three possible actions for an event activity within a workflowprocess?

An event activity can receive, raise, or send an event.



Summary


Summary

In this lesson, you should have learned how to:• Discuss the concepts of a business event and an

event subscription.• Describe how the Business Event System

communicates events between systems.


EventsChapter 3 - Page 1

EventsChapter 3



Events


Events



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Define individual events.• Describe the abstract datatypes used by the

Business Event System.• Define event groups.• Raise events.• Use predefined Oracle Workflow events.



Business Events


Business Events

• Define your significant business events in theEvent Manager.

• When an event occurs in an application on yourlocal system:– The application must assign an event key to

uniquely identify that particular instance of theevent.

– The event must be raised to the EventManager.



Event Properties


Event Properties

A business event definition in the Event Managerincludes the following properties:• Internal Name—The internal name for an event

must be unique and is case-sensitive. Thefollowing format is suggested:

• Display Name• Generate Function—A function that can

generate the complete event data fromthe event key

<company>.<family>.<product>.<component>.

<object>.<event>

Event PropertiesSome examples of event names are:

• oracle.apps.wf.event.event.create• oracle.apps.wf.event.event.delete• oracle.apps.wf.event.subscription.create

These events are predefined events within the Business Event System. For moreinformation, refer to the Predefined Workflow Events chapter in the OracleWorkflow Guide.



Generate Functions


Generate Functions

• Any detail information needed to describe whatoccurred in an event, in addition to the event nameand event key, is called the event data.

• Event data is typically structured as an XMLdocument.

• A Generate function for an event is a function thatcan produce the complete event data from theevent key.

• Generate functions must follow a standard API.

Generate Functions• The event data is stored as a character large object (CLOB).• The application where an event occurs can include the event data when

raising the event to the Event Manager.• If the application will not provide the event data, you should specify a

Generate function for the event.• If an application raises an event without providing the event data, and any

subscriptions to the event require the event data, the Event Manager callsthe Generate function to produce the event data.

• If the event data is required but no Generate function is defined for theevent, Oracle Workflow creates a default set of event data using the eventname and event key.

Standard APIA Generate function for an event must have the following standard API:function <function_name> (p_event_name in varchar2,

p_event_key in varchar2) return clob;

Arguments:• p_event_name—The internal name of the event.• p_event_key—A string generated when the event occurs within a program

or application. The event key uniquely identifies a specific instance of theevent.



For more information, refer to the Defining Procedures and Functions forOracle Workflow chapter in the Oracle Workflow Guide.



Defining an Event


Defining an Event

To Define an Event:1. Use a web browser to connect to the following URL: <webagent>/wf_event_html.listevents Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Events web page from the Oracle Workflow home

page, <webagent>/wfa_html.home. Note: You must have workflow administrator privileges to access the

Event Manager web pages.2. The Events page appears, displaying a list of existing events. Choose the Add Event button to open the Edit Event page.3. Enter the internal name of the event in the Name field.4. Enter a display name for the event.5. Enter an optional description for the event.6. In the Status field, select Enabled or Disabled as the event status. If you

disable an event, it still remains in the Events list for reference, but youcannot use the event in active subscriptions.

7. If you are defining an event that occurs on your local system, enter theGenerate function for the event.

8. If you use a program to create event definitions automatically, the EventManager displays owner information set by that program in the Owner



Name and Owner Tag fields. You can use the Edit Event page to updatethis information manually if necessary.

9. Choose the Submit button to save the event.



Finding an Event


Finding an Event

• Use the Find Event/Group page to locate a specificevent or event group definition.

• Search for events by entering the followingcriteria:– Name– Display Name– Status– Type

Finding an EventTo access the Find Event/Group web page, use a web browser to connect to thefollowing URL:<webagent>/wf_event_html.findeventReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Find Event/Group web page from the Oracle Workflowhome page, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.



Updating or Deleting an Event


Updating or Deleting an Event

Locate the event you want in the Events page.• To view the subscriptions to an event, choose the

schedule icon in the Subs column for that event.• To update an event, choose the pencil icon in the

Edit column for that event.• To delete an event, choose the trash icon in the

Delete column for that event, and choose OK inthe confirmation window that appears.

Updating or Deleting an EventTo access the Events web page, use a web browser to connect to the followingURL:<webagent>/wf_event_html.listeventsReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Events web page from the Oracle Workflow homepage, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.Subscriptions to an EventFor events that do not have any subscriptions yet, a blank schedule icon appears.For events that do have subscriptions referencing them, a full schedule iconappears.You can begin defining a new subscription on the event by choosing the AddSubscription button in the Event Subscriptions page. The Edit Subscription pageappears with the event name automatically entered in the Event Filter field.Deleting an EventYou can only delete events that do not have any subscriptions referencing themand that are not members of any event group.



Business Event System Datatypes


Business Event System Datatypes

Oracle Workflow uses the following abstractdatatypes to model the structure and behaviorof Business Event System data.• Event message structure: WF_EVENT_T• Agent structure: WF_AGENT_T• Parameter list structure: WF_PARAMETER_LIST_T• Parameter structure: WF_PARAMETER_T



Event Message Structure


Event Message Structure

• Oracle Workflow uses the object typeWF_EVENT_T to store event messages.

• WF_EVENT_T contains all the header properties ofan event message as well as the event datapayload.

• Internally, the Business Event System and theWorkflow Engine can only communicate events inthis format.

WF_EVENT_T AttributesAttribute Name: PRIORITYDatatype: NUMBERDescription: The priority with which the message recipient should dequeue themessage. A smaller number indicates a higher priority.

Attribute Name: SEND_DATEDatatype: DATEDescription: The date and time when the message is sent. This attribute isreserved for future use.

Attribute Name: RECEIVE_DATEDatatype: DATEDescription: The date and time when the message is dequeued. This attribute isreserved for future use.

Attribute Name: CORRELATION_IDDatatype: VARCHAR2(240)Description: A correlation identifier that associates this message with othermessages. This attribute is initially blank but can be set by a function. If a value



is set for the correlation ID, then that value is used as the item key if the event issent to a workflow process.

Attribute Name: PARAMETER_LISTDatatype: WF_PARAMETER_ LIST_TDescription: A list of additional parameter name and value pairs.

Attribute Name: EVENT_NAMEDatatype: VARCHAR2(240)Description: The internal name of the event.

Attribute Name: EVENT_KEYDatatype: VARCHAR2(240)Description: The string that uniquely identifies the instance of the event.

Attribute Name: EVENT_DATADatatype: CLOBDescription: A set of additional details describing what occurred in the event.The event data can be structured as an XML document.

Attribute Name: FROM_AGENTDatatype: WF_AGENT_TDescription: The agent from which the event is sent. For locally raised events,this attribute is initially null.

Attribute Name: TO_AGENTDatatype: WF_AGENT_TDescription: The agent to which the event should be sent (the messagerecipient).

Attribute Name: ERROR_ SUBSCRIPTIONDatatype: RAW(16)Description: If an error occurs while processing this event, this is thesubscription that was being executed when the error was encountered.

Attribute Name: ERROR_MESSAGEDatatype: VARCHAR2(4000)Description: An error message that the Event Manager generates if an erroroccurs while processing this event.



Attribute Name: ERROR_STACKDatatype: VARCHAR2(4000)Description: An error stack of arguments that the Event Manager generates ifan error occurs while processing this event. The error stack provides contextinformation to help you locate the source of an error.

The WF_EVENT_T object type also includes the following methods, which youcan use to retrieve and set the values of its attributes.Note: You must call the Initialize method before you can perform any furthermanipulation on a new WF_EVENT_T object.

• Initialize• getPriority• getSendDate• getReceiveDate• getCorrelationID• getParameterList• getEventName• getEventKey• getEventData• getFromAgent• getToAgent• getErrorSubscription• getErrorMessage• getErrorStack• setPriority• setSendDate• setReceiveDate• setCorrelationID• setParameterList• setEventName• setEventKey• setEventData• setFromAgent• setToAgent• setErrorSubscription• setErrorMessage• setErrorStack• Content• Address• AddParameterToList



• GetValueForParameterFor more information, refer to the Oracle Workflow APIs chapter in the OracleWorkflow Guide.



Agent Structure


Agent Structure

• Oracle Workflow uses the object typeWF_AGENT_T to store information about a namedcommunication agent on a system.

• Event messages reference agent information inthe format defined by the WF_AGENT_T datatype.

WF_AGENT_T AttributesAttribute Name: NAMEDatatype: VARCHAR2(30)Description: The name of the agent.

Attribute Name: SYSTEMDatatype: VARCHAR2(30)Description: The system where the agent is located.

The WF_AGENT_T object type also includes the following methods, whichyou can use to retrieve and set the values of its attributes.

• getName• getSystem• setName• setSystem

For more information, refer to the Oracle Workflow APIs chapter in the OracleWorkflow Guide.



Parameter List Structure


Parameter List Structure

• Oracle Workflow uses the named varying arrayWF_PARAMETER_LIST_T to store a list ofparameters in a form that can be included in anevent message.

• WF_PARAMETER_LIST_T allows custom values tobe added to the WF_EVENT_T event messageobject.

• The WF_PARAMETER_LIST_T datatype caninclude up to 100 parameter name and value pairs.

WF_PARAMETER_LIST_TMaximum size: 100Element datatype: WF_PARAMETER_T

When WF_PARAMETER_LIST_T is used within a WF_EVENT_T structure,you can use the following WF_EVENT_T methods to add and retrieveparameters in the list.

• AddParameterToList• GetValueForParameter

When an event message that includes a parameter list is sent to a workflowprocess, the parameters in the list are created as item attributes for the workflowprocess.



Parameter Structure


Parameter Structure

• Oracle Workflow uses the object typeWF_PARAMETER_T to store a parameter nameand value pair in a form that can be included in anevent message parameter list.

• WF_PARAMETER_T allows custom values to beadded to the WF_EVENT_T event message object.

WF_PARAMETER_T AttributesAttribute Name: NAMEDatatype: VARCHAR2(30)Description: The parameter name.

Attribute Name: VALUEDatatype: VARCHAR2(2000)Description: The parameter value.

The WF_PARAMETER_T object type also includes the following methods,which you can use to retrieve and set the values of its attributes.

• getName• getValue• setName• setValue




Event Groups


Event Groups

• Event groups let you associate any events youwant with each other and reference them as agroup in event subscriptions.

• An event group is a type of event composed of aset of individual member events.

• Once you have defined an event group, you canregister a subscription on the group rather thanhaving to create separate subscriptions for eachindividual event within it.

• The subscription will be executedwhenever any one of the group'smember events occurs.

Event Groups• The internal names of event groups should follow the same format as the

names of individual events.• Event groups cannot be used to raise events. You must raise each event

individually.• An event group can contain only individual events as its members. It

cannot contain another group.



Defining an Event Group


Defining an Event Group

To Define an Event Group:1. Use a web browser to connect to the following URL: <webagent>/wf_event_html.listevents Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Events web page from the Oracle Workflow home

page, <webagent>/wfa_html.home. Note: You must have workflow administrator privileges to access the

Event Manager web pages.2. The Events page appears, displaying a list of existing events. Choose the

Add Group button to open the Edit Group page.3. Enter the internal name of the event group in the Name field.4. Enter a display name for the event group.5. Enter an optional description for the event group.6. In the Status field, select Enabled or Disabled as the event group status. If

you disable an event group, it still remains in the Events list for reference,but you cannot use the event group in active subscriptions.

7. If you use a program to create event definitions automatically, the EventManager displays owner information set by that program in the OwnerName and Owner Tag fields. You can use the Edit Group page to updatethis information manually if necessary.

8. Choose the Submit button to save the event group.



After you save the event group definition, the Edit Group page displaysthe list of member events for that group.

9. To add a member event to the group, choose the Add Event button.10. In the Add to Group page that appears, enter search criteria to locate the

event you want to add. The search criteria are:– Name—enter the internal name of the event you want to add.– Display Name—enter the display name of the event you want to add.– Status—choose Enabled or Disabled as the status of the event you

want to add. Choose Any to search for events of any status.11. Choose the Go button. The Add to Group page displays a list of events

that match your search criteria.12. Select the event or events that you want to add to your event group.13. Choose the Add button to add the selected events to your event group. The

Edit Group page appears, displaying the updated list of event groupmembers.

14. Choose the Submit button to save the event group definition.15. If you want to remove a member event from the group, select the event or

events you want to delete in the Edit Group page.16. Choose the Delete button to remove the selected events from your event

group. The Edit Group page displays the updated list of event groupmembers.



Raising Events


Raising Events

• Events can be raised by the following methods:– From the application where the event occurs,

using the WF_EVENT.Raise() API– From a workflow process, using a Raise event

activity– From the Raise Event web page, by manual

submission, if the event does not requireadditional parameters

• When an event is raised, the Event Managersearches for and executes subscriptionsto that event.

Raising EventsTo raise an event, you must provide the event name and an event key to identifythe instance of the event. You can optionally provide a CLOB containing theevent data.Also, if you use the WF_EVENT.Raise API, you can optionally provide a list ofadditional header parameters for the event in the WF_PARAMETER_LIST_Tformat.ExampleThe following example code shows how to use the WF_EVENT.Raise API toraise an event from an application.

declare

l_xmldocument varchar2(32000);

l_eventdata clob;

l_parameter_list wf_parameter_list_t;

l_message varchar2(10);

begin

/*

** If the complete event data is easily available,



** we can optionally test if any subscriptions to

** this event require it (rule data = Message).

*/

l_message := wf_event.test('<EVENT_NAME>');

/*

** If we do require the complete event data, and we

** have the data now, set it; else we can just rely

** on the Event Generate Function callback code.

** Then Raise the Event with the required

** parameters.

*/

if l_message = 'MESSAGE' then

if l_xmldocument is not null then

dbms_lob.createtemporary(l_eventdata, FALSE,

DBMS_LOB.CALL);

dbms_lob.write(l_eventdata,

length(l_xmldocument), 1 ,l_xmldocument);

-- Raise the Event with the message

wf_event.raise(

p_event_name => '<EVENT_NAME>',

p_event_key => '<EVENT_KEY>',

p_event_data => l_eventdata,

p_parameters => l_parameter_list);

else

-- Raise the Event without the message

wf_event.raise(

p_event_name => '<EVENT_NAME>',

p_event_key => '<EVENT_KEY>',


end if;

elsif

l_message = 'KEY' then

-- Raise the Event

wf_event.raise(

p_event_name => <EVENT_NAME>,

p_event_key => <EVENT_KEY>,




end if;

/*

** Up to your own custom code to commit the

** transaction

*/

commit;

/*

** Up to your own custom code to handle any major

** exceptions

*/

exception

when others then

null;

end;



Raising an Event Manually


Raising an Event Manually

To Raise an Event:1. Use a web browser to connect to the following URL: <webagent>/wf_event_html.entereventdetails Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Raise Events web page from the Oracle Workflow

home page, <webagent>/wfa_html.home. Note: You must have workflow administrator privileges to access the

Event Manager web pages.2. The Raise Event page appears.3. In the Event Name field, select the event that you want to raise.4. Enter an event key that uniquely identifies this instance of the event.5. Optionally enter event data to describe what occurred in the event. Note: The maximum length of the data you can enter in the Event Data

field is 32 kilobytes. If the event data exceeds 32 Kb, you should assign aGenerate function in the event definition to generate the event data, ratherthan entering the data directly in the Event Data field.

6. Choose the Submit button to raise the event to the Event Manager. OracleWorkflow raises the event and displays a confirmation message with theevent name and event key. Choose the OK button.



Predefined Events


Predefined Events

• Oracle Workflow provides several predefinedevents for significant occurrences within theBusiness Event System.

• You can define subscriptions to these events forreplication, validation, or other purposes.

• Some predefined events are referenced by defaultsubscriptions that are created automatically whenyou install Oracle Workflow.



Predefined Events


Predefined Events

• Event Created• Event Updated• Event Deleted• Event Group Creation• Event Group Updated• Event Group Deleted• System Created• System Updated• System Deleted

Predefined Workflow events include:• Agent Created• Agent Updated• Agent Deleted• Subscription Created• Subscription Updated• Subscription Deleted

Predefined EventsThese predefined events are raised whenever an Event Manager objectdefinition is created, updated, or deleted. These events are used for replicationof Business Event System data from one system to another.Individual Event or Event Group Definition Events

• Event Created• Event Updated• Event Deleted

Event Group Member Definition Events• Event Group Creation• Event Group Updated• Event Group Deleted

System Definition Events• System Created• System Updated• System Deleted

Agent Definition Events• Agent Created• Agent Updated• Agent Deleted



Event Subscription Definition Events• Subscription Created• Subscription Updated• Subscription Deleted

For more information, refer to the Predefined Workflow Events chapter in theOracle Workflow Guide.



Predefined Events


Predefined Events

• Synchronize EventSystems

• Seed Event Group• System Signup• Any• Unexpected

Predefined Workflow events include:• Ping Agent• Acknowledge Ping• Workflow Send

Protocol• Workflow Send

ProtocolAcknowledgement

Predefined EventsSynchronize Event Systems EventThis event is used to synchronize the Event Manager data on the local systemwith another system.Seed Event GroupThis event group contains events used for automatic replication of BusinessEvent System objects from one system to another. The group includes all theevent, event group, system, agent, and subscription definition events, as well asthe Synchronize Event Systems event.System Signup EventThis event is used to sign up a destination system for receiving event messagesfrom the source system.Any EventThis event is raised implicitly when any other event is raised locally or receivedfrom an external source.Unexpected EventThe Event Manager executes subscriptions to this event when another event israised locally or received from an external source, but no subscription to thatother event exists.Ping Agent Events

• Ping Agent—This event is used in the Workflow AgentPing/Acknowledge process to ping inbound agents.



• Acknowledge Ping—This event is used in the Workflow AgentPing/Acknowledge process to acknowledge receipt of a Ping Agent eventmessage.

Workflow Send Protocol Events• Workflow Send Protocol—This event is used with the Workflow Send

Protocol process to send the event message to an agent.• Workflow Send Protocol Acknowledgement—This event is used with the

Workflow Send Protocol process to acknowledge receipt of an eventmessage.




Practice 1 Overview


Practice 1 Overview

This practice covers defining an event in the EventManager.



Practice 1: Defining an Event


Practice 1:Defining an Event

Define an event with the following properties:– Internal name:

XX.oracle.workflow.bes.event.new– Display name: XX New Event– Description: XX New Event

Replace ‘XX’ with your terminal number.

Practice 1 SolutionIn this practice you will create an event definition in the Event Manager. Aftercompleting the practice, you should be able to see your event listed in theEvents page.Note: Because many students access the system and create objects during thiscourse, you need a way to distinguish between the objects created by you and byyour classmates. Therefore, you will be assigned a terminal number by yourinstructor. Use this number as a prefix wherever you see XX included in thename of something you are defining. In this way, you can ensure that thedefinitions you create are unique.

1. Use a web browser to connect to the Oracle Workflow home page with theURL provided by the instructor. Log in as any user with workflowadministrator privileges.

2. Choose the Events link.3. In the Events page, choose the Add Event button to open the Edit Event

page.4. In the Name field, enter XX.oracle.workflow.bes.event.new as the internal

name of the event.5. In the Display Name field, enter XX New Event.6. In the Description field, enter XX New Event.7. In the Status field, select Enabled.8. Leave the Generate Function, Owner Name, and Owner Tag fields blank.



9. Choose the Submit button to save the event.



Practice 1: Defining an Event


Practice 1:Defining an Event

Practice 1 SolutionWhen you complete this practice, the event definition should look similar tothis.



Practice 2 Overview


Practice 2 Overview

This practice covers raising an event from the RaiseEvent web page.



Practice 2: Raising an Event


Practice 2:Raising an Event

Raise an event with the following properties:– Event name: oracle.apps.wf.event.wf.send– Event key: XX32


Practice 2 SolutionIn this practice, you will raise an event manually from the Raise Event page.The event you raise should trigger a predefined subscription that launches aworkflow process. The focus of this practice is on using the Raise Event page;however, you can review the workflow process in the Workflow Monitor toconfirm that the event was raised successfully.


2. Choose the Raise Event link.3. In the Event Name field, select oracle.apps.wf.event.wf.send. This is the

predefined Workflow Send Protocol event used in the Workflow SendProtocol process.

4. In the Event Key field, enter a unique event key such as XX32.5. For the purposes of this practice, since you will not perform further

processing on this event, you do not need to enter any event data. Leavethe Event Data field blank.

6. Choose the Submit button to raise the event.7. Choose OK in the confirmation window. When the oracle.apps.wf.event.wf.send event is raised on the local system,

it triggers a predefined subscription that sends the event to the WorkflowSend Protocol process. However, since you did not specify a recipient for



the event message in the subscription, the process will simply completewithout performing any further processing.

You can review the status of the process in the Workflow Monitor bychoosing the Find Processes link from the Workflow home page andsearching for the process with the Workflow Send Protocol item type andwith your event key as the item key.



Practice 2: Raising an Event


Practice 2:Raising an Event

Practice 2 SolutionWhen you raise your event for this practice, the raise event details should looksimilar to this.



Summary


Summary

In this lesson, you should have learned how to:• Define individual events.• Describe the abstract datatypes used by the

Business Event System.• Define event groups.• Raise events.• Use predefined Oracle Workflow events.


Systems and AgentsChapter 4 - Page 1

Systems and AgentsChapter 4



Systems and Agents


Systems and Agents



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Define systems.• Define communication agents on systems.• Associate queues and queue handlers with

agents.



Systems


Systems

• A system is a logically isolated softwareenvironment such as a host machine or databaseinstance.

• Define each system to or from which you willcommunicate events in the Event Manager.



Local System


Local System

• When you install Oracle Workflow in a database,that database is automatically defined as a systemin the Event Manager.

• The system name is set to the database globalname.

• This system is automatically set as the localsystem in the Global Workflow Preferences page.



Defining a System


Defining a System

To Define a System:1. Use a web browser to connect to the following URL: <webagent>/wf_event_ html.listsystems Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Systems web page from the Oracle Workflow


Event Manager web pages.2. The Systems page appears, displaying a list of existing systems. An

asterisk marks the local system. Choose the Add System button to open the Edit System page.3. Enter the internal name of the system in the Name field. Note: The internal name must be all-uppercase and should not include any

single or double quotation marks (' or ") or spaces.4. Enter a display name for the system.5. Enter an optional description for the system.6. Optionally select a master system from which you want this system to

receive Event Manager object definition updates. Click on the Masterfield's up arrow icon to display a list of systems from which to choose.

7. Choose the Submit button to save the system.



Finding a System


Finding a System

• Use the Find System page to locate a specificsystem definition.

• Search for systems by entering the followingcriteria:– Name– Display Name– Master

Finding a SystemTo access the Find System web page, use a web browser to connect to thefollowing URL:<webagent>/wf_event_html.findsystemReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Find System web page from the Oracle Workflow homepage, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.



Updating or Deleting a System


Updating or Deleting a System

Locate the system you want in the Systems page.• To view the subscriptions for a system, choose

the schedule icon in the Subs column for thatsystem.

• To update a system, choose the pencil icon in theEdit column for that system.

• To delete a system, choose the trash icon in theDelete column for that system, andchoose OK in the confirmationwindow that appears.

Updating or Deleting a SystemTo access the Systems web page, use a web browser to connect to the followingURL:<webagent>/wf_event_html.listsystemsReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Systems web page from the Oracle Workflow homepage, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.Subscriptions to a SystemFor systems that do not have any subscriptions yet, a blank schedule iconappears. For systems that do have subscriptions referencing them, a fullschedule icon appears.You can begin defining a new subscription for the system by choosing the AddSubscription button in the Event Subscriptions page. The Edit Subscription pageappears with the system name automatically entered in the System field.Deleting a SystemYou can only delete systems that do not have any agents defined on them or anysubscriptions referencing them.



Agents


Agents

• An agent is a named point of communicationwithin a system.

• A single system can have several different agentsrepresenting different communication alternatives,such as different protocols or propagationfrequencies.

• Define each agent that you will use tocommunicate events in the EventManager.



Agents


Agents

• Communication within and between systems isaccomplished by sending a message from oneagent to another.

• Each agent on a Workflow-enabled system isassociated with an AQ queue.

• The Business Event System interacts with theagent by enqueuing or dequeuing event messageson its queue.



Agent Properties


Agent Properties

An agent definition in the Event Manager includes thefollowing properties:• Internal Name—Must be unique within the agent’s

system• Display Name• System



Agent Properties


Agent Properties

An agent definition in the Event Manager includes thefollowing properties:• Direction—Either inbound or outbound

communication on the agent’s system• Protocol—Communication protocol that specifies

how messages are encoded and transmitted• Address—Address at which systems can

communicate with an inbound agent

Agent PropertiesDirectionAn agent can support only one direction of communication on its system:

• In—The agent receives messages in a specific protocol and presents themto the system in a standard format.

• Out—The agent accepts messages from the system in a standard formatand sends them using the specified protocol.

ProtocolFor a message to be successfully communicated, the sending and receivingagents must use the same protocol.You can either use AQ to perform the propagation of messages by the SQLNETprotocol which it supports, or you can implement an external service, such asOracle Message Broker, to propagate messages by a different protocol.Integration with Oracle Message Broker provides support for HTTP and HTTPSprotocols and enables integration with third party messaging solutions.AddressThe address format for an inbound agent depends on the agent's protocol. Foragents that use the SQLNET protocol, the address must be in the followingformat:<schema>.<queue>@<database link>In this format, <schema> represents the schema that owns the queue, <queue>represents the name of the queue associated with the agent, and <database link>



represents the name of the database link to the instance where the queue islocated.Note: You must enter the database link name exactly as the name was specifiedwhen the database link was created. The names of the database links that youwant to use for the Business Event System should be fully qualified with thedomain names.



Agent Properties


Agent Properties

An agent definition in the Event Manager includes thefollowing properties:• Queue—AQ queue used by the Business Event

System to interact with the agent• Queue Handler—PL/SQL package that translates

between the standard Workflow event messageformat and the format required by the agent'squeue

Agent PropertiesQueueEach agent on a Workflow-enabled system should be associated with an AQqueue.

• Outbound agent—To send messages, the system enqueues the messageson the queue and sets the recipient addresses.

• Inbound agent— To receive messages, the system runs a queue listener onthe queue.

Specify the queue using the following format:<schema>.<queue><schema> represents the schema that owns the queue and <queue> representsthe queue name.Queue HandlerEvent messages within the Business Event System are encoded in a standardformat defined by the datatype WF_EVENT_T. You must assign each agent aqueue handler to enqueue and dequeue messages on the agent’s queue,translating between the standard Workflow format and the format required bythe queue.You can either use a queue handler provided by Oracle Workflow or create yourown custom queue handler.



Standard Queue Handlers


Standard Queue Handlers

• WF_EVENT_QH Use for normal Business Event System processing

with queues using SQLNET propagation and thepayload type WF_EVENT_T

• WF_ERROR_QH Use for error queues with SQLNET propagation

and the payload type WF_EVENT_T• WF_EVENT_OMB_QH Use if you implement Oracle Message Broker to

propagate messages by another protocol such asHTTP



Custom Queue Handlers


Custom Queue Handlers

Enqueue Logic

Dequeue Logic

WF_EVENT_T Event Message

Custom Abstract Data Type

Custom Queue HandlersA custom queue handler must translate between the standard WF_EVENT_Tevent message structure and your custom Abstract Data Type (ADT).Queue handler packages must include the following standard APIs:

• Enqueue procedure enqueue (p_event in WF_EVENT_T,

p_out_agent_override in WF_AGENT_T);

Arguments:– p_event—The event message.– p_out_agent_ override—The outbound agent on whose queue the

event message should be enqueued, overriding the outbound agentspecified within the event message.

• Dequeue procedure dequeue (p_agent_guid in raw,

p_event out WF_EVENT_T)

Arguments :– p_agent_guid—The globally unique identifier of the inbound agent

from whose queue the event message should be dequeued.– p_event—The event message.




Standard Agents


Standard Agents

• When you install Oracle Workflow, three standardagents are automatically defined on the localsystem.– WF_IN—Standard inbound agent– WF_OUT—Standard outbound agent– WF_ERROR—Standard agent for error

handling• The standard agents use automatically defined

queues with the SQLNET protocol, theWF_EVENT_T payload type, and theWF_EVENT_QH queue handler.

Standard AgentsOracle Workflow provides WF_IN and WF_OUT as default agents that you canuse to receive and send events without needing to define any custom agents.You can optionally define additional inbound and outbound agents to expandyour event processing. For example, you can define custom agents for:

• Propagation of event messages by different protocols or with differentfrequencies

• Increased scalability• Additional levels of service—for instance, if you have five outbound

agents, and one agent stops functioning, you can still send messages fromthe other four agents



Defining an Agent


Defining an Agent

To Define an Agent:1. Use a web browser to connect to the following URL: <webagent>/wf_event_ html.listagents Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Systems web page from the Oracle Workflow


Event Manager web pages.2. The Agents page appears, displaying a list of existing agents grouped by

the system where they are located. Choose the Add Agent button to open the Edit Agent page.3. Enter the internal name of the agent in the Name field. The agent's internal

name must be unique within the agent's system. Note: The internal name must be all-uppercase and should not include any

single or double quotation marks (' or ") or spaces.4. Enter a display name for the agent.5. Enter an optional description for the agent.6. Select the message communication protocol that the agent supports.7. If the agent supports inbound communication to its system, enter the

address for the agent. The format of the address depends on the protocolyou select.



For agents that use the SQLNET protocol, the address must be in thefollowing format to enable AQ propagation:

<schema>.<queue>@<database link> <schema> represents the schema that owns the queue, <queue> represents

the queue name, and <database link> represents the database link to theinstance where the queue is located.

8. Enter the system in which the agent is defined. Click on the System field'sup arrow icon to display a list of systems from which to choose.

9. Enter the queue handler for the agent. Note: You must enter the queue handler name in all uppercase.10. Enter the name of the queue that the local system uses to interact with the

agent. Since only the local system refers to this queue name, the queuename should be within the scope of this system, without requiring adatabase link. Use the following format to specify the queue name:

<schema>.<queue> <schema> represents the schema that owns the queue, and <queue>

represents the queue name. Note: You must enter the queue name in all uppercase.11. In the Direction field, select In for an agent that supports inbound

communication to its system, or select Out for an agent that supportsoutbound communication from its system.

12. In the Status field, select Enabled or Disabled as the agent status. If youdisable an agent, it still remains in the Agents list for reference, but youcannot use the agent in active subscriptions.

13. Choose the Submit button to save the agent.



Finding an Agent


Finding an Agent

• Use the Find Agent page to locate a specific agentdefinition.

• Search for agents by entering the followingcriteria:– Name– Protocol– Address– System– Direction– Status

Finding an AgentTo access the Find Agent web page, use a web browser to connect to thefollowing URL:<webagent>/wf_event_html.findagentReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Find Agent web page from the Oracle Workflow homepage, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.



Updating or Deleting an Agent


Updating or Deleting an Agent

Locate the agent you want in the Agents page.• To update an agent, choose the pencil icon in the

Edit column for that agent.• To delete an agent, choose the trash icon in the

Delete column for that agent, and choose OK inthe confirmation window that appears.

Updating or Deleting an AgentTo access the Agents web page, use a web browser to connect to the followingURL:<webagent>/wf_event_html.listagentsReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Agents web page from the Oracle Workflow homepage, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.Deleting an AgentYou can only delete agents that do not have any subscriptions referencing them.



Review Questions


Review Questions

1. What is the definition of a system?2. What is the definition of an agent?3. What does a queue handler do?4. What are the three standard agents in an Oracle

Workflow installation?

Review Questions and Solutions1. What is the definition of a system? A system is a logically isolated software environment such as a host

machine or database instance.2. What is the definition of an agent? An agent is a named point of communication within a system.3. What does a queue handler do? A queue handler enqueues and dequeues messages on an agent’s

queue, translating between the standard Workflow format and theformat required by the queue.

4. What are the three standard agents in an Oracle Workflow installation? The three standard agents automatically defined on the local system

when you install Oracle Workflow are:– WF_IN—Standard inbound agent– WF_OUT—Standard outbound agent– WF_ERROR—Standard agent for error handling



Summary


Summary

In this lesson, you should have learned how to:• Define systems.• Define communication agents on systems.• Associate queues and queue handlers with

agents.




Event SubscriptionsChapter 5 - Page 1

Event SubscriptionsChapter 5



Event Subscriptions


Event Subscriptions



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Describe the types of processing a subscription

can include.• Define subscriptions.• Define subscription rule functions.• Use predefined Oracle Workflow subscriptions.• Apply Business Event System APIs.



Event Subscriptions


Event Subscriptions

• Define subscriptions in the Event Manager tospecify the processing that you want to performwhen events occur.

• Whenever an event is raised locally or receivedfrom an external source, the Event Managersearches for and executes any activesubscriptions by the local system to that event orto the Any event.

Event SubscriptionsIf no active subscriptions exist for the event that occurred, then you canoptionally handle the event by having Oracle Workflow execute any activesubscriptions to the Unexpected event.



Event Manager Subscription Processing


Event Manager Subscription Processing

LISTENExternal Events

RAISELocal Events

Application

AQ

Rule Function

WorkflowProcess

Send toAgent

Matching Event Subscription

Event Dispatcher

Event Manager Subscription ProcessingSubscriptions can include the following types of processing:

• Running a function on the event message• Sending the event message to a workflow process• Sending the event message to a local or external agent



Subscription Properties



A subscription definition in the Event Managerincludes the following properties:• Subscriber—The system where you want the

subscription to execute• Source Type—Local, External, or Error• Event Filter—The triggering event

Subscription PropertiesSubscriberEach subscription defines an action on exactly one system, so you should definea separate subscription for each system involved in the processing you want toperform. For example, if you want to propagate data from one system toanother, you should define one subscription for the sending system, and anothersubscription for the receiving system.Note: You can define and store subscriptions for multiple systems in the EventManager on your local system, and use predefined events and subscriptions toreplicate those subscriptions to other systems. However, only subscriptions withthe local system as the subscriber are triggered when events are raised orreceived on the local system.Source TypeSubscriptions can have the following source types:

• Local—The subscription applies only to events raised on the subscribingsystem.

• External—The subscription applies only to events received by an inboundagent on the subscribing system.

Note: All event messages received by an inbound agent on the subscribingsystem are considered to have an External source, whether the sendingagent is located on a remote system or on the local system.



• Error—The subscription applies to only to errored events dequeued fromthe WF_ERROR agent’s queue.

Event FilterYou can choose either an individual event or an event group. If you choose anevent group, the subscription will be triggered whenever any one of the group'smember events occurs.






A subscription definition in the Event Managerincludes the following properties:• Phase—The order in which subscriptions to the

same event are executed• Rule Data—Key or Message

Subscription PropertiesPhaseIf you define multiple subscriptions to the same event, you can control the orderin which the Event Manager executes those subscriptions by specifying a phasenumber for each subscription.Subscriptions are executed in ascending phase order. For example, you canenter 10 for the subscription that you want to execute first when an eventoccurs, 20 for the subscription that you want to execute second, and so on.You can use phases to ensure that different types of actions are performed in theappropriate order, such as executing subscriptions that perform validationbefore subscriptions that perform other types of processing.Rule DataDepending on the processing to be performed, a subscription may have thefollowing rule data requirements:

• Key—Requires only the event key that identifies the instance of the event• Message—Requires the complete set of event information contained in the

event dataYou can improve performance by specifying Key as the rule data forsubscriptions that do not require the complete event data. If an event is raisedlocally and any subscriptions to that event require the complete event data, thenthe Event Manager will run the Generate function for the event to produce theevent data. However, if no subscriptions to the event require the event data, then



the Event Manager will not run the Generate function, minimizing the resourcesrequired to execute the subscriptions.



Subscription Actions: Running a Rule Function


Subscription Actions:Running a Rule Function

• A subscription can include a rule function that isexecuted on the event message.

• Oracle Workflow provides a standard default rulefunction, WF_RULE.Default_Rule, that can:– Send the event message to a workflow

process– Send the event message to an agent

• Oracle Workflow provides some standardrule functions for testing and debugging.

• You can extend your subscriptionprocessing by creating custom rulefunctions.

Subscription Actions: Running a Rule Function• If you specify a rule function for a subscription, you can also specify in

the subscription any additional parameters that you want to pass to thefunction.

• If you use the default rule function, you should specify in the subscriptionthe workflow process or the agent (or both) where you want to send theevent message.

• If you enter a rule function other than the default function, you can stillenter workflow and agent information for your function to reference, butOracle Workflow does not automatically send the event message to thespecified workflow and agent. Instead, you must either explicitly includethe send processing in your rule function, or define a separate subscriptionthat does use the default rule function to perform the send processing.

• Custom rule functions must be defined according to a standard API.



Subscription Actions: Running a Rule Function


Subscription Actions:Running a Rule Function

Some possible uses for a rule function are:• Performing validation• Processing inbound messages as a Receive

message handler for an application• Making modifications to an outbound message,

such as adding a correlation ID that associatesthis message with other messages

Subscription Actions: Running a Rule Function• The rule function controls the behavior of the processing performed for

the subscription.• If a rule function modifies the event message, any subsequent

subscriptions executed on the event will access the changed message.



Predefined Rule Functions


– Log– Workflow_Protocol– Error_Rule

Predefined Rule Functions

• Oracle Workflow provides some standard rulefunctions that you can use for basic subscriptionprocessing, testing and debugging, or otherpurposes.

• The following rule function APIs are defined in aPL/SQL package called WF_RULE:– Default_Rule– Error– Warning– Success

Predefined Rule Functions• Default_Rule—Performs default subscription processing on the event

message when no rule function is specified for an event subscription,including:

– Sending the event message to a workflow process, if specified in thesubscription definition

– Sending the event message to an agent, if specified in thesubscription definition

• Error—Returns the status code ERROR and sets a specified error messageinto the event message.

• Warning—Returns the status code WARNING and sets a specified errormessage into the event message.

• Success—Returns the status code SUCCESS.• Log—Outputs the contents of the event message to a SQL*Plus session

using DBMS_OUTPUT.put_line.• Workflow_Protocol—Sends the event message to the workflow process

specified in the subscription, which should in turn send the event messageto the inbound agent specified in the subscription.

• Error_Rule—Performs the same subscription processing as Default_Rule,but reraises any exception that is encountered.



Custom Rule Functions


Custom Rule Functions

• Rule functions must follow a standard API.• A rule function may read or write to the event

message or perform any other database action.• However, you should never commit within a rule

function. The Event Manager never issues acommit as it is the responsibility of the callingapplication to commit.

• A rule function must not change the connectioncontext in any way, including security and NLSsettings.

Custom Rule FunctionsA rule function for an event subscription must have the following standard API:

function <function_name>

(p_subscription_guid in raw,

p_event in out WF_EVENT_T) return varchar2 is

<local declarations>

begin

<your executable statements>

<optional code for WARNING>

WF_CORE.CONTEXT('<package name>',

'<function name>', p_event.getEventName( ),

p_subscription_guid);

WF_EVENT.setErrorInfo(p_event, 'WARNING');

return 'WARNING';



return 'SUCCESS';

exception

when others then

WF_CORE.CONTEXT('<package name>','<function name>', p_event.getEventName( ),

p_subscription_guid);

WF_EVENT.setErrorInfo(p_event, 'ERROR');

return 'ERROR';

end;

Arguments:• p_subscription_ guid—The globally unique identifier for the subscription.• p_event—The event message.

The function must return one of the following status codes:• SUCCESS—The rule function completed successfully.• WARNING—A warning condition occurred. The rule function reports a

warning message using the Workflow Core error APIs and sets thewarning information into the event message. The Event Manager places acopy of the event message on the WF_ERROR queue, but subscriptionprocessing continues.

• ERROR—An error occurred. The rule function reports an error messageusing the Workflow Core error APIs and sets the error information into theevent message. The Event Manager halts subscription processing for thisevent, rolls back any subscriptions already executed for the event, andplaces the event message on the WF_ERROR queue.




Subscription Actions: Sending an Event to a WorkflowProcess


Subscription Actions:Sending an Event to a Workflow Process

• To send an event to a workflow process, youmust:– Specify in the subscription the item type and

process name of the process.– Either use the default rule function or include

send processing in your custom rule function.• The item key for the process is determined either

by the correlation ID specified in theevent message, or by the event key ifno correlation ID is specified.

Subscription Actions: Sending an Event to a Workflow Process• By sending an event to a workflow process, you can model complex

processing or routing logic beyond the options of directly running apredefined function or sending the event to a predefined recipient.

• For example, you can branch to different functions, initiate subprocesses,send notifications, or select recipient agents, based on the contents of theevent message, or modify the event message itself.

• If you specify a workflow process, you can also specify in the subscriptionany additional parameters that you want to set as item attributes for theworkflow process. If the corresponding item attributes do not already existin the item type, Oracle Workflow automatically defines the itemattributes when the event is sent to the process.

• The subscription's globally unique identifier (GUID) is set as a dynamicitem attribute so that the workflow process can reference other informationin the subscription definition.

• If you want to send an event to a workflow process from within a customrule function, call:

– WF_ENGINE.Event( ) to send the event message to a workflowprocess only



– WF_RULE.Default_Rule( ) to include the default subscriptionprocessing that can send the event message both to a workflowprocess and to an agent



Subscription Actions: Sending an Event to an Agent


Subscription Actions:Sending an Event to an Agent

• To send an event to an agent, you must:– Specify in the subscription the To Agent that

you want to receive the inbound message.– Either use the default rule function or include

send processing in your custom rule function.• You can also optionally:

– Specify the Out Agent that you wantto send the outbound message.

– Specify the priority with which therecipient should dequeue themessage.

Subscription Actions: Sending an Event to a Workflow Process• If you do not specify an Out Agent, Oracle Workflow selects an outbound

agent on the subscribing system whose queue type matches the queue typeof the To Agent.

• If you want to send an event to an agent from within a custom rulefunction, call:

– WF_EVENT.Send( ) to send the event message to an agent only– WF_RULE.Default_Rule( ) to include the default subscription

processing that can send the event message both to a workflowprocess and to an agent



Defining a Subscription


Defining a Subscription

To Define a Subscription:1. Use a web browser to connect to the following URL: <webagent>/wf_event_ html.listsubscriptions Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Event Subscriptions web page from the Oracle

Workflow home page, <webagent>/wfa_html.home. Note: You must have workflow administrator privileges to access the

Event Manager web pages.2. The Event Subscriptions page appears, displaying a list of existing

subscriptions grouped by the subscribing system and triggering event. Choose the Add Subscription button to open the Edit Subscription page.3. In the Subscriber region, enter the system where the subscription executes.

Click on the System field's up arrow icon to display a list of systems fromwhich to choose.

4. In the Triggering Condition region, specify the type of source system towhich the subscription applies in the Source Type field.

– Local—The subscription applies only to events raised on thesubscribing system.

– External—The subscription applies only to events received by aninbound agent on the subscribing system.



Note: All event messages received by an inbound agent on thesubscribing system are considered to have an External source,whether the sending agent is located on a remote system or on thelocal system.

– Error—The subscription applies to only to errored events dequeuedfrom the WF_ERROR agent’s queue.

5. Enter the event to which the subscription applies in the Event Filter field.Click on the Event Filter field's up arrow icon to display a list of eventsfrom which to choose.

6. Enter an optional source agent to which the subscription applies. If youspecify a source agent, then the subscription is executed only when thetriggering event is received from that agent. Click on the Source Agentfield's up arrow icon to display a list of agents from which to choose.

Note: In most cases, the Source Agent field is left blank.7. In the Execution Control region, enter an optional phase number for the

subscription to specify the order in which subscriptions that apply to thesame event are executed.

8. Select Enabled or Disabled as the subscription status. If you disable asubscription, it still remains in the Event Subscriptions list for reference,but it can no longer be actively used to respond to events.

9. In the Rule Data field, specify the event information required by thesubscription.

– Key—The subscription requires only the event key.– Message—The subscription requires the complete event data.

10. In the Action region, define the subscription processing you want toperform when the triggering event occurs.

11. If you want to run a function on the event message, enter the RuleFunction to run.

If you do not specify a rule function, Oracle Workflow runs a default rulefunction to send the event message to the workflow process and the agentthat you specify.

12. If you want to send the event message to a workflow process, enter theitem type that the process belongs to in the Workflow Item Type field andthe name of the process in the Workflow Process Name field. Click oneach field's up arrow icon to display a list of values from which to choose.

Note: The list of values for the Workflow Process Name field includesonly the runnable processes within the item type you specify.

13. If you want to send the event to an agent, optionally enter the Out Agentthat you want to send the outbound message. Click on the Out Agentfield's up arrow icon to display a list of values from which to choose.

Note: The Out Agent must be located on the subscribing system. The listof values for the Out Agent field includes only agents with a direction ofOut.



14. If you want to send the event to an agent, enter the To Agent that you wantto receive the inbound message. Click on the To Agent field's up arrowicon to display a list of values from which to choose.

Note: The list of values for the To Agent field includes only agents with adirection of In.

15. If you want to send the event message to an agent, select Normal, High, orLow as the priority with which the recipient should dequeue the message.

16. Optionally enter any additional parameters for the rule function orworkflow process in the Parameters field. Use spaces to separate theparameters, and specify the name and value for each parameter in thefollowing format:

<name1>=<value1> <name2>=<value2> ... <nameN>=<valueN>17. If you use a program to create subscription definitions automatically, the

Event Manager displays owner information set by that program in theOwner Name and Owner Tag fields in the Documentation region. You canuse the Edit Subscription page to update this information manually ifnecessary.

18. Enter an optional description for the subscription.19. Choose the Submit button to save the subscription.



Finding a Subscription


Finding a Subscription

• Use the Find Subscription page to locate a specificsubscription definition.

• Search for subscriptions by entering the followingcriteria:– System– Source Type– Event– Status

Finding a SubscriptionTo access the Find Subscription web page, use a web browser to connect to thefollowing URL:<webagent>/wf_event_html.findsubscriptionReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Find Subscription web page from the Oracle Workflowhome page, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.



Updating or Deleting a Subscription


Updating or Deleting a Subscription

Locate the subscription you want in the EventSubscriptions page.• To update a subscription, choose the pencil icon

in the Edit column for that subscription.• To delete a subscription, choose the trash icon in

the Delete column for that subscription, andchoose OK in the confirmation window thatappears.

Updating or Deleting a SubscriptionTo access the Event Subscriptions web page, use a web browser to connect tothe following URL:<webagent>/wf_event_html.listsubscriptionsReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the Event Subscriptions web page from the OracleWorkflow home page, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.



Predefined Subscriptions



• Oracle Workflow provides default subscriptions tosome of the predefined Workflow events.

• The subscriber for all the predefined subscriptionsis the local system.

• You can update, enable, or disable some of thesesubscriptions to perform the event processing thatyou want.






• Seed Event Group• System Signup• Any• Unexpected• Ping Agent• Acknowledge Ping

• Workflow SendProtocol

• Workflow SendProtocolAcknowledgement

Oracle Workflow provides predefined subscriptionsfor the following events:

Predefined SubscriptionsSeed Event GroupOracle Workflow provides two predefined subscriptions to the Seed EventGroup. These subscriptions can be triggered by any of the group’s memberevents. The Seed Event Group includes all the event, event group, system,agent, and subscription definition events, as well as the Synchronize EventSystems event.

• The first subscription can send the Event Manager data to an agent and toa workflow process when one of the group member events is raisedlocally. To use this subscription, you must add the agent or workflow towhich you want to send the data, and enable the subscription.

• The second subscription can load the Event Manager data into the localsystem when one of the group member events is received from an externalsource. To use this subscription, you must enable it.

System Signup EventOracle Workflow provides one predefined subscription to the System Signupevent that loads the Event Manager data into the local system when the SystemSignup event is raised locally.Any EventOracle Workflow provides three predefined subscriptions to the Any event.



• The first subscription can be triggered when an event is raised locally. Touse this subscription, you must define the action for the subscription andenable it.

• The second subscription can be triggered when an event is received froman external source. To use this subscription, you must define the action forthe subscription and enable it.

• The third subscription sends the event message to the Default Event Errorprocess in the System: Error item type and raises an exception when anevent is received from an Error source (that is, when it is dequeued fromthe WF_ERROR queue).

Attention: You must not change or disable the definition of thepredefined Error subscription to the Any event. If you do, the EventManager will not be able to perform error handling for event andsubscription processing.

Unexpected EventOracle Workflow provides two predefined subscriptions to the Unexpectedevent.

• The first subscription can send the event message to the Default EventError process in the System: Error item type when the Unexpected event israised locally. To use this subscription, you must enable it.

Attention: If you want to enable this subscription, be careful to considerall the events that can be raised on your local system and trigger thesubscription. Many local events may be raised to which you do not want tosubscribe. Additionally, if a large number of events are raised on the localsystem, enabling this subscription may flood the Business Event System.

• The second subscription sends the event message to the Default EventError process in the System: Error item type when the Unexpected event isreceived from an external source. This subscription allows your localsystem to handle any event messages received from external systems thatyou were not expecting.

Ping Agent Events• Ping Agent—Oracle Workflow provides one predefined subscription to

the Ping Agent event that sends the Acknowledge Ping event back to theoriginating system when the Ping Agent event is received from an externalsource.

• Acknowledge Ping—Oracle Workflow provides one predefinedsubscription to the Acknowledge Ping event that sends the AcknowledgePing event to the Detail Ping process in the Workflow AgentPing/Acknowledge item type when the event is received from an externalsource.

Workflow Send Protocol Events• Workflow Send Protocol—Oracle Workflow provides two predefined

subscriptions to the Workflow Send Protocol event.



– The first subscription sends the event message to the WorkflowEvent Protocol process in the Workflow Send Protocol item typewhen the Workflow Send Protocol event is raised locally. Asubscription parameter specifies that the message requires anacknowledgement. You can add an outbound agent and inboundagent to the subscription to specify where you want the WorkflowEvent Protocol process to send the event message.

– The second subscription sends the event message to the WorkflowEvent Protocol process in the Workflow Send Protocol item typewhen the Workflow Send Protocol event is received from an externalsource. You can optionally add an outbound agent and inbound agentto the subscription to specify that you want the Workflow EventProtocol process to send the event message on to another agent.

• Workflow Send Protocol Acknowledgement—Oracle Workflow providesone predefined subscription to the Workflow Send ProtocolAcknowledgement Event that sends the event message to the WorkflowEvent Protocol process in the Workflow Send Protocol item type when theWorkflow Send Protocol Acknowledgement event is received from anexternal source.




Event APIs


– Enqueue– Listen– SetErrorInfo

Event APIs

• The Event APIs can be called by an applicationprogram or a workflow process in the runtimephase to communicate with the Business EventSystem and manage events.

• The following APIs are defined in a PL/SQLpackage called WF_EVENT:– Raise– Send– NewAgent– Test

Event APIs• Raise—Raises a local event to the Event Manager.• Send—Sends an event message from one agent to another.• NewAgent—Creates a WF_AGENT_T structure for the specified agent

and sets the agent's system and name into the structure.• Test—Tests for the most costly data requirement among subscriptions to

an event.• Enqueue—Enqueues an event message onto a queue associated with an

outbound agent.• Listen—Monitors an agent for inbound event messages and dequeues

messages using the agent's queue handler. Note: If you are using the version of Oracle Workflow embedded in

Oracle Applications, you can also use the "Workflow Listen Process"concurrent program to listen for inbound event messages.

• SetErrorInfo—Retrieves error information from the error stack and sets itinto the event message.




Event Function APIs


Event Function APIs

• The Event Function APIs provide utility functionsthat can be called by an application program, theEvent Manager, or a workflow process in theruntime phase to communicate with the BusinessEvent System and manage events.

• The following APIs are defined in a PL/SQLpackage called WF_EVENT_FUNCTIONS_PKG:– Parameters– SubscriptionParameters– AddCorrelation– Generate– Receive

Event Function APIs• Parameters—Parses a string of text containing parameters and returns the

parsed parameters in a varray.• SubscriptionParameters—Returns the value for a parameter from a text

string containing the parameters defined for an event subscription.• AddCorrelation—Adds a correlation ID to an event message when used as

a rule function for subscription processing.• Generate—Generates the event data for events in the Seed Event Group.• Receive—Receives Business Event System object definitions when used

as a rule function for subscription processing and loads the definitions intothe appropriate Business Event System tables.




Practice 1 Overview


Practice 1 Overview

This practice covers the following topics:• Defining a subscription in the Event Manager• Raising an event to trigger the subscription



Practice 1: Defining a Subscription


Practice 1:Defining a Subscription

1. Define a subscription with the following properties:– System: <local system>– Source Type: Local– Event Filter: XX.oracle.workflow.bes.event.new– Rule Data: Key– Rule Function: WF_RULE.Success

Replace ‘XX’ with your terminal number.2. Raise the XX.oracle.workflow.bes.event.new event

to trigger your subscription.

Practice 1 SolutionIn this practice, you will define a subscription that runs the predefined rulefunction WF_RULE.Success. Then you will raise an event to trigger yoursubscription. Because the WF_RULE.Success function does not perform anyprocessing other than returning the status code SUCCESS, there will be noresult visible in the Workflow web pages after the subscription is executed. Foran indication that the subscription was executed successfully, you can optionallycheck the Worklist to ensure that no error notification was generated.Note: Because many students access the system and create objects during thiscourse, you need a way to distinguish between the objects created by you and byyour classmates. Therefore, you will be assigned a terminal number by yourinstructor. Use this number as a prefix wherever you see XX included in thename of something you are defining. In this way, you can ensure that thedefinitions you create are unique.Step 1


2. Choose the Event Subscriptions link.3. In the Event Subscriptions page, choose the Add Subscription button to

open the Edit Subscription page.4. In the System field, select the local system as the subscriber.5. In the Source Type field, select Local.



6. In the Event Filter field, select the XX.oracle.workflow.bes.event.newevent that you defined in the Defining an Event practice. If you have notperformed this practice, select an event provided by your instructor.

7. Leave the Source Agent field blank.8. Enter 10 in the Phase field.9. In the Status field, select Enabled.10. In the Rule Data field, select Key.11. Enter WF_RULE.Success in the Rule Function field.12. Leave the Workflow Item Type, Workflow Process Name, Out Agent, To

Agent, Parameters, Owner Name, and Owner Tag fields blank. Leave thePriority field set to the default value, which is Normal.

13. In the Description field, enter XX New Event Subscription.14. Choose the Submit button to save the subscription.

Step 21. Navigate back to the Oracle Workflow home page.2. Choose the Raise Event link.3. In the Event Name field, select XX.oracle.workflow.bes.event.new, or

whichever event you defined as the event filter for your subscription.4. In the Event Key field, enter a unique event key such as XX51.5. For the purposes of this practice, since you will not perform further


6. Choose the Submit button to raise the event.7. Choose OK in the confirmation window.

The WF_RULE.Success function does not produce any visible results in theWorkflow web pages. However, for an indication that the subscription wasexecuted successfully, you can optionally choose the Worklist link from theOracle Workflow home page to ensure that no error notification was generated.






Practice 1 SolutionWhen you complete this practice, the subscription definition should look similarto this.









Summary


Summary

In this lesson, you should have learned how to:• Describe the types of processing a subscription

can include.• Define subscriptions.• Define subscription rule functions.• Use predefined Oracle Workflow subscriptions.• Apply Business Event System APIs.


Configuring Oracle Workflow for Event CommunicationChapter 6 - Page 1

Configuring Oracle Workflowfor Event CommunicationChapter 6



Configuring Oracle Workflow for Event Communication


Configuring Oracle Workflow for EventCommunication



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Check the Business Event System setup.• Schedule listeners for inbound agents.• Schedule propagation for outbound agents.• Sign up systems with each other for event

message propagation.• Synchronize Business Event System data on

different systems.• Review event messages on local agents.



Checking Business Event System Setup



Use the Check Setup web page to verify theserequired parameters and components:• Database init.ora parameters

– AQ_TM_PROCESSES– JOB_QUEUE_INTERVAL– JOB_QUEUE_PROCESSES

• Database links• Local agents and their queues

Checking Business Event System SetupDatabase Init.ora Parameters

• AQ_TM_PROCESSES—This parameter enables the time managerprocess in Oracle8i Advanced Queuing (AQ). The time manager processis required by Oracle Workflow to monitor delay events in queues. Theminimum recommended number of time manager processes for OracleWorkflow is one.

• JOB_QUEUE_INTERVAL—Specify the job queue interval to determinehow frequently each SNP job queue process in your instance wakes up.Oracle Workflow requires the job queue interval to be less than or equal tothe latency parameter defined for your AQ propagation schedules, to allowqueues to be rechecked for messages with the specified latency. Therecommended job queue interval for Oracle Workflow is five seconds.

• JOB_QUEUE_PROCESSES—This parameter defines the number of SNPjob queue processes for your instance. Oracle Workflow requires jobqueue processes to handle propagation of Business Event System eventmessages by AQ queues. You must start at least one job queue process toenable message propagation. The minimum recommended number ofprocesses for Oracle Workflow is two.






To Check the Business Event System Setup:1. Use a web browser to connect to the following URL: <webagent>/wf_setup.check_all Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Check Setup web page from the Oracle Workflow


Event Manager web pages.2. In the Check Setup page, use the Database Init.ora Parameters region to

verify your settings for the database initialization parameters related toAQ. The Check Setup page displays the actual value defined for eachparameter as well as the minimum recommended value for OracleWorkflow.

Note: Setting the init.ora parameters is completed as part of the OracleWorkflow installation steps. After any change to the init.ora parameters,you must restart your database to make the change effective.

3. Use the Database Links region to verify your database links. You shouldcreate any required database links that do not yet exist. The database linkname as defined in the database must exactly match the database linkname entered as part of the address for an agent.



4. Use the Local Agents region to verify the queues that are set up for theagents defined on your local system. You should create any requiredqueues that do not yet exist.



Event Message Communication


Event Message Communication

Outbound Queue Inbound Queue

EventDispatcher

Propagate

Listen

Send

Event Message CommunicationTo send an event message, Oracle Workflow places the event message on alocal outbound agent’s queue. You must schedule a propagation to deliver themessage from there to the designated inbound agent’s queue.To receive an event message in Oracle Workflow, you must schedule an agentlistener to dequeue the message from the inbound agent’s queue for OracleWorkflow to process. A component of the Event Manager called the EventDispatcher then searches for and executes subscriptions to the event.



Agent Listeners


Agent Listeners

• An agent listener monitors an agent for inboundevent messages and dequeues messages for theEvent Manager to process.

• You should schedule a listener for each inboundagent on your local system.

• When an event message is received, the EventManager searches for and executes any activesubscriptions by the local system to that event orto the Any event with a source type of External.

Agent ListenersYou must schedule a listener for the standard WF_ERROR agent to enable errorhandling for the Business Event System. Also, if you want to use the standardWF_IN agent for event message propagation, schedule a listener for that agentas well.



Agent Listeners


Agent Listeners

• A listener starts monitoring the agent's queue onthe scheduled run day, dequeuing any inboundevent messages.

• The listener exits after all event messages on theagent's queue have been dequeued.

• Oracle Workflow reruns the listener indefinitely atthe scheduled interval.

• You can modify a listener’s schedule by updatingits settings or stop it altogether by deleting it.



Running Listeners


Running Listeners

You can run listeners by any of the followingmethods:• Check Setup web page• WF_EVENT.Listen( ) API• Wfagtlst.sql script• Workflow Listen Process concurrent program

(only for Oracle Workflow embedded in OracleE-Business Suite)

Running ListenersThe wfagtlst.sql script is intended primarily for debugging purposes.



Scheduling Listeners



To Schedule a Listener for an Inbound Agent:1. Use a web browser to connect to the following URL: <webagent>/wf_setup.check_all Replace <webagent> with the base URL of the web agent configured for



Event Manager web pages.2. In the Check Setup page, locate the agent you want in the Listeners for

Local Inbound Agents region.3. If no listeners are scheduled for the agent yet, the Scheduled status for the

agent is No. Choose the Create link in the Action column for that agent tocreate the first listener for the agent. The Edit Listener page appears,displaying the name of the selected agent.

If at least one listener is already scheduled for the agent, the Scheduledstatus for the agent is Yes. Choose the Edit link in the Action column forthat agent to create an additional listener. The Listeners page appears,displaying a list of existing listeners for the agent. Choose the Add button.The Edit Listener page appears, displaying the name of the selected agent.



4. In Edit Listener page, enter the date on which you want to start runningthe listener in the Run Day field. To start the listener on the current systemdate, leave this field blank.

5. In the Run Every fields, enter an interval to specify how often you wantthe listener to be run. You can specify the interval in days, hours, minutes,and seconds.

6. Choose the Submit button to save the listener schedule.








Updating or Deleting a Listener


Updating or Deleting a Listener

• Locate the agent you want in the Listeners forLocal Inbound Agents region of the Check Setuppage.

• Choose the Edit link in the Action column for thatagent to open the Listeners page.– To update a listener, choose the pencil icon in

the Edit column for that listener.– To delete a listener, choose the trash icon in

the Delete column for that listener, and chooseOK in the confirmation window thatappears.



Propagations


Propagations

• When you send an event message to an agent, theEvent Manager places the message on the queueassociated with the outbound agent.

• The message is then asynchronously delivered tothe recipient by propagation.

• You should schedule a propagation for eachoutbound agent on your local system.

PropagationsIf you want to use the standard WF_OUT agent for event message propagation,ensure that you schedule a listener for that agent.



Propagations


Propagations

• To schedule AQ propagations for agents that usethe SQLNET protocol, you can use the followingmethods:– Check Setup web page– Advanced Queue Propagation concurrent

program (only for Oracle Workflow embeddedin Oracle E-Business Suite)

• For agents that use other protocols, you mustprovide external propagation logic.

PropagationsIf you are using Oracle Message Broker (OMB), you should set up propagationthrough OMB rather than through Oracle Workflow.



Scheduling Propagations



To Schedule a Propagation for an Outbound Agent:1. Use a web browser to connect to the following URL: <webagent>/wf_setup.check_all Replace <webagent> with the base URL of the web agent configured for



Event Manager web pages.2. In the Check Setup page, the Propagations for Local Outbound Agents

region displays a list of the combinations of local outbound agents anddatabase links that may require propagations. This list matches each ofyour local outbound agents with each database link to a remote system thatappears in the addresses of the inbound agents you have defined. Eachlocal outbound agent is also listed with a Local destination in the DatabaseLink column for propagation to inbound agents on the local system.

Locate the outbound agent and database link combination for which youwant to schedule a propagation.

3. If no propagation is scheduled yet for the agent and database link youwant, choose the Create link in the Schedule column to schedule thepropagation. The Edit Propagation page appears.



4. In the Duration field, enter the duration of the propagation window, inseconds.

5. In the Run Every field, enter an interval in seconds to specify how oftenyou want a propagation window to occur.

Note: The run interval must be longer than the duration of the propagationwindow.

6. In the Latency field, enter a latency time in seconds to specify how longyou want to wait, after all messages have been propagated, beforerechecking the queue for new messages to the destination.

The latency represents the maximum wait time during the propagationwindow for a message to be propagated after it is enqueued. To propagatemessages as soon as possible after they are enqueued, enter a latency ofzero. The default latency is 60 seconds.

Note: To enable AQ to enforce the latency time, the job queue intervalsetting in your database initialization parameters must be less than orequal to the latency value.

7. Choose the Submit button to save the propagation schedule.








Updating or Deleting a Propagation


Updating or Deleting a Propagation

• Locate the outbound agent and database linkcombination that you want in the Propagations forLocal Outbound Agents region of the Check Setuppage.

• Choose the Edit link in the Schedule column forthat agent to open the Edit Propagation page.– To update the propagation, make your

changes to the settings in the Edit Propagationpage.

– To delete the propagation, choosethe Delete button.



Demonstration


Demonstration

This demonstration shows you how to:• Check the Business Event System setup• Schedule listeners for inbound agents• Schedule propagations for outbound agents



Signing Up Systems


Signing Up Systems

• Before sending events from one system toanother, you must sign up the destination systemwith the source system as a recipient of eventmessages.

• Signing up a system means defining thedestination system and its inbound agents in theEvent Manager of the source system.

• When the destination system is signedup, you can address event messagesfrom the source system to thedestination agents.

Signing Up SystemsUsually when you integrate two systems, both systems should be signed up witheach other, so that each system can both send messages to and receive messagesfrom the other system.



Signing Up Systems


Signing Up Systems

To sign up a destination system for receiving eventmessages from a source system:1. Retrieve the local system and inbound agent

definitions, which together make up the systemidentifier information, from the destination system.

2. Add the destination system identifier informationto the Event Manager in the source system.

Signing Up Systems• You can use the System Identifier web page on the destination system to

generate an XML document containing the system identifier information.• You can use the System Signup web page on the source system to add the

information by raising the System Signup event with the XML documentfrom the destination system as the event data. When the System Signupevent is raised on the source system, Oracle Workflow executes apredefined subscription that adds the system identifier information to theEvent Manger in that system.



Retrieving System Identifier Information


Retrieving System Identifier Information

• Connect to the System Identifier URL.• Oracle Workflow produces the system identifier

XML document, which contains the definitions ofthe local system and its inbound agents.

• Save this document as a text file.

Retrieving System Identifier InformationUse a web browser to connect to the following URL:<webagent>/wf_event_html.getsystemidentifierReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.You can also access the System Identifier web page from the Oracle Workflowhome page, <webagent>/wfa_html.home.Note: You must have workflow administrator privileges to access the EventManager web pages.System Identifier XML DocumentAfter you save the system identifier XML document as a text file, you can copythe document and enter it as the event data for the System Signup event whenyou sign this system up with a source system.



Signing Up Systems


Signing Up Systems

To Sign Up a System:1. Use a web browser to connect to the following URL: <webagent>/wf_event_html.entereventdetails?p_event_name=

oracle.apps.wf.event.system.signup Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the System Signup web page from the Oracle

Workflow home page, <webagent>/wfa_html.home. Note: You must have workflow administrator privileges to access the

Event Manager web pages.2. In the System Signup page, enter an event key that uniquely identifies this

instance of the event.3. Copy the XML document containing the destination system identifier

information into the Event Data field.4. Choose the Submit button to raise the System Signup event to the Event

Manager. A confirmation message is displayed. When the System Signup event is raised, Oracle Workflow executes a

predefined subscription that adds the system identifier information fromthe event data to the Event Manager.



Synchronizing Systems


Synchronizing Systems

• Synchronizing systems means replicating all theEvent Manager objects that are defined on thesource system to the target system.

• You can use the Synchronize Event Systems eventto synchronize systems with each other.

To Synchronize Systems:1. Sign up the source and target systems with each other.2. On the source system, modify the predefined subscription to the Seed

Event Group with the Local source type.– Specify the inbound agent on the target system that you want to

receive the event message, or specify a workflow process that sendsthe event message to the target system.

– Enable the subscription.3. On the target system, enable the predefined subscription to the Seed Event

Group with the External source type.4. On the source system, raise the Synchronize Event Systems event

(oracle.apps.wf.event.all.sync) using the Raise Event web page. Enter aunique event key, but leave the Event Data field blank.

When the Synchronize Event Systems event is raised on the sourcesystem, it triggers the subscription to the Seed Event Group with the Localsource type. The Event Manager generates the event message, whichcontains the definitions of all the Event Manager objects on the localsystem, including events, event groups, systems, agents, and subscriptions.Then the event message is sent to the specified inbound agent on the targetsystem, or to the specified workflow process that sends the event messageto the target system.

When the Synchronize Event Systems event is received on the targetsystem, it triggers the subscription to the Seed Event Group with the



External source type. Oracle Workflow loads the object definitions fromthe event message into the Event Manager on the target system, creatingnew definitions or updating existing definitions as necessary.



Automatic Replication


Automatic Replication

• When the predefined subscriptions to the SeedEvent Group are enabled, these subscriptions willreplicate any changes you make to Event Managerobject definitions on the source system.

• If you do not want to continue automaticallyreplicating changes after synchronizing systems,you can:– Disable the subscriptions– Disable the predefined events

for those changes

Automatic ReplicationWhen the relevant events and subscriptions are enabled, Oracle Workflowperforms automatic replication as follows:

• Whenever you create, update, or delete events, event group members,systems, agents, or subscriptions, Oracle Workflow raises thecorresponding predefined events.

• These events trigger the Local subscription to the Seed Event Group onthe source system, which sends the object definition data to the targetsystem.

• The External subscription to the Seed Event Group on the target systemreceives the data and adds, updates, or deletes the object definition in theEvent Manager there.



Master/Copy Systems


Master/Copy Systems

• You can choose to treat one system as a mastersystem that has one or more copy systemsassociated with it.

• A master system replicates its own Event Managerobject definitions to its copy systems, but doesnot accept any object definition changes fromthose systems.

To Set Up Master/Copy Replication:1. Synchronize the target copy systems with the source master system.2. Ensure that the Local subscription to the Seed Event Group on the copy

systems is disabled.3. Ensure that the External subscription to the Seed Event Group on the

master system is disabled.



Reviewing Event Messages on Local Agents


Reviewing Event Messages on LocalAgents

• Use the Event System Local Queues page toreview the local agents and how many messagesare on their queues.

• For queues that use the standard WF_EVENT_Tdatatype as their payload type, you can alsoreview the message details.



Reviewing Event Messages on Local Agents


Reviewing Event Messages on LocalAgents

To Review Event Messages on Local Agents:1. Use a web browser to connect to the following URL: <webagent>/wf_event_html.eventqueuedisplay Replace <webagent> with the base URL of the web agent configured for

Oracle Workflow in your Web server. You can also access the Event System Local Queues web page from the

Oracle Workflow home page, <webagent>/wfa_html.home. Note: You must have workflow administrator privileges to access the

Event Manager web pages.2. The Event System Local Queues page appears, displaying a list of the

local agents used by the Business Event System.3. You can review message details for queues that use the standard

WF_EVENT_T datatype as their payload type. To review message details,choose the flashlight icon in the View Detail column for a queue.

4. The Find Standard Event Queue Messages page appears. Enter searchcriteria to locate specific event messages. The search criteria are:

– Event Name– Event Key– Status

5. Choose the Go button. The Local Queue Messages page appears,displaying a list of event messages on the queue you selected that matchyour search criteria.



6. To review the XML document that contains the event data for a message,choose the flashlight icon in the XML Document column for that message.



Review Questions


Review Questions

1. What database init.ora parameters are required bythe Business Event System?

2. Which agents require listeners, and which agentsrequire propagations?

3. What is the definition of signing up a system?4. What is the definition of synchronizing systems

with each other?

Review Questions and Solutions1. Which database init.ora parameters are required by the Business Event

System?– AQ_TM_PROCESSES– JOB_QUEUE_INTERVAL– JOB_QUEUE_PROCESSES

2. Which agents require listeners, and which agents require propagations? Local inbound agents require listeners. Local outbound agents

require propagations.3. What is the definition of signing up a system? Signing up a system means defining the destination system and its

inbound agents in the Event Manager of the source system.4. What is the definition of synchronizing systems with each other? Synchronizing systems means replicating all the Event Manager

objects that are defined on the source system to the target system.



Practice 1 Overview


Practice 1 Overview

This practice covers the following topics:• Defining a subscription that sends an event to an

agent• Defining a subscription to handle the event when it

is received• Raising an event to trigger the subscription• Reviewing event messages on local queues



Practice 1: Sending an Event to an Agent


Practice 1:Sending an Event to an Agent

1. Define a subscription to send theXX.oracle.workflow.bes.event.new event from theWF_OUT agent to the WF_IN agent on the localsystem.

Replace ‘XX’ with your terminal number.2. Define a subscription to handle the event by

running WF_RULE.Success when the event isreceived by the inbound agent.

3. Raise the event to trigger your subscription.4. Review the event messages on the local queues.

Practice 1 SolutionIn this practice, you will define one subscription that sends an event to a localinbound agent and another subscription that handles the event by returning thestatus code SUCCESS when the event is received by that agent. Next, you willraise the event to trigger your first subscription. The second subscription will betriggered in turn when the first subscription sends the event to the agent. Finally,you will review the messages on the local inbound and outbound queues toconfirm that the sending subscription was executed successfully.Note: Because many students access the system and create objects during thiscourse, you need a way to distinguish between the objects created by you and byyour classmates. Therefore, you will be assigned a terminal number by yourinstructor. Use this number as a prefix wherever you see XX included in thename of something you are defining. In this way, you can ensure that thedefinitions you create are unique.Step 1







7. Leave the Source Agent field blank.8. Enter 20 in the Phase field.9. In the Status field, select Enabled.10. In the Rule Data field, select Key.11. Leave the Rule Function field blank to use the default rule function to

send the event to an agent.12. Leave the Workflow Item Type, Workflow Process Name, Parameters,

Owner Name, and Owner Tag fields blank. Leave the Priority field set tothe default value, which is Normal.

13. In the Out Agent field, select the agent WF_OUT@<local system>.14. In the To Agent field, select the agent WF_IN@<local system>.15. In the Description field, enter XX Send to Agent Subscription.16. Choose the Submit button to save the subscription.

Step 21. Navigate back to the Event Subscriptions page.2. Choose the Add Subscription button to open the Edit Subscription page.3. In the System field, select the local system as the subscriber.4. In the Source Type field, select External.5. In the Event Filter field, select the XX.oracle.workflow.bes.event.new

event that you defined in the Defining an Event practice. If you have notperformed this practice, select the event you defined as the event filter forthe first subscription.

6. Leave the Source Agent field blank.7. Enter 20 in the Phase field.8. In the Status field, select Enabled.9. In the Rule Data field, select Key.10. Enter WF_RULE.Success in the Rule Function field.11. Leave the Workflow Item Type, Workflow Process Name, Out Agent, To

Agent, Parameters, Owner Name, and Owner Tag fields blank. Leave thePriority field set to the default value, which is Normal.

12. In the Description field, enter XX Receive from Agent Subscription.13. Choose the Submit button to save the subscription.


whichever event you defined as the event filter for your subscription.4. In the Event Key field, enter a unique event key such as XX61.



5. In the Event Data field, enter the following sample XML document: <DATA>Test Data</DATA>6. Choose the Submit button to raise the event.7. Choose OK in the confirmation window.

Step 41. Navigate back to the Oracle Workflow home page.2. Choose the Event Queue Summary link.3. In the Event System Local Queues page, review the number of messages

on the local WF_IN and WF_OUT agents’ queues.4. Choose the flashlight icon for the WF_OUT agent.5. In the Find Standard Event Queue Messages page, select Any in the Status

field and choose Go.6. In the Local Queue Messages page, locate the message with your event

key. Choose the flashlight icon for that message to review the XMLdocument contained in the message.

7. Navigate back to the Event System Local Queues page.8. Choose the flashlight icon for the WF_IN agent.9. In the Find Standard Event Queue Messages page, select Any in the Status

field and choose Go.10. In the Local Queue Messages page, locate the message with your event

key. Choose the flashlight icon for that message to review the XMLdocument contained in the message.

Note: The amount of time it takes for the inbound message to appear onthe WF_IN queue depends on the propagation scheduled for WF_OUTand the listener scheduled for WF_IN.

When the event message is received by the WF_IN agent, the EventManager executes the External subscription you defined to that event.Because that subscription simply runs the WF_RULE.Success function toreturn the status code SUCCESS, it does not produce any visible results inthe Workflow web pages. However, it is important to define the Externalsubscription to handle the event when it is received in order to avoidhaving the Event Manager generate an unexpected event error notification.






Practice 1 SolutionWhen you complete this practice, the first subscription definition should looksimilar to this.






Practice 1 SolutionWhen you complete this practice, the second subscription definition should looksimilar to this.









Summary


Summary

In this lesson, you should have learned how to:• Check the Business Event System setup.• Schedule listeners for inbound agents.• Schedule propagation for outbound agents.• Sign up systems with each other for event

message propagation.• Synchronize Business Event System data on

different systems.• Review event messages on local agents.




Event Activities in Workflow ProcessesChapter 7 - Page 1

Event Activities in WorkflowProcessesChapter 7



Event Activities in Workflow Processes


Event Activities in Workflow Processes



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Define attributes of type Event.• Describe the possible actions for an event activity.• Send an event to a workflow process to start or

continue the process.• Define event activities.• Define event details for event activity nodes.• Use standard activities to manage information

from event messages.• Define external Java function activities.






Example: Order ProcessingThis example shows a workflow process that includes business events. Theexample comes from the Event System Demonstration workflow. This processincludes activities that receive a purchase order event to launch the workflow,send the purchase order event to a supplier, and wait to receive other eventsfrom the supplier in response to the order, such as an order acknowledgement,advanced shipment notice, and invoice.



Event Attribute Type


Event Attribute Type

• When you define workflow process components,you can assign the attribute type Event to item andactivity attributes.

• An attribute of type Event is a representation of anevent message in the standard WF_EVENT_Tstructure.



Defining an Attribute of Type Event


Defining an Attribute of Type Event

To Define an Attribute of Type Event:1. In the Oracle Workflow Builder, select the item type or activity that you

want in the navigator tree. Then choose New Attribute from the Editmenu.

2. In the Attribute property page, enter an internal name for the attribute. Theinternal name must be all uppercase without any leading or trailing spaces.

3. Enter a display name for the attribute.4. Enter a description of the attribute.5. In the Type field, select the data type Event.6. If you are defining an activity attribute, optionally specify an item attribute

of type Event as the default value.7. Choose Apply to save your changes.8. If you are defining an item type attribute, optionally select the Access tab

to set the access levels allowed to modify this attribute.



Event Activities


Event Activities

• An event activity represents a business eventwithin a workflow process.

• You can include event activities in workflowprocesses to model complex processing orrouting logic based on the content of an event.



Event Activity Actions


Event Activity Actions

An event activity can:• Receive an event from the Event Manager• Raise an event to the Event Manager• Send an event message to an agent



Receive Event Activities



• If you send an event to a workflow process from asubscription, the process must include a Receiveevent activity to accept the event.

• An event sent to a process can:– Launch a new process—The Receive event

activity must be marked as a Start activity.– Continue an existing process—The correlation

ID in the event message matchesthe event with the runningprocess.

Receive Event ActivitiesIf a Receive event activity is marked as a Start activity, it is always enabled toreceive events. Otherwise, the Receive event activity can only receive eventsafter the process transitions to that activity.






• The event filter for a Receive event activitydetermines which event the activity can receive.

• If the event filter is set to an individual event’sinternal name, the activity can receive only thespecified event.

• If the event filter is blank, the activity can receiveany event.

Receive Event ActivitiesYou can only specify an individual event as the event filter for a Receive eventactivity. The event filter cannot be an event group.






When a Receive event activity receives an event, theWorkflow Engine:• Stores the event name, event key, and event

message in the item type attributes specified forthe activity node

• Creates item type attributes to store any additionalparameters listed in the event message

• Continues the thread of execution from the eventactivity



Raise Event Activities


Raise Event Activities

• A Raise event activity:– Retrieves the event name, event key, and event

data specified for the activity node– Raises the event to the Event Manager

• When the event is raised, it triggers any eligiblesubscriptions to that event by the local system.



Send Event Activities


Send Event Activities

• A Send event activity:– Retrieves the event name, event key, event

message, Out Agent, and To Agent specifiedfor the activity node

– Sends the event message by placing it on theOut Agent’s queue, addressed to the To Agent

• When the event is received by the To Agent, ittriggers any eligible subscriptions tothat event by that agent’s system.

Send Event ActivitiesA Send event activity sends the event directly from the Out Agent to the ToAgent without raising the event to the Event Manager. No subscriptionprocessing is performed for the event on the sending system.



Defining an Event Activity


Defining an Event Activity

To Define an Event Activity:1. In the Oracle Workflow Builder, select the item type that you want in the

navigator tree. Then choose New Event from the Edit menu.2. In the Activity property page, enter an internal name for the activity. The

internal name must be all uppercase without any colons or leading ortrailing spaces.

3. Enter a display name for the activity.4. Enter a description of the activity.5. Choose an icon that identifies the activity.6. Select the Event Action for the activity.

– Receive– Raise– Send

7. If you are defining a Receive event activity, you can optionally enter anevent filter to specify the event that the activity can receive.

– To allow only a specified event for the activity, enter the full internalevent name.

– To allow any event for the activity, leave the Event Filter field blank.8. Enter an optional cost for the activity. For Raise or Send event activities,

you can use the cost to defer long running activities to a backgroundengine.



9. Choose Apply to save your changes.10. Optionally select the Details tab to display and modify additional activity

details.11. Optionally select the Access tab to set the access levels allowed to modify

this event.



Event Details


Event Details

• When you add an event activity node to a workflowprocess, define event details for the node.

• The event details that are required depend on theevent activity’s action.



Defining Event Details: Receive


Defining Event Details: Receive

To Define Event Details for a Receive Event Activity Node:1. In the Oracle Workflow Builder, display the property pages of a Receive

event activity node. Select the Event Details tab.2. Enter the following event details:

– Event Name—Optionally select an item type attribute of type textwhere you want to store the event name that the node receives.

– Event Key—Optionally select an item type attribute of type textwhere you want to store the event key that the node receives.

– Event Message—Optionally select an item type attribute of typeevent where you want to store the event message that the nodereceives.

3. Choose Apply to save your changes.



Defining Event Details: Raise


Defining Event Details: Raise

To Define Event Details for a Raise Event Activity Node:1. In the Oracle Workflow Builder, display the property pages of a Raise


– Event Name—Enter the name of the event that the node raises. Youcan either specify a constant event name or select an item typeattribute of type text that dynamically determines the event name atruntime.

– Event Key—Select the item type attribute of type text that containsthe event key for the event that the node raises.

– Event Data—Optionally select an item type attribute of type text thatcontains the event data for the event that the node raises.

Note: The event name and event key are required for a Raise eventactivity.

Note: The maximum length of the data you can enter in a text attribute is4000 bytes. If the event data exceeds 4000 bytes, you should assign aGenerate function in the event definition to generate the event data, ratherthan providing the event data through a text attribute.




Defining Event Details: Send


Defining Event Details: Send

To Define Event Details for a Send Event Activity Node:1. In the Oracle Workflow Builder, display the property pages of a Send


– Event Message—Select the item type attribute of type event thatcontains the event message that the node sends.

– Event Name—Optionally enter the name of the event that the nodesends. You can either specify a constant event name or select an itemtype attribute of type text that dynamically determines the eventname at runtime. The event name that you enter here overrides theprevious event name value in the event message.

– Event Key—Optionally select an item type attribute of type text thatcontains the event key of the event that the node sends. The eventkey that you enter here overrides the previous event key value in theevent message.

– Out Agent—Optionally enter the outbound agent from which thenode sends the event. Specify both the agent name and the systemname for the agent using the following format:

<agent_name>@<system_name> You can either specify a constant Out Agent name or select an item

type attribute of type text that dynamically determines the Out Agentname at runtime. The Out Agent that you enter here overrides theprevious outbound agent value in the event message.



– To Agent—Optionally enter the inbound agent to which the nodesends the event. Specify both the agent name and the system namefor the agent using the following format:

<agent_name>@<system_name> You can either specify a constant To Agent name or select an item

type attribute of type text that dynamically determines the To Agentname at runtime. The To Agent that you enter here overrides theprevious inbound agent value in the event message.

Note: The Event Message is required for a Send event activity.Additionally, you must either include the To Agent within the eventmessage or specify the To Agent in the event details for this node. If youdo not specify a To Agent, the event cannot be sent.




Standard Activities


Standard Activities

• Oracle Workflow provides standard activities thatlet you access information within event messages.– Event message header properties– XML tag sets within an event data XML

document• You can model routing or processing logic in your

workflow process based on the contents of eventmessages.



Standard Activities


Standard Activities

• Get Event Property• Set Event Property• Compare Event

Property

• XML Get Tag Value• XML Compare Tag

Value (Date, Number,Text)

• XML Transform

Use the following standard activities to manage thecontents of event messages:

Standard Activities• Get Event Property—Retrieves a property of an event message and stores

the property value in an item attribute.• Set Event Property—Sets the value of a property in an event message.• Compare Event Property—Compares a property of an event message with

a test value.• XML Get Tag Value—Retrieves the data contained within a particular

XML tag set in an event message and stores the data in an item attribute.• XML Compare Tag Value (Date)—Compares the data contained within a

particular XML tag set in an event message with a test date value.• XML Compare Tag Value (Number)—Compares the data contained

within a particular XML tag set in an event message with a test numbervalue.

• XML Compare Tag Value (Text)—Compares the data contained within aparticular XML tag set in an event message with a test text value.

• XML Transform—Applies an XML style sheet to the payload of an eventmessage and stores the resulting document in an item attribute.

Note: The XML Get Tag Value, XML Compare Tag Value, and XMLTransform activities are external Java function activities and require the JavaFunction Activity Agent as well as a background engine to complete theirprocessing.



For more information, refer to the Standard Activities chapter in the OracleWorkflow Guide.



External Java Function Activities



• An external Java function activity is a functionactivity that runs a Java program on the middletier.

• The standard activities for accessing XMLdocuments are defined as external Java functionactivities.

• You can also define your own external Javafunction activities.






• An external Java function activity enqueues anentry on the 'Outbound' queue.

• The Oracle Workflow Java Function Activity Agentdequeues messages of this type, executes theJava program, and enqueues the results on the'Inbound' queue.

• A background engine dequeues messages fromthe ‘Inbound’ queue and completes the functionactivity to continue the workflowprocess.

External Java Function ActivitiesBefore you can execute external Java function activities, you must perform thesetup steps to run the Java Function Activity Agent and a background engine, toprocess messages on the ‘Outbound’ and ‘Inbound’ queues, respectively.Note: The ‘Outbound’ and ‘Inbound’ queues used for external functionactivities are separate from the queues used for the Business Event System.For more information, refer to the Setting Up Oracle Workflow chapter in theOracle Workflow Guide.






• Java procedures called by external Java functionsmust follow a standard API.

• These Java procedures are implemented asclasses that extend the WFFunctionAPI class.

• You must include the JAR files containing yourcustom Java classes in your CLASSPATH.

External Java Function ActivitiesA Java procedure for an external Java function activity must have the followingstandard API:

package oracle.apps.fnd.wf;

import java.io.*;

import java.sql.*;

import java.math.BigDecimal;

import oracle.sql.*;

import oracle.jdbc.driver.*;

import oracle.apps.fnd.common.*;

import oracle.apps.fnd.wf.engine.*;

import oracle.apps.fnd.wf.*;

public class className extends WFFunctionAPI {

public boolean execute(WFContext pWCtx){

ErrorStack es = pWCtx.getWFErrorStack();

try



{

WFAttribute lAAttr = new WFAttribute();

WFAttribute lIAttr = new WFAttribute();

loadActivityAttributes(pWCtx);

loadItemAttributes(pWCtx);

lAAttr = getActivityAttr("AATTR");

lIAttr = getItemAttr("IATTR");

<your executable statements>

lIAttr.value((Object)"NEWVALUE");

setItemAttrValue(pWCtx, lIAttr);

}

catch (Exception e)

{

es.addMessage("WF","WF_FN_ERROR");

es.addToken("MODULE",this.getClass().getName());

es.addToken("ITEMTYPE",itemType);

es.addToken("ITEMKEY",itemKey);

es.addToken("ACTID",actID.toString());

es.addToken("FUNCMODE",funcMode);

es.addToken("ERRMESSAGE",e.getMessage());

return false;

}

return true;

}

}

The parameters available as class variables are:• itemType—The internal name for the item type.• itemKey—A string that represents a primary key generated by the

workflow-enabled application for the item type. The string uniquelyidentifies the item within an item type.



• ActID—The ID number of the activity from which this procedure iscalled.

• funcMode—The execution mode of the activity. Currently the onlysupported mode for external Java function activities is the 'RUN' mode.

• resultOut—If a result type is specified in the Activities properties page forthe activity in the Oracle Workflow Builder, this parameter represents theexpected result that is returned when the procedure completes.

Note: Unlike the resultout for a PL/SQL procedure called by a functionactivity, the resultOut for a Java procedure does not include a status code.In the Java API, only the result type value is required. The status of theactivity will be set automatically by the Workflow Engine depending onwhether there is a value in the errorStack variable.




Defining an External Java Function Activity


Defining an External Java FunctionActivity

To Define an External Java Function Activity:1. In the Oracle Workflow Builder, select the item type that you want in the

navigator tree. Then choose New Function from the Edit menu.2. In the Activity property page, enter an internal name for the activity. The

internal name must be all uppercase without any colons or leading ortrailing spaces.

3. Enter a display name for the activity.4. Enter a description of the activity.5. Choose an icon that identifies the activity.6. Enter the the class name of your custom Java class as the name of the

function you want this activity to execute. If the custom class is within a package, prefix the class name with the

package name in the following format: <customPackage>.<customClass> The Java class must be defined according to a standard API.7. Select External Java as the function type.8. Indicate the result type (a predefined lookup type) for this activity. Result

types list the possible results that the activity can return.9. Enter an optional cost for the activity. For Raise or Send event activities,

you can use the cost to defer long running activities to a backgroundengine.




11. Optionally select the Details tab to display and modify additional activitydetails.

12. Optionally select the Access tab to set the access levels allowed to modifythis event.



Practice 1 Overview


Practice 1 Overview

This practice covers defining an item type thatincludes an event activity.



Practice 1: Defining an Item Type with an Event Activity


Practice 1:Defining an Item Type with an Event

Activity1. Define a new item type and process using the

Quick Start Wizard.2. Define item attributes of type Text for the event

name and event key, and an item attribute of typeEvent for the event message.

3. Define an event activity with the followingproperties:– Event action: Receive– Event filter: XX.oracle.workflow.bes.event.new


Practice 1 SolutionIn this practice, you will define an item type that includes a Receive eventactivity as well as some item attributes related to the event. You will continuedefining this item type in the next practice, Defining a Workflow Process withan Event Activity Node.Note: Because many students access the system and create objects during thiscourse, you need a way to distinguish between the objects created by you and byyour classmates. Therefore, you will be assigned a terminal number by yourinstructor. Use this number as a prefix wherever you see XX included in thename of something you are defining. In this way, you can ensure that thedefinitions you create are unique.

1. Start the Oracle Workflow Builder.2. From the File menu, choose Quick Start Wizard.3. Define the following properties for the new item type:

– Internal Name: XXRECEVT– Display Name: XX Receive Event Type– Persistence Type: Temporary– Number of Days: 0

4. Define the following properties for the process:– Internal Name: XXEVENTPROCESS– Display Name: XX Receive Event Process

Choose OK.



5. Close the XX Receive Event Process diagram window. You will definethe diagram for this process in the next practice.

6. In the Navigator window, select the XX Receive Event item type.7. From the Edit menu, choose New > Attribute.8. Define the following properties for the item attribute:

– Internal Name: EVENTNAME– Display Name: Event Name– Description: Event Name– Type: Text

Choose OK.9. From the Edit menu, choose New > Attribute.10. Define the following properties for the item attribute:

– Internal Name: EVENTKEY– Display Name: Event Key– Description: Event Key– Type: Text

Choose OK.11. From the Edit menu, choose New > Attribute.12. Define the following properties for the attribute:

– Internal Name: EVENTMESSAGE– Display Name: Event Message– Description: Event Message– Type: Event

Choose OK.13. From the Edit menu, choose New > Event.14. Define the following properties for the event:

– Internal Name: XXEVENT– Display Name: XX Receive Event– Description: XX Receive Event

15. Leave the icon and cost set to the default values.16. Select Receive as the event action.17. In the Event Filter field, enter XX.oracle.workflow.bes.event.new, the

event that you defined in the Defining an Event practice. If you have notperformed this practice, enter an event provided by your instructor.

18. Choose OK.19. From the File menu, choose Save As and save your new data store and

item type to a workflow definition file named XXbes.wft.Note: Refer to the Workflow definition file XXbes.wft for a sample solution.






Activity

Practice 1 SolutionWhen you complete this practice, your Receive event activity definition shouldlook similar to this.






Activity

Practice 1 SolutionWhen you complete this practice, the navigator tree for your XXbes data storeshould look similar to this.



Practice 2 Overview


Practice 2 Overview

This practice covers the following topics:• Defining a workflow process that includes an

event activity node.• Defining event details for an event activity node.



Practice 2: Defining a Workflow Process with an EventActivity Node


Practice 2:Defining a Workflow Process with an

Event Activity NodeFor the workflow process created during the previouspractice, define a process diagram that includes thefollowing activities:• The Receive event activity defined during the

previous practice, marked as a Start activity• A standard Noop activity• A standard End activity

Practice 2 SolutionIn this practice, you will define the process diagram for the process activity thatyou created in the Defining an Item Type with an Event Activity practice.Ensure that you complete that practice before beginning this one. You willlaunch your workflow process in the next practice, Launching a WorkflowProcess from the Business Event System.

1. Start the Oracle Workflow Builder.2. From the File menu, choose Open to open the XXbes.wft data store you

defined in the previous practice.3. Expand the navigator tree and select the XX Receive Event Process in

your XX Receive Event Type item type.4. Double-click the XX Receive Event Process to display the process diagram

window.5. Delete the default Start activity from the process diagram.6. Drag the XX Receive Event activity into the process diagram.7. Double-click the XX Receive Event activity node and choose the Node tab.8. In the Start/End field, select Start.9. Choose the Event Details tab.10. In the Event Name field, select the Event Name item attribute.11. In the Event Key field, select the Event Key item attribute.



12. In the Event Message field, select the Event Message item attribute.13. Choose OK.14. Drag the standard Noop function activity from the Standard item type into

the process diagram. This Noop activity represents a point in the processwhere you could add additional processing for the event.

15. Draw a transition from the XX Receive Event activity to the Noop activity.16. Draw a transition from the Noop activity to the default End activity in the

process diagram.17. Double-click the End activity node and choose the Node tab.18. Ensure that the Start/End field is set to End.19. Choose OK.20. From the File menu, choose Save to save your work to your workflow

definition file.21. From the File menu, choose Save As and save your item type to the class

database, using the database username, password, and connect stringprovided by the instructor.

Note: Refer to the Workflow definition file XXbes.wft for a sample solution.






Event Activity Node

Practice 2 SolutionWhen you complete this practice, the event details for your Receive eventactivity node should look similar to this.






Event Activity Node

Practice 2 SolutionWhen you complete this practice, the process diagram for your XX ReceiveEvent Process should look similar to this.



Practice 3 Overview


Practice 3 Overview

This practice covers sending an event to a workflowprocess to launch a new process instance.



Practice 3: Launching a Workflow Process from theBusiness Event System


Practice 3:Launching a Workflow Process from the

Business Event System1. Define a subscription to the

XX.oracle.workflow.bes.event.new event thatsends the event to the workflow process definedduring the previous practice.

2. Raise the event to trigger the subscription. Replace ‘XX’ with your terminal number.

Practice 3 SolutionIn this practice, you will define a subscription to send an event to the workflowprocess that you defined in the Defining a Workflow Process with an EventActivity Node practice. Ensure that you complete that practice before beginningthis one. After completing this practice, you can review the process in theWorkflow Monitor to confirm that the subscription was executed and theprocess completed successfully.Step 1



open the Edit Subscription page.4. In the System field, select the local system as the subscriber.5. In the Source Type field, select Local.6. In the Event Filter field, select the XX.oracle.workflow.bes.event.new

event that you defined in the Defining an Event practice. If you have notperformed this practice, select the event that you defined as the event filterfor your Receive event activity in the Defining an Item Type with anEvent Activity practice.



7. Leave the Source Agent field blank.8. Enter 30 in the Phase field.9. In the Status field, select Enabled.10. In the Rule Data field, select Key.11. Leave the Rule Function field blank to use the default rule function to

send the event to a workflow process.12. In the Workflow Item Type and Workflow Process Name fields, select the

item type and process name that you defined in the Defining an Item Typewith an Event Activity and Defining a Workflow Process with an EventActivity Node practices.

13. Leave the Out Agent, To Agent, Parameters, Owner Name, and OwnerTag fields blank. Leave the Priority field set to the default value, which isNormal.

14. In the Description field, enter XX Workflow Receive Event Subscription.15. Choose the Submit button to save the subscription.


whichever event you defined as the event filter for your subscription.4. In the Event Key field, enter a unique event key such as XX73.5. For the purposes of this practice, since your workflow will not perform

any further processing for the event, you do not need to enter any eventdata. Leave the Event Data field blank.

6. Choose the Submit button to raise the event.7. Choose OK in the confirmation window. When you raise your event on the local system, it should trigger your new

subscription that sends the event to your workflow process. You canreview the status of the process in the Workflow Monitor by choosing theFind Processes link from the Workflow home page and searching for theprocess with your item type and with your event key as the item key.







Practice 3 SolutionWhen you complete this practice, your subscription definition should looksimilar to this.














Practice 3 SolutionWhen you complete this practice, the diagram for your process in the WorkflowMonitor should look similar to this.



Summary


Summary

In this lesson, you should have learned how to:• Define an item attribute of type Event.• Describe the possible actions for an event activity.• Send an event to a workflow process to start or

continue the process.• Define event activities.• Define event details for event activity nodes.• Use standard activities to manage information

from event messages.• Define external Java function activities.




Sample Business Event Based Workflow ProcessesChapter 8 - Page 1

Sample Business EventBased Workflow ProcessesChapter 8



Sample Business Event Based Workflow Processes


Sample Business Event BasedWorkflow Processes



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Ping agents using Workflow Agent

Ping/Acknowledge.• Send events through a workflow process using the

Workflow Send Protocol.



Workflow Agent Ping/Acknowledge



Event Manager

ListenAQ

Propagation Event Manager

WF_OUT WF_IN

ListenAQ

Propagation

WF_OUTWF_IN


WorkflowEngine

Workflow Agent Ping/AcknowledgeThe Workflow Agent Ping/Acknowledge workflow process sends a ping eventto each inbound agent on the local system or external systems. When theinbound agent receives the ping event, the Event Manager on that system sendsan acknowledgement event back to the workflow process.






• The Workflow Agent Ping/Acknowledge workflowtests the Business Event System setup.– Sends a ping event message to each inbound

agent on the local system or external systems– Waits to receive an acknowledgement event

message from each of the agents• If the workflow completes successfully, then the

basic setup for communicationwith these agents is complete.

Workflow Agent Ping/AcknowledgeThe Workflow Agent Ping/Acknowledge workflow uses the predefined PingAgent and Acknowledge Ping events, together with the predefined subscriptionsto these events, to perform the ping processing. For more information, refer tothe Managing Business Events chapter and the Predefined Workflow Eventschapter in the Oracle Workflow Guide.






• The Workflow Agent Ping/Acknowledge item typecontains two processes:– Master Ping Process– Detail Ping Process

• Use the Launch Processes web page to launch theWorkflow Agent Ping/Acknowledge workflow.– Select the Master Ping process– Enter a unique item key



Master Ping Process


Master Ping Process

Master Ping Process• The Workflow Agent Ping/Acknowledge workflow begins when you

launch the Master Ping Process using the Launch Processes web page.• The workflow begins with the Start activity.• The master process spawns a detail process for each inbound agent that

you have defined on the local system or on external systems.• Each detail process pings an agent by sending it a Ping Agent event and

waits to receive an acknowledgement in the form of an Acknowledge Pingevent.

• In the master process, a Wait for Flow activity waits for all the detailprocesses to complete.

• When all the detail processes have completed, the master process ends. For more information, refer to the Managing Business Events chapter in

the Oracle Workflow Guide.



Detail Ping Process


Detail Ping Process

Detail Ping Process• The Detail Ping process begins when it is launched by the Master Ping

process.• The process begins with the Start activity.• Next, the process sends a Ping Agent event to the selected inbound agent.• The process waits to receive an Acknowledge Ping event back from the

agent. When the acknowledgement is received, the master process cancontinue.

• The detail process ends at this point. For more information, refer to the Managing Business Events chapter in

the Oracle Workflow Guide.



Workflow Send Protocol



• The Workflow Send Protocol process is anexample of request/reply messaging.

• This sample process demonstrates using aworkflow process to receive, send, andacknowledge event messages.

• You can copy or customize this process toaccommodate your organization's specific needs.

Workflow Send ProtocolThe Workflow Send Protocol workflow uses the predefined Workflow SendProtocol and Workflow Send Protocol Acknowledgement events, together withthe predefined subscriptions to these events, to perform the send processing. Touse the Workflow Send Protocol to send an event to an agent, you must updatethe appropriate Workflow Send Protocol event subscription with the To Agentthat you want to receive the message. You can also optionally specify the OutAgent that you want to send the message.For more information, refer to the Predefined Workflow Events chapter in theOracle Workflow Guide.






The Workflow Send Protocol process:• Receives an event message from a subscription• Sends the event message to the inbound agent

specified in the subscription• Waits to receive an acknowledgement if required• Sends an acknowledgement if required






• The Workflow Send Protocol item type containsone process, the Workflow Event Protocolprocess.

• You can use this process on one system to send amessage to another system.

• You can also use the same process on the secondsystem to receive the message and send anacknowledgement back to the first system.






• The Workflow Send Protocol workflow is launchedwhen it receives an event from a subscription.

• You can start the Workflow Send Protocolworkflow by any of the following methods:– Raising the Workflow Send Protocol event

locally– Receiving the Workflow Send Protocol event

from an external source– Sending any event to the Workflow Send

Protocol process from acustom subscription

Workflow Send Protocol• You can raise the Workflow Send Protocol event from the Raise event

page. Enter a unique event key, and enter any valid XML document as theevent data. A predefined subscription sends the event message to theWorkflow Event Protocol process.

• The process can also be started when an agent receives the WorkflowSend Protocol event from an external source. A predefined subscriptionsends the event message to the Workflow Event Protocol process.

• Additionally, you can define your own subscription to send any event youchoose to the Workflow Event Protocol process. In the subscription,specify the workflow item type as WFSNDPRT and the workflow processname as WFEVPRTC. Ensure that you either use the default rule functionor include send processing in your custom rule function to send the eventto the workflow. The Workflow Event Protocol process starts when thesubscription is executed and the process receives the event message.



Workflow Event Protocol Process


Workflow Event Protocol Process

Workflow Event Protocol Process• The Workflow Send Protocol workflow begins when the Event Manager

sends an event message to the Workflow Event Protocol process.• The workflow begins with the Receive Message activity.• Next, the process attempts to retrieve the agent details for the intended

outbound and inbound agents from the subscription.• If no inbound agent is specified, the process continues immediately to the

second Compare Text node to determine whether to send anacknowledgement message.

• If the subscription does specify a To Agent, the process sends the eventmessage to that agent.

• Then the process continues to the first Compare Text node to determinewhether the event message requires an acknowledgement from therecipient, based on a subscription parameter.

• If an acknowledgement is required, the Workflow Engine waits to receivethe acknowledgement message.

• Otherwise, the process continues immediately to the second Compare Textnode to determine whether to send an acknowledgement message.

• At the second Compare Text node, the process determines whether itshould send an acknowledgement of the original message that it received.If no acknowledgement needs to be sent, the process ends at this point.



• Otherwise, the process retrieves the agent details for the inbound agentwhere the acknowledgement must be sent and sends the acknowledgementmessage to that agent. Then the process ends.

For more information, refer to the Predefined Workflow Events chapter inthe Oracle Workflow Guide.






BUYEREvent

Manager

Propagation SUPPLIEREvent

Manager

WF_OUT@BUYER

WF_IN@SUPPLIER

Propagation

WF_OUT@SUPPLIER

WF_IN@BUYER

BUYERWorkflow Engine

SUPPLIERWorkflow Engine

BuyerWorkbench

Raise

Example: Order ProcessingThis example shows how you can use events to build workflow processes thattransmit business documents between two systems. The example comes fromthe Event System Demonstration workflow process. The business flow for apurchase order is controlled by workflow processes on two different systems, aBuyer system and a Supplier system, which use events to communicate witheach other.The order processing is initiated when a purchase order is entered from a BuyerWorkbench on a Buyer system. Oracle Workflow generates a purchase orderXML document and sends this document to a Supplier system in an eventmessage. The Supplier system processes the purchase order and sends back tothe Buyer system three event messages with XML documents representing apurchase order acknowledgement, an advanced shipment notice, and an invoice.






Example: Order ProcessingThis example shows the Buyer: Top Level PO Process from the Event SystemDemonstration workflow.






Example: Order ProcessingThis example shows the Supplier: Top Level Order Process from the EventSystem Demonstration workflow.



Practice 1 Overview


Practice 1 Overview

This practice covers pinging Business Event Systemagents using Workflow Agent Ping/Acknowledge.



Practice 1: Pinging Agents


Practice 1:Pinging Agents

Launch the Workflow Agent Ping/Acknowledgeworkflow with the following properties:– Item Key: XX81– Process Name: Master Ping Process


Practice 1 SolutionIn this practice, you will launch the Workflow Agent Ping/Acknowledgeprocess to ping all inbound agents defined in the Event Manager. Aftercompleting the practice, you can review the process in the Workflow Monitor toconfirm that the appropriate acknowledgements were received and the processcompleted successfully.Note: Because many students access the system and create objects during thiscourse, you need a way to distinguish between the objects created by you and byyour classmates. Therefore, you will be assigned a terminal number by yourinstructor. Use this number as a prefix wherever you see XX included in thename of something you are defining. In this way, you can ensure that thedefinitions you create are unique.


2. Choose the Launch Processes link.3. In the Launch Processes page, choose the Workflow Agent

Ping/Acknowledge item type.4. In the Initiate Workflow page, enter XX81 in the Item Key field.5. Select Master Ping Process in the Process Name field.6. Choose OK.7. Review the process activities in the Activities List page that appears.



8. Choose View Diagram to review the status of the process in the WorkflowMonitor. If the process completes successfully, then the basic setup forcommunication with the inbound agents defined in the Event Manager iscomplete.

You can also review the Ping Agent and Acknowledge Ping eventmessages on the local queues by choosing Event Queue Summary fromthe Workflow home page.



Practice 1: Pinging Agents


Practice 1:Pinging Agents

Practice 1 SolutionWhen you launch the workflow process for this practice, the process detailsshould look similar to this.



Review Questions


Review Questions

1. How can you set up the Workflow Send Protocol tosend a local event to a remote agent?

2. How can the Workflow Send Protocol workflow bestarted?

Review Questions and Solutions1. How can you set up the Workflow Send Protocol to send a local event to a

remote agent? Enter the agent as the To Agent in the predefined Local subscription

to the Workflow Send Protocol event. You can also optionally specifythe Out Agent from which you want to send the event.

2. How can the Workflow Send Protocol process be started? You can start the Workflow Send Protocol process by any of the

following methods:– Raising the Workflow Send Protocol event locally– Receiving the Workflow Send Protocol event from an external

source– Sending any event to the Workflow Send Protocol process from

a custom subscription



Summary


Summary

In this lesson, you should have learned how to:• Ping agents using Workflow Agent

Ping/Acknowledge.• Send events through a workflow process using the

Workflow Send Protocol.




Error Handling for Subscription ProcessingChapter 9 - Page 1

Error Handling forSubscription ProcessingChapter 9



Error Handling for Subscription Processing


Error Handling for SubscriptionProcessing



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Describe the status codes returned by

subscription rule functions.• Describe the WF_ERROR agent.• Explain the Default Event Error process.



Rule Function Status Codes


Rule Function Status Codes

• A subscription rule function can return thefollowing status codes:– SUCCESS– WARNING– ERROR

• The Event Manager uses these status codes tomonitor the status of the subscriptionprocessing for an event.



Errors in Subscription Processing


Errors in Subscription Processing

• If a rule function returns a status code ofWARNING or ERROR, the Event Manager placesthe event message on the standard WF_ERRORagent’s queue.

• For a WARNING status, the Event Manager thencontinues subscription processing for the event.

• For an ERROR status, the Event Manager haltssubscription processing for the event androlls back any subscriptions alreadyexecuted for the event.

Errors in Subscription ProcessingNote: If a rule function raises an exception, the Event Manager rolls back allsubscription processing for the event and raises the error to the callingapplication. In this case the event message is not placed on the WF_ERRORqueue.



WF_ERROR Agent


WF_ERROR Agent

• WF_ERROR is a standard agent for error handlingthat is automatically defined on the local systemwhen you install Oracle Workflow.

• You must schedule a listener to monitor theWF_ERROR agent and dequeue messages from itsqueue.

• All event messages that are dequeued from theWF_ERROR queue are assigned a source type ofError.



Error Handling Subscriptions


Error Handling Subscriptions

• When an event is dequeued from the WF_ERRORqueue, it triggers any subscriptions by the localsystem to that event or to the Any event with thesource type Error.

• A predefined Error subscription to the Any eventsends the event message to the Default EventError process in the System: Error item type.

Error Handling SubscriptionsYou must not change or disable the definition of the Any event or of thepredefined Error subscription to that event. If you do, the Event Manager willnot be able to perform error handling for event and subscription processing.You can set up custom error handling for a particular event by defining asubscription to that event with a source type of Error and specifying the customprocessing you want to execute as the subscription action.



Unexpected Events


Unexpected Events

• If an event is received from an external source, butthe local system does not have any subscriptionsto that event, Oracle Workflow automaticallysearches for exceptions to the predefinedUnexpected event.

• A predefined External subscription to theUnexpected event sends the event message to theDefault Event Error process in the System: Erroritem type.

Unexpected EventsOracle Workflow also provides a predefined Local subscription to theUnexpected event that sends the event message to the Default Event Errorprocess when there are no subscriptions to a locally raised event. Thissubscription is disabled by default. To use this subscription, you must enable it.Attention: If you want to enable this subscription, be careful to consider all theevents that can be raised on your local system and trigger the subscription.Many local events may be raised to which you do not want to subscribe.Additionally, if a large number of events are raised on the local system,enabling this subscription may flood the Business Event System.



Default Event Error Process



The Default Event Error Process:• Sends an administrator a notification when an

error or warning condition occurs during eventsubscription processing

• Provides information to the administrator aboutthe error

• Allows the administrator to abort or retry the eventsubscription processing,depending on the error type



Event Warnings


Event Warnings

• For a warning condition, the Default Event ErrorProcess sends the administrator a warningmessage.

• The warning message is an FYI notification anddoes not require a response.



External Event Errors


External Event Errors

• For an error in subscription processing for anexternal event, the Default Event Error Processsends the administrator an error message thatrequests a response.

• The administrator can:– Abort subscription processing for the event– Enqueue the event message back onto the

queue where it was originallyreceived

External Event ErrorsAbortFor example, if the event data contained in an event message is corrupted, thesystem administrator can abort subscription processing on that event message.Enqueue EventThe event message is enqueued on its original queue with a priority of -1 so thatit will be the first message to be dequeued the next time the listener runs.The system administrator can attempt to correct the error beforere-enqueuing the event. For example, the system administrator can create asubscription to handle an unexpected event and then re-enqueue the eventmessage to trigger the new subscription.



Local Event Errors


Local Event Errors

• For an error in subscription processing for a localevent, the Default Event Error Process sends theadministrator an error message that requests aresponse.

• The administrator can:– Abort subscription processing for the event– Reraise the event with the event name and key– Reraise the event with the

event name, key, and data– Reraise the event with the

event name, key, data, andparameters

Local Event ErrorsThe system administrator can choose the level of information to provide to theEvent Manager when reraising the event. For example, if an error exists in theevent data that was originally provided, the event can be reraised with only theevent name and the event key, forcing the Event Manager to regenerate theevent data using the event's Generate function.The system administrator can also attempt to correct the error before reraisingthe event.






Default Event Error Process• The Default Event Error Process begins when the Event Manager sends an

errored event message to the process.• The workflow begins with the Receive Errored Queue Message activity.• Next, the process determines the error type:

– Event Warning– External Event Error– Local Event Error

• The process notifies the administrator of the error, sending differentmessages depending on the error type.

• For an Event Warning condition, the process ends after the notification issent.

• For an External Event Error, the next activity depends on theadministrator’s response.

– Abort—The process ends.– Enqueue Event—The process retries subscription processing for the

event by re-enqueuing the event on its original queue. Then theprocess ends.

• For a Local Event Error, the next activity also depends on theadministrator’s response.

– Abort—The process ends.



– Raise Event with Event Key, Raise Event with Event Key and EventData, or Raise with Event Key, Event Data, and Parameters—Theprocess retries subscription processing for the event by reraising theevent with the specified level of information. Then the process ends.



Practice 1 Overview


Practice 1 Overview

This practice covers handling an error in subscriptionprocessing.



Practice 1: Handling an Error in SubscriptionProcessing


Practice 1:Handling an Error in Subscription

Processing1. Define a subscription with the following properties:

– System: <local system>– Source Type: Local– Event Filter: XX.oracle.workflow.bes.event.new– Rule Function: WF_RULE.Error– Parameters: WFSQL_ARGS

2. Raise the XX.oracle.workflow.bes.event.new eventto trigger your subscription.

3. Review the error notification and abortsubscription processing for the event.


Practice 1 SolutionIn this practice, you will define a subscription that uses the standardWF_RULE.Error rule function to deliberately return an ERROR status code.Oracle Workflow will send the errored event to the Default Event Error Process,which will send a notification of the error. You can review the notification toconfirm that the subscription was executed and to respond to the error.Note: Because many students access the system and create objects during thiscourse, you need a way to distinguish between the objects created by you and byyour classmates. Therefore, you will be assigned a terminal number by yourinstructor. Use this number as a prefix wherever you see XX included in thename of something you are defining. In this way, you can ensure that thedefinitions you create are unique.Step 1







7. Leave the Source Agent field blank.8. Enter 40 in the Phase field.9. In the Status field, select Enabled.10. In the Rule Data field, select Key.11. Enter WF_RULE.Error in the Rule Function field. This rule function

returns the status code ERROR.12. Leave the Workflow Item Type, Workflow Process Name, Out Agent, To

Agent, Owner Name, and Owner Tag fields blank. Leave the Priority fieldset to the default value, which is Normal.

13. In the Parameters field, enter WFSQL_ARGS. This is the internal name ofthe Workflow error message “Invalid value(s) passed for arguments.”WF_RULE.Error will set this error message into the event message.

14. In the Description field, enter XX New Event Error Subscription.15. Choose the Submit button to save the subscription.


whichever event you defined as the event filter for your subscription.4. In the Event Key field, enter a unique event key such as XX91.5. For the purposes of this practice, since you will not perform further


6. Choose the Submit button to raise the event.7. Choose OK in the confirmation window.

Step 31. Navigate back to the Oracle Workflow home page.2. Choose the Worklist link.3. Choose the Local Event Error notification with your event name and event

key in the subject. Note: The amount of time it takes for the notification to appear on the

Worklist depends in part on the listener scheduled for the WF_ERRORagent.

4. Review the information in the notification. The notification should includethe error message specified in the subscription parameters.

5. In the response region, select Abort and choose Submit.Optional Step

1. Repeat Step 2 to generate a new error. Use a unique event key.



2. Review the new error notification.3. Update your subscription definition by changing the rule function to

WF_RULE.Success.4. Return to the error notification and select Raise Event with Event Key as

your response. This time, the subscription should complete successfullywithout generating an error.






Processing

Practice 1 SolutionWhen you complete this practice, the subscription definition should look similarto this.






Processing







Processing

Practice 1 SolutionWhen you review the error notification for this practice, the notification shouldlook similar to this.



Summary


Summary

In this lesson, you should have learned how to:• Describe the status codes returned by

subscription rule functions.• Describe the WF_ERROR agent.• Explain the Default Event Error process.


Setting Up the Business Event SystemChapter 10 - Page 1

Setting Up the BusinessEvent SystemChapter 10



Setting Up the Business Event System


Setting Up the Business Event System



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Describe the global preferences for the Business

Event System.• Discuss how to run the Java Function Activity

Agent.• Describe setting up database links and queues for

the Business Event System.• Discuss setting up a queue handler for integration

with Oracle Message Broker.



Business Event System Setup Steps


Business Event System Setup Steps

BackgroundEngines

Step 4

Step 1

Global User Preferences

OMBQueue Handler

Step 2

Java Function Activity Agent

Step 3

Database Linksand Queues

Business Event System Setup StepsIn addition to the other setup steps for Oracle Workflow, perform the followingsteps to set up the Business Event System.

1. Set the default Workflow preferences for your entire enterprise using theGlobal Workflow Preferences web page.

2. Start the Java Function Activity Agent if you want to run external Javafunction activities.

3. Set up database links and queues for the Business Event System.4. Set up the WF_EVENT_OMB_QH queue handler if you want to use

Oracle Message Broker to propagate event messages between systems.For more information, refer to the Setting Up Oracle Workflow chapter in theOracle Workflow Guide.



Step 1 Setting Global User Preferences


Step 1Setting Global User Preferences

Use the Global Workflow Preferences web page toset:• Local System—The system where this installation

of Oracle Workflow is located• System Status

– Enabled– Local Only– External Only– Disabled

Setting Global User PreferencesTo access the Global Workflow Preferences web page, use a web browser toconnect to the Oracle Workflow home page at the following URL:<webagent>/wfa_html.homeReplace <webagent> with the base URL of the web agent configured for OracleWorkflow in your Web server.Then choose the Global Workflow Preferences link.Note: You must have workflow administrator privileges to access the GlobalWorkflow Preferences web page.Set values for all appropriate global Workflow preferences, includingpreferences related to the Business Event System.Local SystemWhen you install Oracle Workflow, the database where the installation islocated is automatically defined as a system in the Event Manger and set as thelocal system in the Global Workflow Preferences page.System Status

• Enabled—Subscriptions are executed on all events.• Local Only—Subscriptions are executed only on events raised on the local

system.• External Only—Subscriptions are executed only on events received from

external systems.• Disabled—No subscriptions are executed on any events.



Oracle Workflow sets the system status to Local Only by default. After youfinish setting up the Business Event System, change the setting to the status youwant for event processing.



Step 2 Starting the Java Function Activity Agent


Step 2Starting the Java Function Activity Agent

• Run the Java Function Activity Agent if you wantto execute external Java function activities.

• To start the Java Function Activity Agent, you can:– Run JRE against

'oracle.apps.fnd.wf.WFFALsnr'– Edit and run sample scripts called wfjvlsnr.csh

for UNIX or wfjvlsnr.bat for Windows NT

Starting the Java Function Activity AgentYou must have Java Runtime Environment (JRE) Version 1.1.8 or higherinstalled to run the Java Function Activity Agent.Starting the Java Function Activity Agent ManuallyTo start the Java Function Activity Agent manually, run JRE against'oracle.apps.fnd.wf.WFFALsnr', specifying your CLASSPATH and the username and password of your Oracle Workflow database account. TheCLASSPATH must point to the Java Runtime Environment, the top-levelWorkflow Java directory, the Oracle XML parser, the Oracle JDBCimplementation, and the following Workflow JAR files:

• wfjava.jar—The Java Function Activity Agent• wfapi.jar—Workflow Java APIs• fndbalishare.jar—Utilities referenced by the Workflow Java APIs• fndewt.jar—Utilities referenced by the Workflow Java APIs• fndswing.jar—Optional additional utilities

If you define your own external Java function activities, you must also includethe JAR files containing your custom Java classes in the CLASSPATH.Starting the Java Function Activity Agent From a ScriptOracle Workflow also provides sample scripts called wfjvlsnr.csh andwfjvlsnr.bat which you can modify to run the Java Function Activity Agent onUNIX or on Windows NT, respectively. These scripts are located on your serverin the Oracle Workflow admin subdirectory. Before you can use these sample



scripts, you must edit them to include the actual directory paths to your OracleHome and to the JRE rt.jar file. Also, if you define your own external Javafunction activities, you must include the path to the JAR files containing yourcustom Java classes. Then you can run the scripts with the user name andpassword of your Oracle Workflow database account to submit the JavaFunction Activity Agent.Stopping the Java Function Activity AgentNormally, the Java Function Activity Agent runs as a perpetual job. However,you can stop the agent by running a script called wfjvstop.sql, located in theadmin/sql subdirectory on your Oracle Workflow server.



Step 3 Setting Up Database Links and Queues


Step 3Setting Up Database Links and Queues

• If you want to communicate business eventsbetween the local system and external systems,create database links to those external systems.

• If you want to use custom queues for propagatingevents, set up your queues.

• You can either create database links and set upqueues manually, or use Oracle DBA Studio in theOracle Enterprise Manager.

Setting Up Database Links and QueuesDatabase LinksWhen you set up database links for use by the Business Event System, youshould fully qualify each database link name with the domain name.QueuesOracle Workflow provides three standard queues that you can use for eventprocessing:

• WF_IN• WF_OUT

WF_ERRORYou must not change the setup of these queues. However, you must schedule alistener for WF_ERROR to enable error handling for the Business EventSystem. Also, if you want to use WF_IN and WF_OUT for event messagepropagation, schedule a listener for WF_IN and a propagation for WF_OUT aswell.You can also set up your own queues for event message propagation. To set upa queue, you must create the queue table, create the queue, and start the queue.Oracle Workflow provides a sample script called wfevquec.sql which you canmodify to set up your queues, as well as a sample script called wfevqued.sqlwhich you can modify to drop queues. These scripts are located on your serverin the Oracle Workflow sql subdirectory for the standalone version of Oracle



Workflow, or in the sql subdirectory under $FND_TOP for the version ofOracle Workflow embedded in Oracle Applications.If you define a queue with a payload type other than the standardWF_EVENT_T Workflow format, you must create a queue handler to translatebetween WF_EVENT_T and the format required by the queue.



Step 4 Setting Up the WF_EVENT_OMB_QH QueueHandler


Step 4Setting Up the WF_EVENT_OMB_QH

Queue Handler• If you want to use Oracle Message Broker (OMB)

to propagate event messages between systems,set up the WF_EVENT_OMB_QH queue handler.

• WF_EVENT_OMB_QH translates between thestandard Workflow event message structure,WF_EVENT_T, and the structure required by OMBqueues, OMBAQ_TEXT_MSG.

• You can assign WF_EVENT_OMB_QH to agentsthat use propagation protocols you haveimplemented through OMB.

Setting Up the WF_EVENT_OMB_QH Queue Handler1. Use OMB to create the AQ queues that you want to use for event message

propagation. The queues should be single consumer queues created inyour Oracle Workflow schema. You should create at least one inboundand one outbound queue. For example, create queues

2. Run the script wfquhndos.pls to create the PL/SQL spec for theWF_EVENT_OMB_QH package. This script is located in the wf/sqlsubdirectory in your Oracle Home.

3. Run the script wfquhndob.pls to create the PL/SQL body for theWF_EVENT_OMB_QH package. This script is located in the wf/sqlsubdirectory in your Oracle Home.



Review Questions


Review Questions

1. What does the System Status global preferencesetting control?

2. What modifications do you need to make beforeyou can run the wfjvlsnr.csh and wfjvlsnr.batscripts?

3. What steps are required to set up a queue?4. When should you set up the WF_EVENT_OMB_QH

queue handler?

Review Questions and Solutions1. What does the System Status global preference setting control? The System Status global preference controls which events can trigger

subscriptions: all events, only local events, only external events, or noevents at all.

2. What modifications do you need to make before you can run thewfjvlsnr.csh and wfjvlsnr.bat scripts?

You must edit the scripts to include the actual directory paths to yourOracle Home and to the JRE rt.jar file.

3. What steps are required to set up a queue? To set up a queue, you must create the queue table, create the queue,

and start the queue.4. When should you set up the WF_EVENT_OMB_QH queue handler? Set up WF_EVENT_OMB_QH if you want to use Oracle Message

Broker (OMB) to propagate event messages between systems.



Summary


Summary

In this lesson, you should have learned how to:• Describe the global preferences for the Business

Event System.• Discuss how to run the Java Function Activity

Agent.• Describe setting up database links and queues for

the Business Event System.• Discuss setting up a queue handler for integration

with Oracle Message Broker.




Business Event System SummaryChapter 11 - Page 1

Business Event SystemSummaryChapter 11



Business Event System Summary


Business Event System Summary



Objectives


Objectives

After completing this lesson, you should be able todo the following:• Describe the main components of the Business

Event System• Discuss how Oracle Workflow enables business

process based integration






• Event Manager– Contains a registry of events, systems, agents,

and subscriptions– Executes subscriptions when events are

raised locally or received from externalsources

• Workflow Engine event activities– Represent events within workflow

processes– Receive, raise, or send events



Subscription Processing


Subscription Processing

Subscriptions can include the following types ofprocessing:• Executing custom code on the event• Sending the event to a workflow process• Sending the event to other agents or systems



Event Communication


Event Communication

• Events can be communicated among systemsboth within and beyond the enterprise.

• Communication among systems is accomplishedby sending an event message from one agent toanother.

• The Business Event System leverages OracleAdvanced Queuing to propagate messages by theSQLNET protocol.

• You can also implement an external service topropagate messages by a different protocol.






Event based workflows:• Allow modeling of cross-system business

processes• Express policies for end-to-end processes• Control and route objects between applications

powerfully and flexibly



Review Question 1


Review Question 1

What does the Generate function for an event do?A. Raises the event with the event keyB. Defines the event with the internal nameC. Generates the event key for the eventD. Generates the complete event data from the event

keyE. Generates the error message for the event



Answer to Review Question 1



What does the Generate function for an event do?A. Raises the event with the event keyB. Defines the event with the internal nameC. Generates the event key for the eventD. Generates the complete event data from the event

keyE. Generates the error message for the event



Review Question 2


Review Question 2

What is the name of the abstract datatype used tostore event messages?A. EVENT_MESSAGEB. WF_EVENT_MESSAGEC. WF_EVENT_TD. WF_EVENT_MESSAGE_TE. EVENT_T






What is the name of the abstract datatype used tostore event messages?A. EVENT_MESSAGEB. WF_EVENT_MESSAGEC. WF_EVENT_TD. WF_EVENT_MESSAGE_TE. EVENT_T



Review Question 3


Review Question 3

What does a queue handler do?A. Translates between the standard Workflow format

and the format required by the queueB. Propagates messages from one queue to anotherC. Moves errored messages onto the error queueD. Handles expired messages on the queueE. Purges the queue






What does a queue handler do?A. Translates between the standard Workflow format

and the format required by the queueB. Propagates messages from one queue to anotherC. Moves errored messages onto the error queueD. Handles expired messages on the queueE. Purges the queue



Review Question 4


Review Question 4

Which events have a source type of External?A. Any events dequeued from the WF_ERROR agent’s

queueB. Any events raised by applications other than

Oracle WorkflowC. Any events received from a remote systemD. Any events received from a system outside the

enterpriseE. Any events received by an inbound agent on the

local system, whether the sending agent is locatedon a remote system or the local system






Which events have a source type of External?A. Any events dequeued from the WF_ERROR agent’s

queueB. Any events raised by applications other than Oracle

WorkflowC. Any events received from a remote systemD. Any events received from a system outside the

enterpriseE. Any events received by an inbound agent on the

local system, whether the sending agent is locatedon a remote system or the local system



Review Question 5


Review Question 5

What does Oracle Workflow do if you do not specify arule function for a subscription?A. Performs no processing for the eventB. Executes the default rule functionC. Raises the Unexpected eventD. Raises an exceptionE. Places the event on the WF_ERROR queue






What does Oracle Workflow do if you do not specify arule function for a subscription?A. Performs no processing for the eventB. Executes the default rule functionC. Raises the Unexpected eventD. Raises an exceptionE. Places the event on the WF_ERROR queue



Review Question 6


Review Question 6

For which agents do you need to schedule listeners?A. All local agentsB. All outbound agentsC. All inbound agentsD. Local outbound agentsE. Local inbound agents






For which agents do you need to schedule listeners?A. All local agentsB. All outbound agentsC. All inbound agentsD. Local outbound agentsE. Local inbound agents



Review Question 7


Review Question 7

How do you specify that an event can be sent to aReceive event activity to launch a new workflowprocess?A. Mark the Receive event activity as a Start activityB. Place a standard Start activity after the Receive

event activityC. Define the event details for the Receive event

activity nodeD. Leave the event filter blank for the Receive event

activityE. Define an item attribute to store the event message






How do you specify that an event can be sent to aReceive event activity to launch a new workflowprocess?A. Mark the Receive event activity as a Start activityB. Place a standard Start activity after the Receive event

activityC. Define the event details for the Receive event activity

nodeD. Leave the event filter blank for the Receive event

activityE. Define an item attribute to store the event message



Review Question 8


Review Question 8

Which Oracle Workflow component executes externalJava programs?A. Workflow EngineB. Workflow BuilderC. Background EngineD. Java Function Activity AgentE. Event Manager






Which Oracle Workflow component executes externalJava programs?A. Workflow EngineB. Workflow BuilderC. Background EngineD. Java Function Activity AgentE. Event Manager



Review Question 9


Review Question 9

What does the predefined Error subscription to theAny event do?A. Returns the status code ERRORB. Raises an exception to the calling applicationC. Sends the event to the Default Event Error processD. Places the event on the WF_ERROR queueE. Sends the event back to the originating system






What does the predefined Error subscription to theAny event do?A. Returns the status code ERRORB. Raises an exception to the calling applicationC. Sends the event to the Default Event Error processD. Places the event on the WF_ERROR queueE. Sends the event back to the originating system



Review Question 10


Review Question 10

What is the default system status setting in theGlobal Workflow Preferences page when you installOracle Workflow?A. EnabledB. Local OnlyC. External OnlyD. DisabledE. Active






What is the default system status setting in theGlobal Workflow Preferences page when you installOracle Workflow?A. EnabledB. Local OnlyC. External OnlyD. DisabledE. Active



Summary


Summary

In this lesson, you should have learned how to:• Describe the main components of the Business

Event System• Discuss how Oracle Workflow enables business

process based integration

Documents

Workflow Developer Guide