Integrating Oracle XML Gateway with Oracle Workflow Business Event System

This chapter covers the following topics:

Integrating Oracle XML Gateway with Oracle Workflow Business Event System

Overview

Oracle Workflow is a process management tool used to seamlessly integrate Oracle E-Business Suite business processes together. Introduced with Oracle Workflow 2.6 is the Business Event System to further support business process integration at the business event level.

Integral to the Business Event System is the ability to raise a business event to signal that something of interest has occurred in the Oracle E-Business Suite. Using Oracle Purchasing as an example, an event of interest would be the creation, change, confirmation, or deletion of a purchase order.

Complementary to the raise event is an event subscription defined to perform some activity when it detects an event of interest has occurred. An example of an event subscription in our Oracle Purchasing scenario is to send a message to the appropriate supplier when a new order is created, or when an existing order is changed, confirmed, or deleted.

An event subscription is controlled by a rule function. The result of the rule function determines whether the associated Workflow process will be executed. The actual activity performed by the event subscription is based on the Workflow process defined for it.

In the context of the integration between the Oracle Workflow Business Event System and Oracle XML Gateway, business events and their corresponding event subscriptions are seeded and deployed to the Oracle E-Business Suite. Once the Trading Partner is defined, the seeded business events and event subscriptions may be implemented as is, or they may be configured to perform specific activities relevant to the business requirements.

Application business events for outbound messages are raised by the Oracle E-Business Suite application module responsible for the message and processed by the event subscription defined for it. The seeded event subscription for the B2B integration may be based on the XML Gateway Rule Function or the Workflow Default Rule Function.

Embedded in the XML Gateway Rule Function is the Transaction Delivery Required Function used to determine if the Trading Partner is enabled for the transaction. The XML Gateway Rule Function can therefore be simply represented as follows:

XML Gateway Rule Function Process Flow Diagram

the picture is described in the document text

The Receive Event is followed by the Send Document function activity which proceeds to End.

The Workflow Default Rule Function uses the Transaction Delivery Required function as a process activity to determine if the Trading Partner is enabled for the transaction. This process consists of the following steps: The Receive Event is followed by the Transaction Delivery Required function activity. If it returns TRUE, the Send Document function activity is executed. If FALSE, the process proceeds to End. This process is shown below:

Workflow Default Rule Function Process Flow Diagram

the picture is described in the document text

With either rule function, no message is sent if the Trading Partner is not enabled for the transaction.

For efficiency, the XML Gateway Rule Function is the recommended approach as it has already predetermined that the Trading Partner is enabled for the transaction before it proceeds with generating the message. However, the Workflow Default Rule function approach provides a visual audit trail of the Workflow process.

With either approach, Oracle XML Gateway gathers the data from the Oracle E-Business Suite, creates the XML message, and delivers it to the Trading Partner for Business to Business (B2B) integration or to another application module for Application to Application (A2A) integration.

Inbound messages received from the Trading Partner for Business to Business (B2B) integration are enqueued onto the inbound queue. Inbound messages received from another application module for Application to Application (A2A) integration are stored in the Event Message attribute (of the Consume XML Document function) to be accessed by the XML Gateway execution engine for processing.

An XML Gateway inbound rule function is executed in the B2B integration to validate the Trading Partner and to identify the transaction queue. If the Trading Partner is valid, the message is enqueued onto the transaction queue for processing by the XML Gateway execution engine.

The XML Gateway execution engine processes the data according to the instructions in the message map associated with the Trading Partner and message. If successful, the message map sets the Event Details to inform the Oracle E-Business Suite of the Event. It is the application of the map to the message that enables you to determine what the Event Details are. The event is then processed by an application event subscription interested in the inbound message.

Oracle Workflow Business Event System consists of three key components that are used to integrate with the Oracle E-Business Suite to create and consume XML messages:

Oracle Workflow Builder - Item Types

Delivered with XML Gateway are two standard item types:

An Item Type is a group of components of a particular category that share the same set of item attributes (also known as variables).

Both the XML Gateway Standard Item Type and XML Gateway Error Processing Item Type can be accessed using the Oracle Workflow Builder.

Components of an Item Type

Common to all item types are the following components:

A Workflow process may be made up of event activities, function activities, notification activities, or process activities. A message is the information sent in a notification activity. Lookup types represent a list of valid values. Attributes represent variables used to share data between activities in the Workflow process.

See the Oracle Workflow User's Guide for more information.

XML Gateway Standard Item Type

The XML Gateway Standard Item Type is a toolkit consisting of attributes, processes, functions, and event activities. Configure the seeded events and event subscriptions delivered by the Oracle E-Business Suite for prebuilt XML messages in support of B2B integration requirements.

In addition, the function activities can be used to define Workflow processes in support of A2A integration requirements.

Oracle Workflow Builder Window

the picture is described in the document text

See XML Gateway Standard Item Type for details regarding the function and event activities.

XML Gateway Error Processing Item Type

The XML Gateway Error Processing Item Type contains error handling processes to manage errors detected by Oracle Workflow Business Event System or Oracle XML Gateway.

Oracle Workflow sends a notification to the Trading Partner contact for data errors or to the XML Gateway system administrator for system or process errors. For errors that require collaboration between the Trading Partner contact and the XML Gateway system administrator, a notification is sent to both parties to encourage discussion and to expedite problem solution.

In addition, Oracle Workflow sends a notification to an appropriate transaction owner depending on the transaction type of an erred inbound transaction. If a transaction owner for a particular transaction type is identified, and the transaction error belongs to the transaction type with the owner defined, then the transaction owner will receive a notification in addition to the XML Gateway system administrator and Trading Partner contact depending on the error type. For example, if an inbound transaction error belongs to the Purchasing transaction type, then the Purchasing transaction owner also receives the notification if his or her user name is defined in the Define Transactions form.

A transaction owner can act on an error notification if needed. Once the notification has been responded on either reprocess or abort, any other subsequent response from the system administrator will be ignored and the notification should be closed.

Oracle Workflow Builder Window with XML Gateway Error Processing Highlighted

the picture is described in the document text

For more information on the error handling process, see XML Gateway Error Processing Item Type.

E-Business Suite Application Module-Specific Item Type

The seeded event subscription delivered for Oracle prebuilt messages is delivered in an Oracle E-Business Suite application module-specific item type. The seeded event subscription may be configured using the function activities defined in the XML Gateway Standard Item Type or customized to support the application-specific requirement.

See Configure Oracle Prebuilt Inbound Messages or Configure Oracle Prebuilt Outbound Messages for details on how to configure a seeded event subscription.

XML Gateway Standard Item Type

The XML Gateway Standard Item Type is a toolkit consisting of attributes, processes, functions, and event activities. These are provided to implementers to build Workflow processes to configure the seeded event subscriptions delivered by the Oracle E-Business Suite for prebuilt XML messages in support of B2B integration requirements.

In addition, the function activities can be used to define Workflow processes in support of A2A integration requirements.

The Notifications and Messages are contained in the Oracle E-Business Suite application module-specific item type and are defined using the XML Gateway Error Processing Item Type.

See XML Gateway Error Processing Item Type.

Attributes

Attributes, also known as variables, are used to support the function, event, notification, and process activities defined for the XML Gateway Standard Item Type.

Processes

The XML Gateway Standard Item Type supports the following process:

The Create Trading Partner Message is a rule function available from the Workflow Event Subscription page.

Functions

Oracle Workflow Builder Window with Functions Node Expanded

the picture is described in the document text

The XML Gateway Standard Item Type includes five function activities as shown in the following table:

Function Display Name A2A/B2B Inbound / Outbound Purpose
Consume XML Document A2A Inbound Trigger XML Gateway to process inbound message on the Event Message attribute.
Generate XML Document A2A Outbound Create XML message and store in Event Message attribute. Trading Partner verification is not required.
Generate Trading Partner XML Document B2B Outbound Verify transaction is enabled for the Trading Partner, create XML message, and store in Event Message attribute.
Send Document B2B Outbound Create and enqueue XML message onto outbound queue.
Transaction Delivery Required B2B Outbound Verify transaction is enabled for the Trading Partner.
Transform XML A2A/B2B Inbound/Outbound Enable XML to XML transformations

Application-to-Application (A2A) exchange of data is conducted within and outside your enterprise to share or synchronize data between information systems. There is no Trading Partner involved in an A2A integration. An example of an A2A exchange is to move data from the Oracle Payables module to Oracle General Ledger for GL consolidation.

Business-to-Business (B2B) exchange of data is conducted with a Trading Partner outside of your enterprise for which Trading Partner validation is required. Data will not be sent to or received from an invalid Trading Partner. An example of a B2B exchange is to send a purchase order to a supplier.

There is not a controlling Workflow process for inbound B2B exchanges. The XML Gateway execution engine subscribes directly to the inbound queue.

Functions will be referred to by their function display names. The internal function names are provided for reference in the following table:

Function Display Name Internal Name
Consume XML Document PROCESSXML
Generate XML Document GETXML
Generate Trading Partner XML Document GETTPXML
Send Document DOCUMENT_SEND
Transaction Delivery Required DELIVREQUIRED
Transform XML XMLTOXML

The following is a description of each function supported by the XML Gateway Standard Item Type.

Consume XML Document (applies to A2A for inbound messages)

The Consume XML Document function triggers the XML Gateway Execution Engine to process the inbound message in the Event Message attribute. The XML Gateway execution engine will process the message according to the message map associated with the message, and will conclude by raising a business event to indicate that it has successfully processed the inbound message.

See Procedure Call: Execute Procedure for details regarding the Procedure Call action to raise a business event.

The Consume XML Document function is for inbound messages in the A2A scenario only. The XML Gateway execution engine is automatically triggered in a B2B scenario when an inbound message arrives on the inbound queue.

Oracle Workflow Builder Window with Consume XML Document Function Displayed

the picture is described in the document text

The attributes for the Consume XML Document function are shown in the following table. The values for the attributes are provided by the business event, another function activity, or are set as constants.

Attribute Name Attribute Description
Map Code This is the Map Code defined in the Message Designer and associated to the Trading Partner that uniquely identifies the message map associated with the business document enabled for the Trading Partner.
Event Message Event Message contains the event data as well as header properties for the event name, event key, and error data. The Event Message attribute is required to store the inbound message for processing by the XML Gateway execution engine.

Generate XML Document (applies to A2A for outbound messages)

The Generate XML Document function is used to retrieve data from the Oracle E-Business Suite. The data for the XML message retrieved from the Oracle E-Business Suite is stored in the Event Message attribute. The Event Message is then processed according to the subsequent Workflow instruction, which may be to send it to another Oracle E-Business Suite application module or to the WF_OUT agent.

The difference between the Generate XML Document function and the Generate Trading Partner XML Document function is that this function does not require Trading Partner validation since there is no Trading Partner involved in A2A integration.

The Generate XML Document function activity is provided for use in Workflow processes. For environments where a Workflow process does not exist, the ECX_STANDARD.generate function can be called from the Workflow Define Event window, Generate Function field. The details of the function are as follows:

ECX_STANDARD

PL/SQL Syntax

function generate

(p_event_name in varchar2,
 p_event_key in varchar2
 p_parameter_list in wf_parameter_list_t)
 return CLOB;

Description

Arguments (input)

Variable Description
p_event_name Unique identifier for the business event associated with the transaction.
p_event_key Unique identifier for the business document from the Oracle E-Business Suite associated with the business event.
p_parameter_list Parameter list containing the document selection criteria.

Oracle Workflow Builder Window with Generate XML Document Function Highlighted

the picture is described in the document text

The attributes for the Generate XML Document function are shown in the following table. The values for the attributes are provided by the business event, another function activity, or are set as constants.

Attribute Name Attribute Description
Document ID This is the unique identifier for the business document. It can be the document number or its associated database key, whichever is guaranteed to be unique for the transaction. The Document ID is optional for the Generate XML Document function unless it is used in the message map as a selection criterion.
Map Code This is the Map Code defined in the Message Designer and associated to the Trading Partner that uniquely identifies the message map associated with the business document enabled for the Trading Partner. The Map Code is required for the Generate XML Document function.
Event Name This is a unique identifier for the business event. The naming convention is oracle.apps.<product code>.<component>.<object>.<event> The Event Name is required for the Generate XML Document function to store the value returned.
Event Key This is a unique identifier for an instance of an event. The combination of event name, event key, and event data fully describe what occurred in the event. The Event Key is required for the Generate XML Document function activity to store the value returned.
Parameter 1 Optional variable. This attribute is used if it is used in the message map.
Parameter 2 Optional variable. This attribute is used if it is used in the message map.
Parameter 3 Optional variable. This attribute is used if it is used in the message map.
Parameter 4 Optional variable. This attribute is used if it is used in the message map.
Parameter 5 Optional variable. This attribute is used if it is used in the message map.
Event Message Event Message contains the event data as well as header properties for the event name, event key, and error data. The Event Message is required for the Generate XML Document function to store the value returned.

Generate Trading Partner XML Document (applies to B2B for outbound messages)

The Generate Trading Partner XML Document function is used to retrieve data from the Oracle E-Business Suite. The data for the XML message retrieved from the Oracle E-Business Suite is stored in the Event Message attribute. The Event Message is then processed according to the subsequent Workflow instruction, which may be to send it to another Oracle E-Business Suite application module or to the WF_OUT agent.

The difference between the Generate Trading Partner XML Document function and the Generate XML Document function is that this function is used in B2B integration for which a valid Trading Partner is required.

Oracle Workflow Builder Window with Generate Trading Partner XML Document Function Displayed

the picture is described in the document text

The attributes for the Generate Trading Partner XML Document function are shown in the following table. The values for the attributes are provided by the business event, another function activity, or are set as constants.

Attribute Name Attribute Description
Transaction Type This is the Transaction Type defined in the XML Gateway Define Transactions form. The Transaction Type is optional for the Generate Trading Partner XML Document function because it can be derived from the Map Code.
Transaction Subtype This is the Transaction Subtype defined in the XML Gateway Define Transactions form. The Transaction Subtype is optional for the Generate Trading Partner XML Document function because it can be derived from the Map Code.
Document ID This is the unique identifier for the business document. It can be the document number or its associated database key, whichever is guaranteed to be unique for the transaction. The Document ID is optional for the Generate XML Document function unless it is used in the message map as a selection criterion.
Party Site ID This is the unique identifier for the Trading Partner site defined in Oracle E-Business Suite. The Party Site ID is required for the Generate Trading Partner XML Document function.
Party ID This is the unique identifier for the Trading Partner defined in Oracle E-Business Suite. This field is optional.
Event Name This is a unique identifier for the business event. The naming convention is oracle.apps.<product code>.<component>.<object>.<event> The Event Name is required for the Generate Trading Partner XML Document function to store the value returned.
Event Key This is a unique identifier for an instance of an event. The combination of event name, event key, and event data fully describe what occurred in the event. The Event Key is required for the Generate Trading Partner XML Document function to store the value returned.
Parameter 1 Optional variable. This attribute is used if it is used in the message map.
Parameter 2 Optional variable. This attribute is used if it is used in the message map.
Parameter 3 Optional variable. This attribute is used if it is used in the message map.
Parameter 4 Optional variable. This attribute is used if it is used in the message map.
Parameter 5 Optional variable. This attribute is used if it is used in the message map.
Event Message Event Message contains the event data as well as header properties for the event name, event key, and error data. The Event Message is required for the Generate Trading Partner XML Document function to store the value returned.
Party Type The Party Type defined in the XML Gateway Trading Partner Setup window.

Send Document (applies to B2B for outbound messages)

The Send Document function is used to trigger outbound message creation. The XML message may be created immediately or deferred depending on the setting of the Send Mode attribute. This function triggers XML Gateway to gather the data from the Oracle E-Business Suite, and to create and enqueue the XML message.

A Send Mode of "Deferred" defers the processing to the Workflow background engine.

A Send Mode of "Immediate" triggers the XML Gateway Execution Engine to create the XML message immediately after the data has been entered into the Oracle E-Business Suite. With this approach, a snapshot of the data is taken to avoid a race condition where the data may be changed after the time the event is raised and before the data is extracted.

The Send Document function may be modeled using the XML Gateway Rule Function or the Workflow Default Rule Function to ensure that XML messages are sent to Trading Partners enabled for the transaction.

Oracle Workflow Builder Window with Send Document Function Displayed

the picture is described in the document text

The attributes for the Send Document function are shown in the following table. The values for the attributes are provided by the business event, another function activity, or are set as constants.

Attribute Name Attribute Description
Transaction Type This is the Transaction Type defined in the XML Gateway Define Transactions form.
Transaction Subtype This is the Transaction Subtype defined in the XML Gateway Define Transactions form.
Document ID This is the unique identifier for the business document. It can be the document number or its associated database key, whichever is guaranteed to be unique for the transaction.
Party Site ID This is the unique identifier for the Trading Partner site defined in Oracle E-Business Suite.
Party ID This is the unique identifier for the Trading Partner defined in Oracle E-Business Suite. This field is optional.
Parameter 1 Optional variable. This attribute is used if it is used in the message map.
Parameter 2 Optional variable. This attribute is used if it is used in the message map.
Parameter 3 Optional variable. This attribute is used if it is used in the message map.
Parameter 4 Optional variable. This attribute is used if it is used in the message map.
Parameter 5 Optional variable. This attribute is used if it is used in the message map.
Send Mode Select "Deferred" or "Immediate"
Message ID This is a unique identifier provided by the XML Gateway execution engine for each outbound message.
Party Type Party Type defined in the XML Gateway Trading Partner Setup window.

Transaction Delivery Required? (applies to B2B for outbound messages)

The Transaction Delivery Required function is used to determine if the Trading Partner is enabled for the transaction. It is used for B2B integration where Trading Partner validation is required. The function returns TRUE or FALSE.

The Transaction Delivery Required function is also embedded in the XML Gateway Rule Function. No Workflow process will be executed if the function returns FALSE.

The seeded event subscription delivered by Oracle E-Business Suite application modules can use the XML Gateway Rule Function or the Workflow Default Rule Function. The XML Gateway Rule Function is more efficient because it predetermines whether the Trading Partner is enabled for the transaction and executes the associated Workflow process only if the result of the rule function is TRUE. It is therefore the recommended approach.

Oracle Workflow Builder Window with Transaction Delivery Required? Function Displayed

the picture is described in the document text

The attributes for the Transaction Delivery Required function are shown in the following table. The values for the attributes are provided by the business event, another function activity, or are set as constants.

Attribute Name Attribute Description
Transaction Type This is the Transaction Type defined in the XML Gateway Define Transactions form.
Transaction Subtype This is the Transaction Subtype defined in the XML Gateway Define Transactions form.
Party Site ID This is the unique identifier for the Trading Partner site defined in Oracle E-Business Suite.
Party ID This is the unique identifier for the Trading Partner defined in Oracle E-Business Suite.
Party Type The Party Type defined in the XML Gateway Trading Partner Setup window.
Confirmation Flag The Document Confirmation flag from the Trading Partner Setup window. Indicates whether a confirmation is sent or received. The Confirmation Flag has been added to the Transaction Delivery Required? (DELIVREQUIRED) function activity. Workflows for outbound business documents can now be designed to wait for the inbound confirmation if the ECX_CONFIRMATION_FLAG is set to 1 (send confirmation if error detected) or 2 (always send confirmation). The Confirmation Flag is an attribute of the Trading Partner that is defined using the Trading Partner Setup window. Use this Workflow design approach if you want to link the outbound business document with the inbound confirmation. This is optional.

Transform XML

The Transform XML function is used for XML to XML transformation.

Oracle Workflow Builder Window with Transform XML Function Displayed

the picture is described in the document text

The Transform XML function transforms a given Input XML document into another XML document. The input parameters to this activity are the Map Code and the Input XML Document. The output of the activity is the transformed XML document. The execution engine will execute the transformation according to the Map Definition.

The attributes for the Transform XML function are shown in the following table. The Event Message In attribute stores the input XML information and the Event Message Out attribute stores the transformed XML information.

Attribute Name Attribute Description
Map Code The Map Code associated with the Transaction as defined in the Trading Partner Details form.
Event Message In The Input XML message.
Event Message Out The Transformed XML message.

Events

The XML Gateway Standard Item Type includes three Events to raise a business event from an existing Workflow process.

Oracle Workflow Builder Window with Events Highlighted

the picture is described in the document text

Generic Receive Event

The Generic Receive Event is used to support the Create Trading Partner Message process.

Raise Document Delivery Event

The Raise Document Delivery Event is used to raise a business event from an existing Workflow process. This allows you to seamlessly integrate your existing Workflow process with Oracle XML Gateway to create an outbound XML message.

An alternate approach is to raise the business event directly from PL/SQL code. Refer to the Raise, Oracle Workflow API Reference for the details.

Oracle Workflow Builder Window with Raise Document Delivery Event Displayed

the picture is described in the document text

The attributes for the Raise Document Delivery Event are shown in the following table. The values for the attributes are provided by a function activity or are set as constants.

Attribute Name Attribute Description
Transaction Type This is the Transaction Type defined in the XML Gateway Define Transactions form.
Transaction Subtype This is the Transaction Subtype defined in the XML Gateway Define Transactions form.
Document ID This is the unique identifier for the business document. It can be the document number or its associated database key, whichever is guaranteed to be unique for the transaction.
Party Site ID This is the unique identifier for the Trading Partner site defined in Oracle E-Business Suite.
Party ID This is the unique identifier for the Trading Partner defined in Oracle E-Business Suite.
Parameter 1 Optional Variable. This attribute is used if it is used in the message map.
Parameter 2 Optional Variable. This attribute is used if it is used in the message map.
Parameter 3 Optional Variable. This attribute is used if it is used in the message map.
Parameter 4 Optional Variable. This attribute is used if it is used in the message map.
Parameter 5 Optional Variable. This attribute is used if it is used in the message map.

WF Send

The WF Send Event enqueues a message onto the ECX_OUTBOUND queue. This event is used in conjunction with Callback. See Message Delivery Status for a complete description of this event and its attributes.

Lookup Types

The XML Gateway Standard Item Type supports the Send Mode Lookup Type used in the Send Document function to indicate whether the event subscription should be processed immediately or in deferred mode.

Oracle Workflow Builder Window with Lookup Types Displayed

the picture is described in the document text

Communications Method

Confirmation Values

Confirmation Values are used in the Transaction Delivery Required function activity.

Party Types

Party Types are used in the Get Trading Partner Role and Send Document function activities.

Send Mode

Send Mode is used in the Send Document function activity.

XML Gateway Error Processing Item Type

The XML Gateway Error Processing Item Type contains error handling processes to manage errors detected by Oracle Workflow Business Event System or Oracle XML Gateway.

Oracle Workflow sends a notification to the Trading Partner contact for data errors or to the XML Gateway system administrator for system or process errors. For errors that require collaboration between the Trading Partner contact and the XML Gateway system administrator, a notification is sent to both parties to encourage discussion and to expedite problem solution.

In addition, Oracle Workflow sends a notification to an appropriate transaction owner depending on the transaction type of an erred inbound transaction. If a transaction owner for a particular transaction type is identified, and the transaction error belongs to the transaction type with the owner defined, then the transaction owner will receive a notification in addition to the system administrator and Trading Partner contact depending on the error type. For example, if an inbound transaction error belongs to the Purchasing transaction type, then the Purchasing transaction owner also receives the notification if his or her user name is defined in the Define Transactions form.

A transaction owner can act on an error notification if needed. Once an open notification has been responded on either reprocess or abort, any other subsequent response from the XML Gateway system administrator will be ignored and the notification should be closed.

However, if the system administrator or transaction owner has not taken an explicit action such as reprocess or abort on a notification that was received earlier, after the notification timeout period, the XML Gateway execution engine will automatically reprocess the corresponding erred transaction until the number of maximum retries is exceeded. Oracle XML Gateway uses the following two profile options to manage the timeout feature:

Note: The Workflow Retry feature is used to support outbound messages; it resumes from the point of failure. The ECX Reprocess Inbound function is used to support the reprocess feature for inbound messages; it resumes using a copy of the inbound message stored in the ECX_DOCLOGS table.

Attributes

Attributes, also known as variables, are used to support the function, event, notification, and process activities defined for the XML Gateway Error Processing Item Type.

Processes

The XML Gateway Error Processing Item Type supports the following error handling processes:

The relationship of the error handling processes is shown below. The ECX Main Error Process calls the ECX Main Error Inbound process for inbound message errors or the ECX Main Error Outbound process for outbound message errors. If inbound, the ECX Main Error Inbound process calls the Error Handling for Inbound Message process, which calls the ECX Error Process for Timeout. If outbound, the ECX Main Error Outbound process calls the Error Handling for Outbound Message process, which calls the Default Error process.

the picture is described in the document text

The following is a description of each Process (listed in their functional order above) supported by the XML Gateway Error Processing Item Type:

ECX Main Error Process

The ECX Main Error Process is triggered by the Receive Error Event (see illustration, node 1), the Receive Inbound Subscription Error event, or the Receive Inbound Subscription Processing Error event for errors detected by the XML Gateway execution engine; or by Workflow for errors involving the Workflow processes created using the XML Gateway Standard Item Type.

At node 2, the process determines whether the error relates to an inbound or outbound message. The ECX Main Error Process calls the ECX Main Inbound Error Process (node 3) for errors related to an inbound message. For errors related to an outbound message, it calls the ECX Main Outbound Error Process (node 4).

the picture is described in the document text

ECX Main Inbound Error Process

As shown in the illustration below, ECX Main Inbound Error Process gets the error information (node 1) from the XML Gateway execution engine or Workflow engine and calls the Error Handling for Inbound Messages process (node 2).

the picture is described in the document text

Error Handling for Inbound Messages

Errors detected by the XML Gateway execution engine or Workflow engine may trigger a notification. The notification can be sent to the XML Gateway system administrator, the Trading Partner contact, or both depending on the nature of the error, as well as an appropriate transaction owner if the information is identified.

Notifications can be e-mailed to the target recipient(s) if the Workflow mailer is enabled. The e-mail or user name information is defined in the following places:

The target recipient(s) of the notification are predefined for the error message and cannot be changed.

The Error Handling for Inbound Messages process checks the type of the error detected (shown in the following diagram, node 1). If the error type indicates that no notification is sent, the failed process ends, and the error process ends.

If the compare in node 1 indicates that a notification is to be sent, the process retrieves the timeout value measured in minutes from the ECX: Notification Timeout in Minutes profile option (node 2), and retrieves the trading partner contact information (Company Admin e-mail) from the trading partner tables (node 3). If the error type indicates that the target recipient is the Trading Partner contact (performed in node 4), a notification is sent to the Trading Partner (node 5), the failed process ends, and the error process ends.

If the check in node three did not indicate that the target recipient is solely the Trading Partner contact, the process retrieves the System Administrator contact information and the transaction owner contact information if it is available (node 6) and checks the error type again (node 7).

the picture is described in the document text

If the target recipients are both the Trading Partner contact and the XML Gateway system administrator, then the process retrieves the transaction owner contact information if available from the Define Transactions form (node 9), and then three notifications are sent, one to each party (nodes 8, 10, and 11). The system administrator and the transaction owner both have the option of reprocessing or aborting the failed inbound process (node 12). Reprocessing resumes using a copy of the inbound message stored in the ECX_DOCLOGS table.

If the target recipient is solely the XML Gateway system administrator, then the process retrieves the transaction owner contact information if available from the Define Transactions form (node 14), and then two notifications are sent, one for the system administrator and the other for an appropriate transaction owner (node 15 and 16). Both of them have the option to reprocess (node 17) or abort (node 18) the failed inbound process.

If the system administrator or a transaction owner does not respond to the notification that is waiting for action, and the notification timeout period specified in the ECX: Notification Timeout in Minutes profile option is exceeded, the ECX Error Process for Timeout will be called (node 19). This step enables XML Gateway execution engine to automatically reprocess the corresponding erred transaction if it does not exceed the maximum retries limit set by the ECX: Maximum Reprocess Attempts For Errored Inbound Transaction profile option.

the picture is described in the document text

ECX Error Process for Timeout

During the error handling for inbound messages, the ECX Error Process for Timeout process is called by the Error Handling for Inbound Messages process to have the XML Gateway execution engine automatically reprocess an erred inbound transaction when the XML Gateway system administrator or the transaction owner has not taken an explicit action on a notification that was sent earlier, and the timeout value for a notification waiting for a response is exceeded but the number of automatically reprocess has not yet reached the maximum retries limit.

When a notification that was sent earlier has not yet responded explicitly (shown in the following diagram, node 1), the XML Gateway execution engine will automatically reprocess an erred transaction (node 2).

the picture is described in the document text

ECX Main Outbound Error Process

ECX Main Outbound Error Process initializes the error (shown below, node 1) and gets the error information (node 2) from the XML Gateway execution engine or Workflow engine and calls the Error Handling for Outbound Messages process (node 3).

the picture is described in the document text

Error Handling for Outbound Messages

Errors detected by the XML Gateway execution engine or Workflow engine may trigger a notification. The notification can be sent to the XML Gateway system administrator, the Trading Partner contact, or both depending on the nature of the error.

Notifications may be e-mailed to the target recipient(s) if the Workflow mailer is enabled. Their e-mail addresses are defined in the following places:

The target recipient(s) of the notification are predefined for the error message and cannot be changed.

The Error Handling for Outbound Messages process checks the error type to determine if a notification is to be sent (shown below, node 1). If the type indicates that no notification is to be sent, the process ends.

If the type does not indicate that no notification is to be sent, the process retrieves the trading partner contact information (Company Admin e-mail) from the trading partner tables (node 2). The notification type is checked (node 3), and if the target recipient is solely the Trading Partner contact, a notification is sent to the Trading Partner (node 4) and the failed process is aborted.

If the target recipient is not solely the trading partner contact, the system administrator contact is retrieved (node 5) and the Default Error Process will be called (node 6). At node 8 the type is checked to determine if the notification is to be sent to both the trading partner and the system administrator.

If the target recipients are both the Trading Partner contact and the XML Gateway system administrator, then notification is also sent to the Trading Partner contact (node 9).

the picture is described in the document text

the picture is described in the document text

(FYI) Message Delivery Error Process

The (FYI) Message Delivery Process is used with Oracle Transport Agent (or other messaging systems) to report message delivery status back to the Workflow process that initiated message creation.

A corresponding event subscription (seeded in XML Gateway) for the oracle.apps.ecx.processing.message.callback event initiates the XML Gateway Standard Error Processing Item Type:FYI_MESSAGE_DELIVERY_ERROR error handling process. In the event of an error, a notification is sent to the System Administrator who has the option to "Resend" the message after correcting the error, or to "Ignore" the notification if no action is required.

the picture is described in the document text

Default Error Process

The Default Error Process is called by the Error Handling for Outbound Messages process when the error message notification is for the system administrator.

The Workflow notification administrator delivers the notification (shown below, node 1) to the system administrator as well as proceeds on one of the following paths:

ECX Engine Notification Process

The Receive Send Notification Event (shown below, node 1) triggers the ECX Engine Notification Process.

The ECX Engine Notification Process checks the error type to determine the target recipient (node 2). If the target recipient is the Trading Partner contact, notification is sent (node 3). If the error type does not indicate that the Trading Partner contact is the sole target recipient, the process checks the error type (node 4) to determine if the notification should be sent to the XML Gateway system administrator (node 5), or both parties (node 6).

the picture is described in the document text

Notifications

the picture is described in the document text

The following is a description of each Notification supported by the XML Gateway Error Processing Item Type:

ECX Event Notification (FYI)

The ECX Event Notification [FYI] is used to send a notification to the system administrator.

This notification is used by the ECX Engine Notification Process.

ECX External Event Notification

The ECX External Event Notification is used to send a notification to the system administrator.

This notification is used by the Error Handling for Inbound Messages process.

Message Delivery Error (FYI)

The Callback feature allows messaging systems (including OTA) to report message delivery status back to the Workflow process that initiated message creation. If delivery fails, the apps.ecx.processing.message.callback event is raised. The corresponding event subscription for the FYI_MESSAGE_DELIVERY_ERROR process is executed and a Workflow notification is sent to the System Administrator (defined in the ECX: System Administrator Email Address profile) who has the option to retry/resend or about/ignore the process.

Trading Partner Inbound Error Notification

The Trading Partner Inbound Error Notification is used to send a notification to the Trading Partner contact.

This notification is used by the Error Handling for Inbound Message and ECX Engine Notification processes.

Trading Partner Outbound Error Notification

The Trading Partner Outbound Error Notification is used to send a notification to the Trading Partner contact.

This notification is used by the Error Handling for Outbound Message process.

Transaction Owner Inbound Error Notification

The Transaction Owner Inbound Error Notification is used to send a notification to the transaction owner if the owner is specified in the Define Transactions form.

This notification is used by the Error Handling for Inbound Message process.

Functions

the picture is described in the document text

Several functions are provided in the XML Gateway Error Processing Item Type to support the error handling process.

ECX Reprocess Inbound

The ECX Reprocess Inbound function is used if the XML Gateway system administrator responded to the error notification by selecting the "reprocess" option. The reprocess function will rerun the inbound process using a copy of the inbound message stored in the ECX_DOCLOGS table.

The "reprocess" function is not supported for external notifications to the Trading Partner.

The attribute for the ECX Reprocess Inbound function is:

Variable Description
ECX Message ID This is a unique identifier provided by the XML Gateway execution engine for each outbound message.

ECX Resend Outbound Message

The ECX Resend Outbound function is provided to support Oracle Exchange only, it is not used in the XML Gateway Error Processing Item Type. The ECX Resend Outbound function resumes from a copy of the outbound message stored in the ECX_DOCLOGS table.

The Oracle Workflow "retry" function is used to rerun an outbound process from the point of failure. This is handled using the Default Error Process.

The attribute for the ECX Resend Outbound function is shown in the following table:

Variable Description
ECX Message ID This is a unique identifier provided by the XML Gateway execution engine for each outbound message.

ECX Timeout Value

The ECX Timeout Value function is used to retrieve the timeout period measured in minutes stored in the ECX: Notification Timeout profile option.

If the XML Gateway system administrator or the transaction owner has not taken explicit action, such as reprocess or abort, on a notification that was received earlier, after the notification timeout period, the XML Gateway execution engine will automatically reprocess the erred transaction until the number of maximum retries is exceeded. The maximum retries value is stored in the ECX: Maximum Reprocess Attempts For Errored Inbound Transaction profile option.

Error Still Active

The Error Still Active function is used to check whether the error still existed for the outbound message after notifications have sent to appropriate parties, such as Trading Partner contact and XML Gateway system administrator.

Get ECX In Error Details

The Get ECX In Error Details function activity is used to get the details regarding an inbound error to prepare the e-mail notification. In addition, required information is passed to the Error Handling for Inbound Messages process activity.

Get ECX Out Error Details

The Get ECX Out Error Details function is used to get the details regarding an outbound error to prepare the notification. In addition, required information is passed to the Error Handling for Outbound Messages process.

Get System Administrator Role

The Get System Administrator Role function is used to retrieve the e-mail address for the system administrator stored in the ECX: System Administrator Email Address system profile.

The e-mail address retrieved from the system profile is returned by the function and stored in the ECX System Administrator Role (ECX_SA_ROLE) item attribute.

A notification is sent to the XML Gateway system administrator for system or process errors detected by Oracle XML Gateway or Oracle Workflow Business Event System.

Get Trading Partner Role

The Get Trading Partner Role function is used to determine the e-mail address for the Trading Partner contact that was provided when the Trading Partner was defined.

The function uses the attribute values passed to it to uniquely identify the Trading Partner. The e-mail address associated with the Trading Partner selected returned by the function is stored in the ECX Trading Partner Role (ECX_TP_ROLE) item attribute.

A notification is sent to the Trading Partner contact for data errors detected by Oracle XML Gateway.

The attributes for the Get Trading Partner Role function are shown in the following table:

Attribute Name Attribute Description
ECX Party ID This is the unique identifier for the Trading Partner defined in Oracle E-Business Suite. This field is optional.
ECX Party Site ID This is the unique identifier for the Trading Partner site defined in Oracle E-Business Suite.
ECX Transaction Type This is the Transaction Type defined in the XML Gateway Define Transactions form.
ECX Transaction Subtype This is the Transaction Subtype defined in the XML Gateway Define Transactions form.

Get Transaction Owner Role

The Get Transaction Owner Role function is used to determine the e-mail address for the transaction owner if the owner's user name was specified in the Define Transactions form.

The function uses the attribute values passed to it to uniquely identify the transaction owner if the owner is defined. The e-mail address associated with the transaction owner's user name that was defined in the applications as the application login name is retrieved and returned by the function.

A notification is sent to an appropriate transaction owner depending on the erred transaction type for process errors detected by Oracle XML Gateway.

The Get Transaction Owner Role function uses the following attributes:

Attribute Name Attribute Description
ECX Transaction Type This is the Transaction Type defined in the XML Gateway Define Transactions form.
ECX Transaction Subtype This is the Transaction Subtype defined in the XML Gateway Define Transactions form.
ECX Party Type This is the party type for the Trading Partner defined in Oracle E-Business Suite.
ECX Party Site ID This is the unique identifier for the Trading Partner site defined in Oracle E-Business Suite.
ECX Message Standard This is the XML message format standard defined in the Define Transactions form.
ECX Message Type This is the payload message format, which is XML.

Events

the picture is described in the document text

The XML Gateway Error Processing Item Type supports the following event activities:

All of the XML Gateway seeded events and event subscriptions are seeded with a Customization Level of "L" for Limit, which means the event or event subscription may be enabled or disabled but may not be changed in any other way. Because the seeded events and event subscriptions play an integral role in the total solution, Oracle does not recommend that you disable any of them. If necessary, you may define additional events and event subscriptions to augment the seeded activities.

Message Delivery Error

The Message Delivery Error Event is used by the XML Gateway to indicate that an error has occurred. This event is used with OTA Callback.

The seeded event name is oracle.apps.ecx.processing.message.callback. This event triggers the (FYI) Message Delivery Error Process workflow.

Receive Error

The Receive Error event is used by XML Gateway to indicate that the execution engine has detected an error. Regardless of whether the error was detected by Oracle XML Gateway or Oracle Workflow Business Event System, the same ECX Main Error Process manages the error. See: ECX Main Error Process for the details.

The seeded event name is oracle.apps.ecx.processing.message.error. This event triggers the ECX Main Error Process workflow.

Receive Send Notification Event

The Receive Send Notification Event is used by XML Gateway to indicate that the execution engine has identified a need to send a notification for errors related to an inbound process. The ECX Engine Notification Process manages the error. See: ECX Engine Notification Process for the details.

The seeded event name is oracle.apps.ecx.processing.notification.send. This event triggers the ECX Engine Notification Process workflow.

Receive the inbound subscription error

The event "oracle.apps.ecx.inbound.message.receive" is raised by the ECX_INBOUND agent listener after it dequeues a message from the ECX_INBOUND queue. The "Receive Inbound Subscription Error" Event is used to indicate that there is an error when executing the subscription for the event "oracle.apps.ecx.inbound.message.receive".

This subscription is savies the xml message to ecx_doclogs, checks the trading partner setup for the given transaction, performs logging, and enqueues the message to the next queue for the actual map processing.

Receive the inbound subscription processing error

The event "oracle.apps.ecx.inbound.message.process" is raised by the ECX_TRANSACTION agent listener after it dequeues a message from the ECX_IN_OAG_Q queue. The "Receive Inbound Subscription Processing Error" is used to indicate that there is an error when processing the inbound xml document.

Messages

The XML Gateway Error Processing Item Type provides several message templates used by the various notification activities to send a notification to the XML Gateway system administrator or the Trading Partner contact based on the nature of the error.

the picture is described in the document text

Below is a description of each message template. The message template is displayed in the Body tab and Text Body subtab.

ECX Event Message (FYI)

The ECX Event Message [FYI] template is used by the ECX Event Notification. The template includes information regarding the transaction, the type of error detected, and the associated error message.

ECX External Event Message

The ECX External Event Message template is used by the ECX External Event Notification activity. The template includes information regarding the transaction, the type of error detected, and the associated error message.

Inbound Trading Partner Message

The Inbound Trading Partner Message template is used by the Trading Partner Inbound Error Notification activity. The template includes information regarding the transaction, the type of error detected, and the associated error message.

Message Delivery Error

The Message Delivery Error template is used by the XML Message Delivery Callback error process. The template includes information regarding the action to take in case of error.

Outbound Trading Partner Message

The Outbound Trading Partner Message template is used by the Trading Partner Outbound Error Notification activity. The template includes information regarding the transaction, the type of error detected, and the associated error message.

Message Template Attributes

Each message template has the attributes listed in the following table. The values for the attributes are provided by the Get ECX Out Error Details and Get ECX In Error Details function. The values are used to replace the message tokens in the message template.

For a detailed explanation of each error and possible corrective actions, see Manual Troubleshooting Steps.

The following table describes all the possible attributes:

Lookup Types

The XML Gateway Error Processing Item Type supports several lookup types for the error handling processes.

the picture is described in the document text

ECX Inbound Error Actions

The ECX Inbound Error Actions lookups are used by the ECX External Event Notification as a Result Type attribute. The valid values are as follows:

ECX Outbound Error Actions

The ECX Outbound Error Actions lookups is used by the Default Error Process. The valid value is as follows:

The retry function is supported by the Default Error Process.

ECX Outbound Error Types

The ECX Outbound Error Types lookups are used by the Get ECX Error Type function as a Result Type attribute. The valid values are as follows:

ECX Resend Actions

ECX Resend Actions are lookups used by the XML Gateway Error Process. The valid values are as follows:

Configure Oracle Prebuilt Inbound Messages

Seeded Business Event and Corresponding Event Subscription

Inbound messages that are prebuilt and delivered by Oracle E-Business Suite application modules are delivered with the following:

An event subscription is required for inbound messages from Trading Partners (B2B) regardless of whether the application is interested in the inbound message. The seeded event subscription uses the Workflow Default Rule Function but may be configured to use a rule function and Workflow process relevant to the business requirement.

See the Message Designer for instructions on how to create a new message map and how to modify an Oracle prebuilt message map.

Configuration Options for Seeded Event Subscription

Use the Workflow Administrator to configure the seeded event subscription for the prebuilt inbound message if necessary.

  1. Register new event subscription

    Use the Workflow Administrator Add Event Subscription window to register the new event subscription if you defined a new subscription instead of configuring the seeded subscription.

    See Manage Workflow Processes for instructions on how to register new event subscriptions.

  2. Configure Seeded Subscription

    Use Oracle Workflow Administrator Add Event Subscription window to configure the seeded event subscription to consume the inbound message if your application is interested in it. The subscription will trigger the Oracle E-Business Suite to perform some activity. The actual activity performed by the event subscription will be based on the Workflow process defined for it. Some examples are as follows:

    • Integrate with existing Workflow process defined in the Oracle E-Business Suite

    • Call an application API to perform a specific function

      See: Manage Workflow Processes for instructions on how to register new event subscriptions and configure a seeded event subscription.

Configure Oracle Prebuilt Outbound Messages

Seeded Business Event and Corresponding Event Subscription

Outbound messages that are prebuilt and delivered by Oracle E-Business Suite application modules are delivered with the following:

The seeded event subscription consumes all the seeded events but may be configured to execute a specific Workflow process for the outbound events it is interested in.

See the Message Designer chapter for instructions on how to create a new message map and how to modify an Oracle prebuilt message map.

Configuration Options for Seeded Event Subscription

Use the Workflow Administrator to configure the seeded event subscription for the prebuilt outbound message if necessary.

  1. Register new event subscription

    Use the Workflow Administrator Add Event Subscription window to register the new event subscription if you defined a new subscription instead of configuring the seeded subscription.

    See Manage Workflow Processes for instructions on how to register new event subscriptions.

  2. Configure Seeded Event Subscription

    Use Oracle Workflow Administrator Add Event Subscription window to configure the seeded event subscription to consume the application business event of interest. The subscription will trigger the Oracle E-Business Suite to perform some activity. The actual activities performed by the event subscription will be based on the Workflow process defined for it.

    There are three subscription options for the Business-to-Business (B2B) integration scenario described below. The function activities outlined are supported by the XML Gateway Standard Item Type.

    Send Document Function Using XML Gateway Rule Function

    This option uses the XML Gateway Rule Function which has the Transaction Delivery Required function embedded in it to determine if the Trading Partner is enabled for the transaction before the message is generated.

    The "Send Document" function can be configured to generate the message in synchronous or asynchronous mode by setting the Send Mode attribute to "Immediate" or "Deferred" respectively.

    The following is an example of a Workflow process launched by the XML Gateway Rule Function. The Receive activity is followed by the Send Document function activity, which proceeds to End. The Transaction Delivery Required Function is not modeled in the Workflow process since it is already included in the rule function.

    An Example of a Workflow Process Flow Launched by the XML Gateway Rule Function

    the picture is described in the document text

    Note: The first Workflow activity may be a Receive or a Start activity. Use Receive to continue an existing Workflow process. Use Start to begin a new Workflow process.

  3. Send Document Function Using Workflow Default Rule Function

    This option is used to first determine if the Trading Partner is enabled for the transaction. If the result of the Transaction Delivery Required function activity returns TRUE, the "Send Document" function activity is executed.

    The "Send Document" function activity may be configured to send the message in synchronous or asynchronous mode by setting the Send Mode attribute to "Immediate" or "Deferred" respectively.

    The following is an example of a Workflow process launched by the Workflow Default Rule Function. The Transaction Delivery Required Function is modeled in the Workflow process since it is not included in the Workflow Default Rule Function.

    An Example of a Workflow Process Flow Launched by the Workflow Default Rule Function

    the picture is described in the document text

    Note: The first Workflow step may be a Receive or a Start activity. Use Receive to continue an existing Workflow process. Use Start to begin a new Workflow process.

  4. Generate Trading Partner XML Document

    This option is used to gather and return the message data in the Event Message attribute without delivering it to the Trading Partner. The Event Message is then processed according to the subsequent Workflow instruction.

    The following is an example of a Workflow process using the Generate Trading Partner XML Document function. A Receive activity is followed by the Transaction Delivery Required function activity. If it returns False, the process proceeds to End. If True, the Generate Trading Partner XML Document function activity is executed and proceeds to End. In a production Workflow process, the Generate Trading Partner XML Document function activity would be followed by an application-specific activity.

    An Example of a Workflow Process Flow Using the Generate Trading Partner XML Document Function

    the picture is described in the document text

    Note: The first Workflow step may be a Receive or a Start activity. Use Receive to continue an existing Workflow process. Use Start to begin a new Workflow process.

Application to Application Integration

The XML Gateway Standard Item Type provides function activities to support A2A integration requirements. Listed below are the options for inbound and outbound transactions.

Inbound Option

Consume XML Document

This option is used to interact with Oracle XML Gateway to insert data into the base application tables. Depending on how the message map was defined, the data may be inserted using an Application Open Interface API or an Application API. See: How to Map to an API.

The Consume XML Document function is used for A2A integration. It may be used in existing Workflow processes for which the Event Message attribute is used to pass the message data. This makes it unnecessary to raise a business event or define an event subscription as recommended in the B2B integration scenario.

The following is an example of a Workflow process using the Consume XML Document function:

This Workflow process shows the Consume XML Document (2) function activity completing and followed by an End function (3). In a production Workflow process, the Consume XML Document function activity would be followed by an application-specific activity.

the picture is described in the document text

Note: The first Workflow step (1) may be a Receive or a Start activity. Use Receive to continue an existing Workflow process. Use Start to begin a new Workflow process.

Outbound Option

Generate XML Message

This option is used to generate the XML message and forward it to the subsequent Workflow process. The Generate XML Document function activity is used to gather the document data and return it in the Event Message attribute. The Event Message is then processed according to the Workflow instructions which may be to send it to another Oracle E-Business Suite application module.

The following is an example of a Workflow process using the Generate XML Document function:

An Example of a Workflow Process Flow Using the Generate XML Document Function

the picture is described in the document text

The Workflow process shows the Generate XML Document function activity completing and followed by an End function. In a production Workflow process, the Generate XML Document function activity would be followed by an application specific activity.

Note: The first Workflow step may be a Receive or a Start activity. Use Receive to continue an existing Workflow process. Use Start to begin a new Workflow process.

Manage Workflow Processes

Use the following Oracle Workflow Administrator windows to help manage your Workflow processes.

For more information about these windows, see Oracle Workflow Developer's Guide and Oracle Workflow User's Guide.

Register New Business Events and Event Subscription

This process is necessary for new events and subscriptions added as a result of creating a new XML message. The seeded business events and event subscriptions delivered by the Oracle E-Business Suite have already been registered. There is no need to register a seeded event subscription that was configured during implementation.

Use the Events window, Oracle Workflow Developer's Guide to add a new business event.

Use the Subscriptions window, Oracle Workflow Developer's Guide to add a new subscription to consume the new event.

Identify Seeded Item Types

Use the Developer Studio, Oracle Workflow Developer's Guide to view the seeded item types delivered by Oracle Workflow Business Event System, Oracle XML Gateway, and Oracle E-Business Suite modules.

Identify Seeded Business Events and Associated Event Subscriptions

Use the Events window, Oracle Workflow Developer's Guide to view the seeded business events delivered by Oracle Workflow Business Event System, Oracle XML Gateway, and Oracle E-Business Suite modules.

Select the business event and click on Edit Subscription to proceed to the Subscriptions window, Oracle Workflow Developer's Guide to view the associated subscriptions.

Configure or Delete Seeded Event Subscriptions

From the Subscriptions window, Oracle Workflow Developer's Guide, select the subscription and click Edit to configure the subscription. Click Delete to delete the subscription. You can modify the rule function or Workflow process defined for the subscription.

View and Respond to Error Notifications

Use the Worklist window, Oracle Workflow User's Guide to view and respond to notifications awaiting your attention.

Purge XML Gateway Transactions

To purge workflow or non-workflow related XML Gateway transaction data, Oracle XML Gateway allows you to use the following concurrent programs to purge XML Gateway transactions:

Purge Obsolete ECX Data Concurrent Program

To purge non-workflow related XML Gateway transactions, Oracle XML Gateway lets you use the Purge Obsolete ECX Data concurrent program to exclusively purge XML Gateway transaction data based on transaction type, transaction subtype, and date range.

Note: Since Workflow purge is associated with item_type and item_key, XML Gateway logs do not have these parameters available all the time. In case of inbound transaction item_type and item_key parameters are not available, you can submit the Purge Obsolete ECX Data concurrent program to specifically purge XML Gateway transaction data.

Parameters and Purge Behavior
Parameters Expected Behavior
Transaction Type All data corresponding to that specific Transaction Type will be deleted.
Transaction Type
Transaction Subtype		 All data corresponding to that specific Transaction Type and Subtype will be deleted.
Transaction Type
Transaction Subtype
From Date		 All data corresponding to that specific Transaction Type and Subtype will be deleted after the specified date.
Transaction Type
Transaction Subtype
From Date
To Date		 All data corresponding to that specific Transaction Type and Subtype will be deleted within the specified date range.
From Date All data after the specified date will be deleted regardless of Transaction Type and Subtype.
From Date
To Date		 All data within the specified date range will be deleted regardless of Transaction Type and Subtype.
No parameter is given All data will be deleted regardless of Transaction Type, Subtype, and date range.

Use the Submit Requests form in Oracle E-Business Suite to submit these concurrent programs.

Note: Commit Cycle will be of 500 rows as it is done in Workflow Purge.

Purge Obsolete Workflow Runtime Data Concurrent Program

When purging workflow related XML Gateway transactions, use the Purge Obsolete Workflow Runtime Data concurrent program instead. This concurrent program is used in conjunction with the 'ECX: Purge ECX data with WF' profile option which lets you have an option to either purge XML Gateway data along with workflow data or purge workflow data only.

When the Purge Obsolete Workflow Runtime Data concurrent program is submitted, the 'ECX: Purge ECX data with WF' profile value will be retrieved to determine whether XML Gateway data will be purged together with workflow data or only workflow data will be purged.

For more information on 'ECX: Purge ECX data with WF' profile option, see Define System Profile Options.

Note: You can use Oracle Workflow Manager to submit and manage the Purge Obsolete Workflow Runtime Data concurrent program. See: Purging Workflow Data, Oracle Workflow Administrator's Guide.

Monitor Workflow Processes

Identified below are several Oracle Workflow Administrator windows to help monitor your Workflow processes:

Transaction-Level Trace

The trace function is performed via centralized logging through the Applications Logging Framework. Using the logging framework you can enable logging and set log levels using FND profile options. For information on logging, see the Logging chapter, Oracle E-Business Suite Maintenance Guide.

Monitor Transaction Status

Use the Event Queue Summary window to monitor the status of a transaction. Select the Agent Listener and click the View Detail icon. Once you enter the selection criteria to identify the transaction, the detail information including status and an option to view the event data in XML or text format, are presented.

Review XML Message Returned by Generate Functions

Modify the subscription for the Generate XML Document or Generate Trading Partner XML Document function and set the Action: Out Agent field to the WF_OUT. The XML data gathered by the function is directed to the WF_OUT agent.

For instructions on viewing the XML message directed to WF_OUT see: Monitor Transaction Status.

Start Agent Listeners

There is one Agent Listener per inbound agent. The agents necessary to support the integration between Oracle Workflow Business Event System and Oracle XML Gateway are shown in the following table:

Agent Name Description
ECX_INBOUND Agent for inbound messages originating from outside the enterprise for B2B integration.
ECX_TRANSACTION Agent for inbound messages originating from within the enterprise for A2A integration.
WF_OUT Agent to stage outbound messages. ECX_OUTBOUND is the agent used to stage and deliver outbound XML messages to the Trading Partner.
WF_IN Agent to receive inbound messages sent to the Oracle E-Business Suite.
WF_DEFERRED Agent for outbound messages sent in deferred mode.
WF_ERROR Agent for errors detected by Oracle Workflow Business Event System or Oracle XML Gateway.

The agents must be enabled and the seeded agent listener service components must be running.

Note: Additional agents are provided for Web services. See Web Services Setup.

Use the Workflow Administrator: Agents window to enable the required agents if necessary (the agents are enabled by default). The same window can be used to disable an agent.

Use Oracle Applications Manager to schedule and manage agent listener service components. For more information, refer to the Oracle Applications Manager online help.

Ensure that the seeded agent listener service components named Workflow Deferred Agent Listener and Workflow Error Agent Listener, provided by Oracle Workflow, are running for the WF_DEFERRED and WF_ERROR agents, respectively.

The agent listener service components ECX Inbound Agent Listener and ECX Transaction Agent Listener are seeded with a manual startup mode and therefore must be manually started. The startup mode can be changed to "Automatic" using the Oracle Applications Manager, if desired.

Place any user-defined agents in their own container.

Development Guidelines for Custom Messages for B2B Integration

If you are using Oracle XML Gateway to create new inbound and outbound messages, use the following guidelines to raise business events and define event subscriptions.

A prerequisite to this process is a message map created using the XML Gateway Message Designer.

See the Message Designer section for instructions on how to create a new message map and how to modify an Oracle prebuilt message map.

Development Guidelines for Outbound Messages

Following are the guidelines for developing outbound messages:

  1. Register the Business Event and Corresponding Event Subscription

    Register the business event and corresponding event subscription defined in the Oracle E-Business Suite.

    See: Manage Workflow Processes for the instructions on registering business events and event subscriptions.

  2. Raise a Business Event in the Application

    Use the Workflow function to raise business events in your application at points indicating when a document has been created, changed, confirmed, or deleted. Business events may be raised in PL/SQL code, by an existing Workflow process using the Raise Document Delivery Event activity, or as the first activity of a new Workflow process.

    It is important to raise an event at all possible event points even though you may not define a specific event subscription for it. This will allow you to define an event subscription for any event of interest without having to modify the application code to raise the event.

  3. Define an Event Subscription

    Add an event subscription for each business event of interest. Use the function and event activities provided in the XML Gateway Standard Item Type to define the Workflow process associated with the event subscription.

    See: Configure Oracle Prebuilt Outbound Messages for the Workflow process configuration options.

    See: Manage Workflow Processes for the instructions on adding an event subscription.

    There is no need to add an event subscription for business events that you are not interested in. These may be added at a later point in time when the event becomes of interest to your implementation.

Development Guidelines for Inbound Messages

The guidelines for developing inbound messages are as follows:

  1. Register the Business Event and Corresponding Event Subscription

    Register the business event and corresponding event subscription defined in the Oracle E-Business Suite.

    See: Manage Workflow Processes for the instructions on registering business events and event subscriptions.

  2. Set Event Details in the Message Map

    Make sure your message map includes a post process Procedure Call action to call the Workflow function to set event details indicating XML Gateway has successfully processed the inbound message.

    See: Procedure Call: Execute Procedure for details regarding the Procedure Call action.

  3. Define an Event Subscription

    An event subscription is required for inbound messages from Trading Partners (B2B) regardless of whether the application is interested in the inbound message.

    Assuming your application is interested in the inbound message, define an event subscription with a rule function and Workflow process relevant to the business requirement.

    See: Configure Oracle Prebuilt Outbound Messages for the Workflow process configuration options.

    See: Manage Workflow Processes for the instructions on addition a Workflow process.

    There is no need to add a subscription for business events that you are not interested in. These can be added later if the business event becomes of interest to your implementation.

Common Questions

The following are common implementation questions:

  1. Is the combination of the Generate Trading Partner XML Document and Send Document function activity valid?

    No. This combination of function activities is invalid.

    The Generate Trading Partner XML Document function returns the XML message in the Event Message attribute. The Send Document function gathers the data, creates the XML message, and enqueues it onto the outbound queue.

    The result of this combination of function activities is that the Send Document function activity will complete successfully but the Generate Trading Partner XML Document function activity will have data in the Event Message attribute that is not sent anywhere unless something is defined in the Out Agent attribute (associated with the Event Subscription) which will enqueue the message.

  2. Is the combination of the Generate XML Document and Send Document function activity valid?

    Same as answer 1.

  3. Does the Generate Trading Partner XML Document function activity require the Transaction Delivery Required function activity to determine if the Trading Partner is defined to receive a document?

    Yes. The Generate Trading Partner XML Document function activity must be preceded by the Transaction Delivery Required function activity.

Message Delivery Status

XML Message Delivery Callback allows messaging systems (such as Oracle Transport Agent) to report message delivery status back to the Workflow process that initiated message creation. If delivery fails, a Workflow notification is sent to the System Administrator who has the option to retry/resend or abort/ignore the process.

Use of XML Message Delivery Callback

Prior to the introduction of this feature, the common Workflow process to send an outbound document to a Trading Partner was the Send Document function activity as follows:

An Example of a Workflow Process Flow Using the Send Document Function

the picture is described in the document text

The Send Document function activity consists of message creation and message enqueue onto the ECX_OUTBOUND queue. If XML message delivery fails, the entire Workflow is re-executed causing the message creation step to be performed again unnecessarily.

With message delivery callback, the message creation is separated from the message enqueue, so that only the message enqueue is re-executed if the message delivery fails. The new model consists of the Generate Trading Partner XML Document function activity and the Workflow Send as follows:

An Example of a Workflow Process Flow Using the Generate Trading Partner XML Function and Workflow Send

the picture is described in the document text

The Generate Trading Partner XML Document function activity is responsible for gathering the message data. The Workflow Send event activity is responsible for enqueuing the message onto the ECX_OUTBOUND queue.

The Oracle E-Business Suite application module delivers a Workflow with the event subscription in support of outbound documents that follows this model. Both models are valid. As with any seeded event subscription, you have the option to disable it. For information on how to disable a seeded event subscription, see: Manage Workflow Processes.

There are four ways that XML Message Delivery Callback can be used. They are summarized as follows:

Block Mode = Y

Block Mode is an attribute of the Workflow Send event activity. A Block Mode value of "Y" implies that your Workflow process will await the message delivery status before proceeding to the next activity in the Workflow process. If delivery fails, the Workflow Default Error Process is executed to send a notification to the System Administrator. The System Administrator has the option to "Retry" the process assuming the error was corrected, or "Ignore" the process if the error cannot be corrected.

Block Mode = N

A Block Mode value of "N" implies that your Workflow process will proceed to the next activity on the Workflow process without waiting for the message delivery status. If delivery fails, the FYI_MESSAGE_DELIVERY_ERROR process is executed to send a notification to the System Administrator.

The System Administrator has the option to "Resend" the message assuming the error was corrected or "Ignore" the notification if no action is required.

The (FYI) Message Delivery Error is a seeded process that is part of the XML Gateway Error Processing Item Type.

For more details, see XML Gateway Error Processing Item Type.

How Other Messaging Systems Use XML Message Delivery Callback

Other messaging systems such as webMethods and iAS can use the XML Message Delivery Callback feature by calling the ECX_ERRORLOG.external_system API. The API is used by all messaging systems (both Oracle and non-Oracle) to report message delivery status. The status information is written to the XML Gateway log tables to track and report message delivery data.

For details on the API see: ECX_ERRORLOG.external_system.