1
Publishing Engine

This chapter provides an introduction to the Oracle Application Server InterConnect Adapter Publishing Engine. The following topics are discussed:

• What is the Publishing Engine?

• Key Management

• Using the Publishing Engine with Oracle Application Server InterConnect

What is the Publishing Engine?

The Publishing Engine provides an event publication mechanism for systems that have no native publication mechanism (for example, PeopleSoft). The Publishing Engine tracks changes to the applications by periodically polling for changes to data from operator input. It essentially polls the application looking for predefined variables.

The Publishing Engine consists of three major components:

• Publishing Engine Adapter--Provides persistent storage of event definitions and the event browsing and selection capabilities.

• Publishing Agent--Responsible for the runtime polling and event publishing. It is started as part of the Oracle Application Server InterConnect application startup.

• Publishing Manager (pubmgr)--A command line tool used to administer and configure the Publishing Engine. The Publishing Manager can configure the Publishing Engine to poll for (and publish) any information retrieved from a system.

  The events defined through the Publishing Manager appears in the component browser. You can browse and define published events in iStudio.

Supported Platforms

Table 1-1 lists the platforms on which the Publishing Engine runs.

Table 1-1 Supported Platforms

Operating System	Version
Windows NT	Version 4.0 with Service Pack 6 or above
Windows 2000	With Service Pack 1 or above
HP-UX	11.0 and 11.11
Sun SPARC Solaris	8 and 9

Key Management

To convert inbound polling calls into outbound published events, the Publishing Engine must be able to retrieve unpublished data. This is done by tracking (in persistent storage) the key fields of previously retrieved data. When the polling interval begins, the agent retrieves all data added/ changed/ deleted after the last stored key fields. After retrieving new data, the Publishing Engine publishes the data as an event and updates the stored key field. However, if no new data is retrieved, no event is generated. This cycle begins again during the next polling interval.

This process of storing and tracking key field values to retrieve only the data changed since the last polling interval is called Key Management. There are two main forms of key management recognized by the Publishing Engine:

• Internal Key Management

• External Key Management

Internal Key Management

Internal key management is where functionality, within the system itself, tracks the changes. With internal key management, the Publishing Engine does not need to store or manage keys itself. Instead, a business API is provided in the system that provides the user with all the new records since the last time this API was called. When the Publishing Engine polls this API, it may or may not retrieve records in the output set. If it retrieves records, it publishes them as a single event. Otherwise, it waits for the next polling interval.

To use internal key management with the Publishing Engine, the business API must either have no input parameters or one fixed- value input parameter. All other parameters must be output parameters (or input/output parameters for which the input can be empty). A fixed value input parameter is provided if the API supports multiple different callers. Each caller has a different value and the API stores caller-specific data previously retrieved.

The following is an example of an API that the Publishing Engine can support for internal key management:

void GetUpdatedVendors (in String callerName,
                        out VendorList updatedVendors);

There is one disadvantage to use internal key management: unless the system being called supports transactional calls, the Publishing Engine can only guarantee zero- or one-time publishing of events (it cannot guarantee exactly-one time publishing of events). The API call may succeed in the system itself (and the API updates and commits its internal key storage) but if, as the data is being transmitted back to the Publishing Engine, a network (or other) failure occurs, then the Publishing Engine will not receive the data and, therefore, cannot publish it. In order to provide exactly-one time event publishing external key management must be used.

External Key Management

External key management is similar to internal key management except that the Publishing Engine manages the persistent storage of the published key values. With external key management, the business APIs used by the Publishing Engine essentially retrieves all records whose key is greater than a given input key value. The Publishing Engine stores these key values, therefore, it can provide exactly one time event publishing in concert with the event queuing mechanism.

To use external key management with the Publishing Engine, the business API must have one input parameter used to pass in the last known key value. This parameter can also be an input/output (the output is ignored unless the output value is the updated, most recent key value). All other parameters must be output parameters (or input/output parameters for which the input can be empty).

In addition, the API provides two ways to retrieve the most recent key value:

• There must be an output parameter which is the most recent key value.

• There is a table output parameter, which contains a field for the key value where the table is sorted so that the last row in the table is the most recent key value.

The following is an example of an API that the Event Editor can support for external key management:

   void GetVendors (in String lastKnownKey,
                          out String mostrecentKey
                          out VendorList vendorsInAnyOrder);

In these cases, the Publishing Engine persistently stores and tracks the last known key value and passes the most recent value into the API each time the API is called. The Publishing Engine stores the key values (as well as the event definitions) on a per-profile basis.

Using the Publishing Engine with Oracle Application Server InterConnect

To use publishing engine with Oracle Application Server InterConnect, you need to:

• Define polled events by running the pubmgr tool.

• Define publish events for the Oracle Application Server InterConnect application in iStudio.

• Run the Oracle Application Server InterConnect application. This loads the Publishing Agent.

• If the events are configured to be manually triggered, you must launch the pubmgr and trigger the event. However, if the events are not manually triggered, the events will be triggered as soon as you start the application.

The Publishing Agent polls the system for the changes in data and reports the changes back to the Oracle Application Server InterConnect application.

Defining Polled Events using Publishing Manager

An event must be defined in the Publishing Manager to indicate its purpose. Use the following steps to define an event:

1. Change to the Installation directory\bin directory.

2. Type pubmgr iStudio and press Enter.

   Figure 1-1 Creating an Event Definition using PUBMGR

   

   Text description of the illustration PubMgr.gif

3. Type add to add a new event definition. For example:

   add Vendors Deleted
   
   

   This creates a Vendors category if it does not already exist and adds the Deleted event definition to that category.

   Note:: Type help to get the list of commands and their syntax.

4. Enter the polled API. This is the business API that is polled periodically by the Publishing Engine. For example:

   Execute@PeopleSoft://Queries/DELD_VENDORS
   
   

   To find which URL to use, please refer to the iStudio section of your Adapter document. Follow the step up to the point where the Define Application View is populated. In the field for Object Name at the top of the screen, the URL will be displayed.

5. Enter the remaining parameters at the correct prompts.

   See Also: "Publishing Manager Commands"

Defining a Published Event in iStudio

After you have defined the polled events for Publishing Engine, create the corresponding published events using iStudio.

Figure 1-2 Browsing Polled Events in iStudio

Text description of the illustration deleted.gif

See Also: Oracle Application Server InterConnect User's Guide

Runtime Polling and Event Publishing using Publishing Engine

The publishing agent is responsible for the runtime polling and event publishing. It is started as part of the Oracle Application Server InterConnect application startup. Use the following steps to start this application:

1. Run the Oracle Application Server InterConnect application to load the Publishing Agent.

2. If the events are configured to be manually triggered, you must launch the pubmgr and trigger the event. However, if the events are not manually triggered, the events will be triggered as soon as you start the application.

The Publishing Agent polls the system for the changes in data and reports the changes back to the Oracle Application Server InterConnect application.

Use the following steps to use the Publishing Engine on a Unix machine:

1. Export the event definition by using the command export filename in the pubmgr on Windows.

2. Import the file by typing import filename in the pubmgr.

All commands for running pubmgr and defining events is the same on Unix as it is on Windows.

Publishing Manager Commands

Use the Publishing Manager to configure and monitor the Publishing Engine. Use the Publishing Manager to publish an event or message to monitor. The information set in the Publishing Manager is stored in the config\pub.db file created on activation of the Publishing Manager.

From and command line:

pubmgr [{-p | -r} <script>] [<profile>]

where:

• -r--Records a script containing each of the commands performed interactively during the execution of this session of the publishing manager.

• -p--Plays back a previously recorded script.

Each event, defined with the Publishing Manager, is given a category for organizational purposes. Examples of possible categories are Customers, Vendors, or PurchaseOrders. When using the Publishing Manager, the category must always be specified along with the event name.

Table 1-2 describes each of the commands available within the Publishing Manager.

Table 1-2 Description of available commands  

Command	Sytax	Example	Description
List	list	Category Event Interval Vendor Created 1 minute Customers All Manual	Lists all defined events grouped by category. For each event the polling interval is also given.
Show	show <category> <event>	show Vendors Created Polled API: Execute@PeopleSoft://Queries/VENDORS Input key argument: Vendor_ID Output key argument: Result Output key field: VENDOR_ID Update interval: 1 minute Time of last check: Fri Sep 01 15:19:28 2000 Most recent key value: 0000000044	Shows the details of a particular event. For more information on the arguments in this example refer to the description of the Add command.
Add	add <category> <event>	add Vendors Deleted Polled API (method@impl): Execute@PeopleSoft://Queries/DELD_VENDORS Input key argument: TimeStamp Output key argument: Result Output key field: TIME_STAMP Most recent key value: 0000000012 Manually triggered (yes/no) [no]: Interval (minutes) [5]:	Allows you to add a new event definition. The polled API is the business API that is polled periodically by the Publishing Engine. The input key argument, for internal key management, is the name of the argument that has a fixed value provided. This can be blank (input with a single period, ".") if there is no input value. For external key management this is the name of the argument used to pass in the stored key value. For external key management, if the output key is a standalone argument value, then the output key argument is the name of this argument and the output key field should be left blank (input with a single period, "."). If the output key is determined by examining a table, the output key argument is the name of the table argument and the output key field is the name of the key field within the table. The most recent key value, for internal key management, actually represents the fixed key value that is passed in to the input key argument each time the API is polled. For external key management this is the key value of the most recently synchronized data (data will be retrieved with key values after this entry). Polling of the business API can be either manually triggered (through the Trigger command) or automatically performed at a set interval (in minutes). The minimum polling interval is 1 minute. When entering values, press Enter to select the default value (shown between square brackets). However, unless an event has been set up to be triggered manually, it will be triggered at the interval entered in this field.
Change	change <category> <event>	change Vendors Created Implementation:[Execute@ PeopleSoft://Queries/VENDORS]: Input key argument [Vendor_ID]: Output key argument [Result]: Output key field [VENDOR_ID]: Most recent key value [0000000044]: 0000000020 Manually triggered (yes/no) [no]: Interval (minutes) [1]:	Allows you to change existing event definitions. This can be used to update any of the fields (including the most recent key value if publishing of information needs to be repeated for any reason). The syntax of this command is identical to Add except that default values are provided for each field. Press Enter to select the default value. In order to enter a blank value instead of the default input a single period (".") followed by Enter.
Trigger	trigger <category> <event>	trigger Customers All	Allows you to trigger an event for polling. After trigger is used, the event is scheduled for polling within the next minute. You can use trigger to manually poll event (otherwise they will never be polled). Alternately, you can use trigger on interval polled events so that the polling occurs faster than it might otherwise. This is only useful on interval polled events if the polling interval is greater than 1 minute.
Remove	remove <category> <event>	remove Customers All	Removes the specified event definition and stored key information. There is no undo for the remove operation, so it is recommended to either export or show the definition before removing.
Export	export <filename>	export c:\Temp\events.xml	All values in the export format directly correspond to the values entered through Add.
Import	import <filename>	import c:\Temp\events.xml	Imports previously exported events definitions. If the events in the file do not already exist, they are created. If any of the events specified in the import file already exists, it is overwritten with the information found in the import file. This is typically used to load deployed event definitions.
Replace	replace <filename>	replace c:\Temp\events.xml	Similar to Import, it removes all existing event definitions and then imports the event definitions found in the file. Replace restores the Publishing Engine database to a previous state.
Help	help	help	Provides specific help using the following list of the possible commands.
quit	quit	quit C:\Oracle\ora81\oai\bin>	Quits the publishing manager. All changes are applied persistently as commands occur. Quit exits the manager. It does not affect the persistent store of the Publishing Engine. The Publishing Manager can be left running with commands applied periodically. However, if recording a script for later playback, the script is only written after a Quit command.