This chapter covers the following topics:
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:
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:
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:
The Oracle Workflow Builder contains the Oracle Workflow Standard Item Type and the Oracle XML Gateway Standard Item Type. The components of the standard item types can be used to define Workflow processes.
Oracle Workflow Administrator used to register new events and event subscriptions as well as configure seeded event subscriptions.
The Oracle Workflow processing engine used to execute the workflow processes.
Delivered with XML Gateway are two standard item types:
XML Gateway Standard Item Type
XML Gateway Error Processing Item Type
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.
Common to all item types are the following components:
Attributes
Process Activity
Notification Activity
Function Activity
Event Activity
Messages
Lookup Types
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.
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.
See XML Gateway Standard Item Type for details regarding the function and event activities.
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.
For more information on the error handling process, see XML Gateway Error Processing 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.
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, also known as variables, are used to support the function, event, notification, and process activities defined for the XML Gateway Standard Item Type.
The XML Gateway Standard Item Type supports the following process:
Create Trading Partner Message (for ECX internal use only)
The Create Trading Partner Message is a rule function available from the Workflow Event Subscription page.
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.
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.
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. |
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:
function generate
(p_event_name in varchar2, p_event_key in varchar2 p_parameter_list in wf_parameter_list_t) return CLOB;
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. |
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. |
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.
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. |
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.
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. |
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.
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. |
The Transform XML function is used for XML to XML transformation.
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. |
The XML Gateway Standard Item Type includes three Events to raise a business event from an existing Workflow process.
The Generic Receive Event is used to support the Create Trading Partner Message process.
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.
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. |
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.
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.
Attachment Enabled HTTP
Attachment Enabled HTTPS
Attachment Enabled OTA over HTTP
Attachment Enabled OTA over HTTPS
Email Delivery
HTTP Delivery
HTTPS (Secure HTTP)
No Electronic Delivery
Oracle Integration Server
Oracle Transport Agent Using HTTP
Oracle Transport Agent Using HTTPS
Confirmation Values are used in the Transaction Delivery Required function activity.
No confirmation Business Object Document Delivery
Send a confirmation Business Object Document Regardless
Send back a confirmation Business Object Document only if an error has occurred
Party Types are used in the Get Trading Partner Role and Send Document function activities.
Bank
Customer
Carrier
Exchange
Internal
Supplier
XML Gateway Standalone
Send Mode is used in the Send Document function activity.
Deferred
The Deferred mode informs the XML Gateway execution engine to defer the message creation to the Workflow background engine. This is also known as asynchronous processing.
Immediate
The Immediate mode informs the XML Gateway execution engine to create and enqueue the XML message immediately after the data has been entered into the Oracle E-Business Suite. This is also known as synchronous processing.
Synchronous processing avoids the race condition where the data may be changed between the time the event is raised and before the data is extracted.
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:
ECX: Notification Timeout Profile Option
This profile option sets the timeout period measured in minutes for a notification that is waiting for a response. If the notification timeout value is exceeded, the XML Gateway execution engine will automatically reprocess the erred transaction if it does not exceed the maximum retries limit.
ECX: Maximum Retries Profile Option
This profile option governs the number of times that the XML Gateway execution engine will automatically reprocess the erred transaction after the notification timeout period. When an error occurs during reprocessing, notifications will be sent to the XML Gateway system administrator and the transaction owner if identified. If the maximum retries limit is exceeded, the engine will not reprocess the transaction until the system administrator or the transaction owner explicitly opts for reprocessing it.
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, also known as variables, are used to support the function, event, notification, and process activities defined for the XML Gateway Error Processing Item Type.
The XML Gateway Error Processing Item Type supports the following error handling processes:
(FYI) Message Delivery Error
Default Error Process
ECX Engine Notification Process
ECX Error Process for Timeout
ECX Main Error Process
ECX Main Inbound Error Process
ECX Main Outbound Error Process
Error handling for Inbound Messages
Error handling for Outbound Messages
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 following is a description of each Process (listed in their functional order above) supported by the XML Gateway Error Processing Item Type:
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).
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).
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:
XML Gateway system administrator's e-mail address is defined in the ECX: System Administrator Email Address profile option.
The Trading Partner contact e-mail address is defined in the Trading Partner form.
The transaction owner's user name can be specified in the Define Transactions form.
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 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).
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 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 Retries profile option.
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).
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).
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:
XML Gateway system administrator's e-mail address is defined in the ECX: System Administrator Email Address profile option
The Trading Partner contact e-mail address is defined in the Trading Partner form.
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 (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 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:
Check for response from the system administrator and issue time-out if no response received (node 2).
Execute retry function (node 3) if the system administrator wants to retry the failed outbound process. The retry process resumes from the point of failure. Continue retry function until error is resolved or failed process is aborted.
Execute abort function (node 4) if the system administrator wants to abort the failed outbound process.
Resolve error and end process (node 5)
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 following is a description of each Notification supported by the XML Gateway Error Processing Item Type:
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.
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.
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.
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.
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.
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.
Several functions are provided in the XML Gateway Error Processing Item Type to support the error handling process.
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. |
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. |
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 Retries profile option.
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.
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.
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.
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.
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. |
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. |
The XML Gateway Error Processing Item Type supports the following event activities:
Message Delivery Error
Receive Error
Receive Send Notification Event
Receive the inbound subscription error
Receive the inbound subscription processing error
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.
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.
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.
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.
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.
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.
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.
Below is a description of each message template. The message template is displayed in the Body tab and Text Body subtab.
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.
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.
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.
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.
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.
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:
Event Key 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.
Attribute Name | Attribute Description |
---|---|
Event Key | Event Key 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. |
ECX Transaction Type | This is the Transaction Type defined in the XML Gateway Define Transactions form. |
ECX 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. |
ECX Error Message | This is the error message text describing the error detected. |
ECX Error Type | This is the error type code. The valid values are:
|
ECX Return Code | This is the return status code. The valid values are:
|
ECX Message Standard | Message format standard (such as OAG) as defined in the Define Transactions form. |
ECX TP Header ID | Trading Partner name. |
ECX Message Type | Message Type, which is XML. |
ECX Logfile | If a log file is created, the name and location. |
ECX Status | The status of the transaction. |
ECX Time Stamp | The date the log file was created. |
ECX Transaction Subtype | This is the Transaction Subtype defined in the XML Gateway Define Transactions form. |
ECX Party ID | This is the unique identifier 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 the XML Gateway Define Transactions form. |
ECX Internal Control Number | The Internal Control Number is a system-generated number that uniquely identifies the message being processed. |
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. |
ECX Party Admin Email | System Administrator as defined in the Trading Partner Setup window. |
ECX Protocol Address | Protocol address used (for example, SMTP, HTTP, HTTPS). |
ECX Attribute 1 | Optional variable as defined in the message map. |
ECX Attribute 2 | Optional variable as defined in the message map. |
ECX Attribute 3 | Optional variable as defined in the message map. |
ECX Attribute 4 | Optional variable as defined in the message map. |
ECX Attribute 5 | Optional variable as defined in the message map. |
ECX Trigger ID | Unique number given to each event being raised. |
ECX Trading Partner Role | The e-mail address from the Trading Partner Setup window that is returned by the Get Trading Partner Role function. |
ECX Protocol Type | Transmission protocol as defined in the Setup Trading Partner window. |
The XML Gateway Error Processing Item Type supports several lookup types for the error handling processes.
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:
Abort
Abort the failed inbound process.
Reprocess
Reprocess the failed inbound process.
The ECX Outbound Error Actions lookups is used by the Default Error Process. The valid value is as follows:
Abort
Abort the failed outbound process
The retry function is supported by the Default Error Process.
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:
Generate Error
The error was detected during the message creation process as opposed to the message delivery process.
Send Error
The error was detected during the message delivery process as opposed to the message creation process.
Trading Partner Setup Error
The error was based on incorrect Trading Partner setup. Correct the erroneous set up before proceeding further.
ECX Resend Actions are lookups used by the XML Gateway Error Process. The valid values are as follows:
Ignore
Resend
Inbound messages that are prebuilt and delivered by Oracle E-Business Suite application modules are delivered with the following:
Message map containing an XML Gateway Procedure Call action as the last activity. This activity sets event details to indicate that XML Gateway has successfully processed the inbound message.
Seeded event subscription to consume the business event raised in the message map.
The event subscription is seeded as an enabled subscription. You can disable the event subscription if necessary.
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.
Use the Workflow Administrator to configure the seeded event subscription for the prebuilt inbound message if necessary.
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.
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.
Outbound messages that are prebuilt and delivered by Oracle E-Business Suite application modules are delivered with the following:
Calls in the application module to raise a business event to indicate when something of interest has occurred. This includes event points indicating when a document was created, changed, confirmed, or deleted.
Seeded event subscription using the XML Gateway or Workflow Default Rule Function to consume all the business events raised in the application module.
The event subscription is seeded as an enabled subscription. You can disable the event subscription if necessary.
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.
Use the Workflow Administrator to configure the seeded event subscription for the prebuilt outbound message if necessary.
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.
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.
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.
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.
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.
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.
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.
The XML Gateway Standard Item Type provides function activities to support A2A integration requirements. Listed below are the options for inbound and outbound transactions.
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.
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.
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:
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.
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.
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.
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.
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.
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.
Use the Worklist window, Oracle Workflow User's Guide to view and respond to notifications awaiting your attention.
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:
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 | 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.
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.
If the profile value is set to 'Y' (default), then all XML Gateway data along with workflow data will be purged.
If the profile value is set to 'N', then XML Gateway data will not be purged with workflow data, but only workflow data will be purged.
For more information on 'ECX: Purge ECX data with WF' profile option, see Define System Profile Options.
Note: If you are using the version of Oracle Workflow embedded in Oracle E-Business Suite and you have implemented Oracle Applications Manager, you can use Oracle Workflow Manager to submit and manage the Purge Obsolete Workflow Runtime Data concurrent program. For more information, see the Oracle Applications Manager online help.
Identified below are several Oracle Workflow Administrator windows to help monitor your Workflow processes:
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 this feature, see the Oracle E-Business Suite System Administrator's Guide - Configuration.
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.
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.
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.
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.
Following are the guidelines for developing outbound messages:
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.
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.
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.
The guidelines for developing inbound messages are as follows:
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.
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.
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.
The following are common implementation questions:
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.
Is the combination of the Generate XML Document and Send Document function activity valid?
Same as answer 1.
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.
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.
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:
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:
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 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.
User Event Defined
The XML message generated by the XML Gateway is enqueued onto the ECX_OUTBOUND queue. The messaging system (such as OTA or webMethods) dequeues the message from the ECX_OUTBOUND queue and attempts to deliver the message to the Trading Partner. Any user-defined events (defined in the Workflow Send event) will be raised and corresponding event subscriptions will be executed.
The message delivery status is returned regardless of success or failure. If the delivery fails, the Workflow Default Error Process is executed, allowing the System Administrator to retry or abort the process.
No User Event Defined
The XML message generated by the XML Gateway is enqueued onto the ECX_OUTBOUND queue. The messaging system (such as OTA or webMethods) dequeues the message from the ECX_OUTBOUND queue and attempts to deliver the message to the Trading Partner. The delivery status is returned regardless of success or failure. If the delivery fails, the Workflow Default Error Process is executed, allowing the System Administrator to retry or abort the process.
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.
User Event Defined
The XML message generated by the XML Gateway is enqueued onto the ECX_OUTBOUND queue. The messaging system (such as OTA or webMethods) dequeues the message from the ECX_OUTBOUND queue and attempts to deliver the message to the Trading Partner. Any user-defined events (defined in the Workflow Send event) will be raised and corresponding event subscriptions will be executed.
If the delivery fails, the apps.ecx.processing.message.callback event is raised. The corresponding event subscription for the FYI_MESSAGE_DELIVERY_ERROR process is executed allowing the System Administrator to resend or ignore the message notification.
No User Event Defined
The XML message generated by the XML Gateway is enqueued onto the ECX_OUTBOUND queue. The messaging system (such as OTA or webMethods) dequeues the message from the ECX_OUTBOUND queue and attempts to deliver the message to the Trading Partner.
If the delivery fails, the apps.ecx.processing.message.callback event is raised. The corresponding event subscription for the FYI_MESSAGE_DELIVERY_ERROR process is executed allowing the System Administrator to resend or ignore the message notification.
For more details, see XML Gateway Error Processing Item Type.
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.