Professional Documents
Culture Documents
(An Oracle White Paper, Apr 2013) by Srecko Bartl, Sarath Nimmagadda and Vaibhav Kapoor Edited by - Anusha Parava and Radha Batchu
Document Structure .............................................................................................................. 3 Intended Users ..................................................................................................................... 3 Documentation References ................................................................................................... 3 Introduction.......................................................................................................................... 4 The Oracle Workflow Business Event System ............................................................................ 4 Business Events in Oracle Order Management ............................................................................ 5 Business Event oracle.apps.ont.oi.xml_int.status ...................................... 6 Set-Up Considerations ........................................................................................................... 6 Parameter Details .................................................................................................................. 6 When raised due to Processing Constraint setup ......................................................... 7 When raised due to Workflow Sub-process setup ....................................................... 8 Business Event oracle.apps.ont.genesis.outbound.update .......................8 Set-Up Considerations ........................................................................................................... 8 Parameter Details .................................................................................................................. 9 Business Event oracle.apps.ont.oip.processfailure.update ................. 10 Set-Up Considerations .......................................................................................................... 10 Parameter Details ................................................................................................................. 10 Business Event oracle.apps.ont.oip.statuschange.update...................... 11 Set-Up Considerations .......................................................................................................... 11 Parameter Details ................................................................................................................. 11 Business Event oracle.apps.ont.hold.action.................................................. 12 Set-Up Considerations .......................................................................................................... 12 Parameter Details ................................................................................................................. 12 Use Case A Fully Functional Custom Extension ............................................................. 13 Requirement ....................................................................................................................... 13 Setup ................................................................................................................................. 13 Conclusion ...................................................................................................................... 24
Page 2 of 24
Document Structure
This document starts with a brief introduction of Workflow Business Events as available with Oracle e-Business Suite Technology Stack. Next, the business events supported out of the box by Oracle Order Management are described. The salient parameters associated with these business events are explained. Subsequent sections of the white paper elaborate the set up to be done by Oracle Order Management Administrator/Super User, to enable Order Management to emit business events with relevant payload (of event parameter values). Towards the final phases of the document, an illustrated example delineating the integration process (defining subscriptions to the business events) is presented in Use Case A Fully Functional Custom Extension.
Intended Users
Oracle Applications System Administrators and Third-Party System Integrators find the information contained in this document particularly useful.
Documentation R eferences
O Oracle Applications - Order Management Open Interfaces, API & Electronic Messaging Guide, part # B14446-01, Chapter 7 (Electronic Messaging Technical Information) and Chapter 8 (Electronic Messaging Implementation Considerations). Oracle Workflow Administrators Guide, API Reference Guide, and Developers Guide.
Page 3 of 24
Introduction
The Oracle Workflow Business Event System The Oracle Workflow Business Event System is an application service that leverages the Oracle Advanced Queuing (AQ) infrastructure to communicate business events between application systems. The Business Event System consists of the Event Manager and workflow process event activities. The Event Manager contains a registry of business events, systems, named communication agents within those systems, and subscriptions indicating that an event is significant to a particular system. Events can be raised locally or received from an external system or the local system through AQ. When an event occurs, the subscribing code gets executed. Subscriptions can include the following types of processing: O O O Executing custom code on the event information Sending event information to a workflow process Sending event information to other queues or systems.
The uses of Business Event System include: 1. 2. 3. 4. 5. System integration messaging hubs Distributed applications messaging Message-based system integration Business event based workflow processes Customization of packaged applications in a non-invasive manner
Page 4 of 24
Business Events in Oracle Order Management Subject to the completion of certain set-up steps, Oracle Order Management raises Business Events at salient points during the processing of a given sales order. This allows for the use: Customization of Oracle Order Management in a non-invasive manner simply by registering suitable subscriptions to the relevant Business Events. The following table displays a quick summary of Business Events raised by Order Management: Activity of Interest in Order Processing Processing of Electronic Messages (XML, EDI transactions) and Order Import. Create a sales order (line); Modify a sales order (line); and Cancel a sales order (line). Status Change Supported by Automatically by seeded workflows. Defining a processing constraint of type:
Raise Integration Event.
oracle.apps.ont.oi.xml_int.status
Utilizing the seeded workflow subprocess Raise Show Sales Order Event Sub Process (of workflow item type OESO i.e., OM Show Sales Order) For sales orders created from order sources marked as AIA Enabled When the profile OM: Raise Status Change Business Event is set to Yes When the profile OM: Raise Status Change Business Event is set to Yes For all the sales orders independent of Order source. i.e AIA& Non AIA enabled.
oracle.apps.ont.oi.xml_int.status
Apply a hold; Release a hold; some flow status changes Process Failure
oracle.apps.ont.genesis.outbound.update
Oracle.apps.ont.oip.processfailure.update
Status Change
Oracle.apps.ont.oip.statuschange.update
oracle.apps.ont.hold.action
Oracle.apps.ont.oi.xml_int.status is available in release 11i and up. Oracle.apps.ont.genesis.outbound.update is available in 11i10 and R12.1 and up, but not in R12.0.x. Business Events in Oracle Order Management Page 5 of 24
Oracle.apps.ont.oip.processfailure.update is available on top of 12.1.3 and in 12.2.2, but not in R12.0.x, 11i. Oracle.apps.ont.oip.statuschange.update is available on top of 12.1.3 and in 12.2.2, but not in R12.0.x, 11i. Oracle.apps.ont.hold.action is available on top of 12.1.3 and in 12.2.2, but not in R12.0.x and 11i.
Parameter Description
Unique document number generated by XML Gateway for inbound messages.
Comments Overloaded to provide a unique id for EDI inbounds and Order Import as well.
XMLG_MESSAGE_ID XMLG_INTERNAL_TXN_TYPE
Unique message id generated by XML gateway for outbound messages. Typically 'ONT' except for Confirm BOD which is owned by 'ECX'. Identifies XML transaction Type.
XMLG_INTERNAL_TXN_SUB TYPE
Overloaded to contain EDI and Order Import transaction type, namely '850', '860', '855', '865', 'GENERIC' Overloaded to provide a unique identifier for outbound EDI transactions.
DOCUMENT_DIRECTION XMLG_DOCUMENT_ID
'C' TP Party ID TP Party Site ID Sales Order Number Organization ID Purchase Order Number Change Sequence 'ACTIVE', 'SUCCESS', 'ERROR'
Page 6 of 24
FND MESSAGE detailing what has occurred. Workflow Info for XML/EDI Processing Workflow Info for XML/EDI Processing. Order Source Customer ID Order Type ID Processing Concurrent Request ID Code to identify why this event was raised. Sample values include 'INBOUND_IFACE', 'OUTBOUND_SENT'. Comma delimited list of product short names of the intended subscribers e.g., 'ONT, CLN. 'SUCCESS', 'ERROR' 'Y' for 3A8 Change PO Response documents Order Header identifier Only applicable for events raised via Processing Constraints.
SUBSCRIBER_LIST
It may be noted that not every parameter will be populated in all cases, as described in subsequent sections. When raised due to Processing Constraint setup The following table contains a Y if a particular parameter is populated for Processing Constraint based Event Raise: Parameter Name
DOCUMENT_NO ORG_ID PARTNER_DOCUMENT_NO DOCUMENT_REVISION_NO ORDER_SOURCE_ID SOLD_TO_ORG_ID HEADER_ID SUBSCRIBER_LIST LINE_IDS
Note: Regarding the colon-delimited string of Line Ids for line-level triggering: if the values populating the line_id string exceed 2000 characters, the relevant business event will be raised multiple times. The Raise Integration Event operation in the Processing Constraints window will not fail because the line_id string can accommodate more characters.
Page 7 of 24
When raised due to Workflow Sub-process setup The following table contains a Y if a particular parameter is populated for workflow sub-process based event raise (using the Raise Show Sales Order Event Sub Process):
Parameter Name
DOCUMENT_NO ORG_ID PARTNER_DOCUMENT_NO DOCUMENT_REVISION_NO ORDER_SOURCE_ID SOLD_TO_ORG_ID ORDER_TYPE_ID HEADER_ID SUBSCRIBER_LIST LINE_IDS
Note: Because the event passes no useful line id as its parameter, Raise Show Sales Order Event Sub Process is only suitable to raise events from header-level (OM Order Header) workflow processes. To raise events from a line-level (OM Order Line) workflow process, you can add Event nodes to its definition, with Event Action = Raise, the desired Event Name, and with line id as one of the parameters. Standard activity Set Event Property can be used to set the parameter value(s) as desired. For more details on this topic, see Oracle Workflow Developers Guide.
Page 8 of 24
This event is raised on such orders after they are booked and: 1. 2. 3. 4. A hold is applied. A hold is released. Flow status code on the order header/line is changed to Supply Eligible, Awaiting Shipping, Shipped, Fulfilled or Closed. Schedule Ship/Arrival Date is changed.
Parameter Details Parameter Name HEADER_ID Parameter Description Header ID (reference to OE_ORDER_HEADERS_ALL) of the order/line that underwent a change, causing the event to be raised. Line ID (reference to OE_ORDER_LINES_ALL) of the order line that underwent a change, causing the event to be raised. Comments Always populated.
LINE_ID
Populated when the action performed is on a specific order line. A null value indicates, the event is the result of an action that got performed on the order level. For internal use. For internal use. APPLY a hold has been applied. RELEASE a hold has been released. LINE_STATUS Flow status code has changed. SHIP_DT_CHG Schedule Ship date has been changed. ARVL_DT_CHG Schedule Arrival date has been changed.
An auto-generated identifier. An auto-generated identifier. Indicates the type of change the order/line is being subjected to.
HOLD_SOURCE_ID
Hold Source ID (reference to OE_ORDER_HOLDS_ALL) which caused the hold to be applied on the order header. Hold ID (reference to OE_ORDER_HOLDS).
Populated only when CHANGE_TYPE is APPLY or RELEASE. Populated only when CHANGE_TYPE is APPLY or RELEASE. Page 9 of 24
ORDER_HOLD_ID
HEADER_ID
STATUS_CODE
PROCESS_NAME
BOOK_ORDER
Page 10 of 24
LINE_ID
STATUS_CODE
ACCEPTANCE_STATUS
ACCEPTED_BY
REJECTED BY
REJECTION_REASON
Parameter Details The event oracle.apps.ont.hold.action is raised with the following parameters: Parameter Name HEADER_ID Parameter Description Header ID (reference to OE ORDER HEADERS ALL) of the order/line that underwent a change, causing the event to be raised. Line ID (reference to OE ORDER LINES ALL) of the order line that underwent a change, causing the event to be raised. Comments Always populated.
LINE_ID
Populated when the action performed is on a specific order line. A null value indicates, the event is the result of an action that got performed on the order level. APPLY a hold has been applied. RELEASE a hold has been released.
CHANGE_TYPE
HOLD_SOURCE_ID
ORDER_HOLD_ID
Hold Source ID (reference to OE ORDER HOLDS ALL) which caused the hold to be applied on the order header. Hold ID (reference to OE ORDER HOLDS).
Populated only when CHANGE TYPE is APPLY or RELEASE. Populated only when CHANGE TYPE is APPLY or RELEASE. Populated only when CHANGE_TYPE is RELEASE.
HOLD_RELEASE_ID
Hold Release ID (reference to OE_HOLD_RELEASES) which caused the hold to be released from the Order.
Page 12 of 24
CREATE TABLE XX_OM_BES_TBL ( ORG_ID , ORDER_SOURCE_ID , ORDER_NUMBER , HEADER_ID , CUSTOMER_ID , LINE_NUMBER , BOOKED_FLAG , LINE_ID , FLOW_STATUS_CODE , REQUEST_DATE , CREATION_DATE );
NUMBER NUMBER NUMBER NUMBER NUMBER NUMBER VARCHAR2(1) NUMBER VARCHAR2(30) DATE DATE
The tables purpose is to hold some basic order auditing information. 2. Create another custom table, XX_OM_BES_ERRORS:
CREATE TABLE XX_OM_BES_ERRORS ( ITEM_TYPE VARCHAR2(8), ITEM_KEY VARCHAR2(240), SQLERRNUMBER NUMBER, SQLERRTEXT VARCHAR2(2000), LOGTIME DATE);
The purpose of this table is to store any unexpected errors raised during the logging process.
Page 13 of 24
API XX_OM_BES_PKG_WF.Update_BES_InfoToCustTable() contains sample code to populate the audit table XX_OM_BES_TBL.
/****************************************************************************** ** ** Body of package XX_OM_BES_PKG_WF ** ** NOTES ** This is created for test purpose ** *****************************************************************************/ CREATE OR REPLACE PACKAGE BODY XX_OM_BES_PKG_WF AS PROCEDURE Update_BES_InfoToCustTable ( p_itemtype IN VARCHAR2, p_itemkey IN VARCHAR2, p_actid IN NUMBER, p_funcmode IN VARCHAR2, p_x_result IN OUT NOCOPY VARCHAR2) IS l_order_source_id NUMBER; l_sold_to_org_id NUMBER; l_order_number NUMBER; l_org_id NUMBER; l_result VARCHAR2(30); l_header_id NUMBER; l_line_id NUMBER; l_pos NUMBER; l_line_number varchar2(100); l_request_date DATE; l_open_flag VARCHAR2(1); l_flow_status_code VARCHAR2(30); l_line_ids VARCHAR2(4000); l_sqlcode number; l_sqlerrm VARCHAR2(2000);
Page 14 of 24
CURSOR lines_info (c_line_id NUMBER) IS SELECT line_id, booked_flag, request_date, flow_status_code , line_number||'.'||shipment_number AS Line_Num , (SELECT order_number FROM oe_order_headers_all WHERE header_id = l.header_id) AS Order_Number FROM oe_order_lines_all l WHERE line_id = c_line_id; cursor SELECT FROM WHERE BEGIN l_org_id := wf_engine.GetItemAttrNumber ( p_itemtype, p_itemkey, 'ORG_ID'); l_order_source_id := wf_engine.GetItemAttrNumber( p_itemtype, p_itemkey, 'ORDER_SOURCE_ID'); l_header_id := wf_engine.GetItemAttrNumber( p_itemtype, p_itemkey, 'HEADER_ID'); l_sold_to_org_id := wf_engine.GetItemAttrNumber( p_itemtype, p_itemkey, 'SOLD_TO_ORG_ID'); l_line_ids := wf_engine.GetItemAttrText( p_itemtype, p_itemkey, 'LINE_IDS'); IF l_line_ids = 'ALL' THEN event was raised because order was booked OPEN header_info (l_header_id); FETCH header_info INTO l_booked_flag, l_request_date, l_flow_status_code, l_order_number; CLOSE header_info; INSERT INTO XX_OM_BES_TBL ( ORG_ID , ORDER_SOURCE_ID , ORDER_NUMBER , HEADER_ID , CUSTOMER_ID , BOOKED_FLAG , REQUEST_DATE , FLOW_STATUS_CODE , CREATION_DATE ) VALUES ( l_org_id , l_order_source_id , l_order_number , l_header_id , l_sold_to_org_id , l_booked_flag , l_request_date , l_flow_status_code , SYSDATE ); ELSE event was raised because line request dates were changed WHILE l_line_ids IS NOT NULL LOOP -- decode colon delimited line id list l_pos := INSTR(l_line_ids, ':',1, 1); IF l_pos = 0 THEN l_line_id := l_line_ids; l_line_ids := NULL; ELSE l_line_id := SUBSTR(l_line_ids, 1, l_pos - 1); l_line_ids := SUBSTR(l_line_ids, l_pos + 1); END IF; OPEN lines_info (l_line_id); FETCH lines_info INTO l_line_id, l_booked_flag, l_request_date, l_flow_status_code, l_line_number, l_order_number; CLOSE lines_info; header_info (c_header_id NUMBER) IS booked_flag, request_date, flow_status_code, order_number oe_order_headers_all l header_id = c_header_id;
Page 15 of 24
INSERT INTO XX_OM_BES_TBL ( ORG_ID , ORDER_SOURCE_ID , ORDER_NUMBER , HEADER_ID , CUSTOMER_ID , LINE_NUMBER , BOOKED_FLAG , LINE_ID , REQUEST_DATE , FLOW_STATUS_CODE , CREATION_DATE ) VALUES ( l_org_id , l_order_source_id , l_order_number , l_header_id , l_sold_to_org_id , l_line_number , l_booked_flag , l_line_id , l_request_date , l_flow_status_code , SYSDATE ); END LOOP; END IF; -- line_ids = 'ALL'
p_x_result := 'COMPLETE:COMPLETE'; EXCEPTION WHEN OTHERS THEN l_sqlcode := sqlcode; l_sqlerrm := SUBSTR(sqlerrm, 1, 2000); INSERT INTO XX_OM_BES_ERRORS ( item_type, item_key, sqlerrnumber, sqlerrtext, logtime) VALUES ( p_itemtype, p_itemkey, l_sqlcode, l_sqlerrm, sysdate); p_x_result := 'COMPLETE:ERROR'; END Update_BES_InfoToCustTable; END XX_OM_BES_PKG_WF; / COMMIT; EXIT;
Page 16 of 24
4. Create a custom workflow. 4.1 New Item Type = Custom OM Business Event (Internal Name = XX_OMBES).
4.2 Create an event of Event Action = Receive and name = Custom Receive Event (Internal Name = XX_BES_RECEIVE_EVENT). Set the Event filter = oracle.apps.ont.oi.xml_int.status
Page 17 of 24
4.3 Create a new function Write Details to Custom table (Internal Name = XX_BES_WRITE_DETAILS) and assign Function Name =
XX_OM_BES_PKG_WF.Update_BES_InfoToCustTable
4.4 Create a process Write Details Process (Internal Name = XX_WRITE_DETAILS) and check the Runnable checkbox
4.5 Create a process definition by assigning the receive Custom Receive Event as the start activity, and workflow standard End as end activity. Place the Write Details to Custom table function activity between the above two activities and join the transition line as shown below:
Page 18 of 24
4.6 Create following attributes to the custom item type Custom OM Business Event:
Event Name and Event Key should be of type Text, Event Message type Event, Line Ids type Text with length of 2000, and the rest type Number. 4.7 Set the Event properties under the Event Details property tab as shown below:
4.8 Create a custom subscription to event oracle.apps.ont.oi.xml_int.status by navigating to Workflow administrator responsibility > Business Events > Events tab Query for event oracle.apps.ont.oi.xml_int.status and press the create icon to create a new custom subscription to this event
Page 19 of 24
Provide the appropriate system name and Action Type = Launch Workflow along with other necessary details for creation, as shown below and click the Next button.
In the next screen, provide the custom workflow item type and process internal name. Provide the Owner Name and Tag to this event and save the changes
Page 20 of 24
5. Setup the processing constraint rule for raising the business event: Navigate to OM Super User responsibility > Setup > Rules > Security > Processing Constraints form Query for: Application = Order Management Entity = Order Line Define a new user constraint with Operation = Update Attribute = Request Date User Action = Raise Integration Event Enabled = Checked And constraint condition as: = Any Scope Validation Entity = Order Line Record Set = Line Validation Template = Booked = Checked Enabled User Message = Business event has been raised
Page 21 of 24
Save the changes. 6. Setup the value to profile OM: Electronic Message Integration Event Source' as ALL. That completes the necessary implementation & set-up for the request date change part of the requirement. Now, test the implementation done so far. Navigate to OM Super User responsibility > Orders, Returns > Quick Sales Order Enter the Operating Unit, Customer details and Order Type information. Ensure other required information to either be defaulted or enter it manually for the successful creation of the order sales order. Once done, save the changes and enter a sales order line with a certain request date. Book the sales order. Now change the request date. Upon saving the changes, business event oracle.apps.ont.oi.xml_int.status will be raised.
Once the event is raised, navigate to Workflow Administrator responsibility > Status Monitor. Query for custom item type XX_OMBES and the latest launched details of custom process XX_WRITE_DETAILS Click on view diagram button to ensure that the custom workflow, tied to custom subscription, is triggered and completed.
Page 22 of 24
Finally, check the entry to custom table XX_OM_BES_TBL. There should be a row in this table for the modified sales order line along with the new request date value and any other desired details. For the second part of the requirement, to get an entry in the audit table XX_OM_BES_TBL also when an order is booked, there is a few more setup steps required. This is because booking is a flow status change, rather than attributes change, and cannot be captured by processing constraints. Instead, well use the seeded workflow sub process Raise Show Sales Order Event Sub Process. 7. Copy and rename the seeded order header process R_STANDARD_HEADER (Order Flow Generic). Change the name to R_STANDARD_HEADER_SSO (Order Flow Generic SSO). 8. In Oracle Workflow Builder, change the definition of Order Flow Generic SSO by inserting the seeded sub process RAISE_SHOW_SO_SUB (Raise Show Sales Order Event Sub Process) from item type OESO (OM Show Sales Order) between BOOK_PROCESS_ASYNCH (Book Order, Manual) and CLOSE_HEADER_PROCESS (Book - Order, Manual):
Page 23 of 24
9. Assign workflow process Order Flow Generic SSO to an order type in OMs Transaction Types form. Now create an order with order type from step 9 and book it. This should cause a corresponding row to be created in the audit table XX_OM_BES_TBL, as well as a workflow item of type XX_OMBES, just as previously, when you tested the request date change scenario.
Conclusion
Oracle Order Management provides out-of-the-box support to raise workflow business events at salient points within the lifecycle of a sales order. By coding & registering appropriate subscriptions to the standard business events, in a very noninvasive manner, you can: O O extend the standard functionality offered by Oracle Order Management, and/or accomplish third party system integration with Oracle Order Management at various instances of interest during the sales order lifecycle.
Page 24 of 24