The steps to performing a map analysis for an outbound message are as follows:
Compare database views (source) to DTD (target)
Identify application business event trigger
Add XML Gateway required Actions to define selection criteria
Identify source and target document levels
Use the following table as a checklist to track your progress when analyzing an outbound message. Details of each step are provided in the following sections. Use the "Completed" column to check off the step as it is completed.
| Step | Completed | Description |
|---|---|---|
| 1 | CREATE WORKSHEET: Create a worksheet to identify all data. | |
| 2 | SET UP SOURCE: Create database views or get database views/table definitions (source) for the required message from the database schema. | |
| 3 | SET UP TARGET: Populate the target column of the worksheet with the DTD or production XML message in the expanded format. | |
| 3A | Identify the required DTD (target) elements. | |
| 3B | For DTD elements with "|" as the occurrence indicator, select one element from the list. Make a note of the elements not selected because these must be removed from the message map to prevent a parser violation. | |
| 4 | RELATE SOURCE ELEMENT TO TARGET ELEMENT: For each DTD (target) element, identify the database view (source) column to map from. | |
| 4A | Identify where code conversion is needed. | |
| 4B | Identify Derivation Rules | |
| 4C | Identify Defaulting Rules | |
| 4D | Identify DTD Attribute Settings | |
| 5 | CONVERT FROM ORACLE FORMAT TO OAG FORMAT: For each OAG DTD (target) DATETIME, AMOUNT, OPERAMT, or QUANTITY element, identify the database view/table (source) column to map from. Other XML standards may have similar elements. | |
| 5A | Identify and map each DATETIME element. | |
| 5B | Identify and map each AMOUNT element. | |
| 5C | Identify and map each OPERAMT element. | |
| 5D | Identify and map each QUANTITY element. | |
| 6 | ADD SIBLING FOR DUPLICATE NODES/ELEMENTS: Add Sibling nodes and elements if needed. | |
| 7 | ADD CHILD TO EXTEND DTD DEFINITION FOR FLEXFIELDS: If there is a database view or table column that you wish to map from but no DTD element is defined to support it, you can use the OAG's USERAREA. Map data to the USERAREA (or corresponding area if using other XML standards). | |
| 8 | RESOLVE DATA GAPS: Any DTD (target) elements that have not been mapped are data gaps. | |
| 9 | IDENTIFY APPLICATION BUSINESS EVENT TRIGGER: Identify the application business events to trigger message creation. | |
| 10 | IDENTIFY REQUIRED ACTIONS: All outbound messages require the following Actions to define the selection criteria. Make a notation on the worksheet to include them. Use the Append Where Clause action to bind to transaction type, transaction subtype, party ID, and party site ID to ECX_OAG_CONTROLAREA_TP_V (formerly ECX_OAG_CONTROLAREA_V see Note). If using ECX_OAG_CONTROLAREA_V, use the Append Where Clause action to bind to transaction type and transaction subtype. Use the Append Where Clause action to bind document ID to header view to select the document | |
| 11 | IDENTIFY SOURCE AND TARGET DOCUMENT LEVELS |
Create a worksheet with the following columns: Target, Required (Y/N), Source, Code Category, Derivation Rule, Default Value, and Action, as shown in the following table:
| Target | Required (Y/N) | Source | Code Category | Derivation Rule | Default Value | Action |
|---|---|---|---|---|---|---|
Create database views or get database view and table definitions (source) for the required message from the database schema. Include ECX_OAG_CONTROLAREA_V or ECX_OAG_CONTROLAREA_TP_V (see Note) view to map to the CNTROLAREA segment of the DTD.
Populate the target column of the worksheet with the DTD or production XML message in the expanded format.
Note: You may use third party software to expand the DTD or use a production XML message.
Identify the required DTD (target) elements. An element is required if there is no special symbol next to the element name.
The XML occurrence indicators are:
"+" implies one or more
"*" implies zero or more
"?" implies zero or 1
"|" implies either one or the other
"," implies all listed child elements must be used in the order shown
For DTD elements with "|" as the occurrence indicator, select one element from the list. Make a note of the elements not selected in order to remove them from the message map. They must be removed from the message map to prevent a parser violation.
For each DTD (target) element, identify the database view (source) column to map from.
Note: Use the Open Application Group's Integration Specification (available at http://www.openapplications.org) Appendix C, Field Identifier Descriptions and Appendix D, Segment Descriptions, to get detailed descriptions of each element identified on the DTD.
If the DTD (target) element can be sourced from a database view (source) column, determine if the database view column value requires code conversion.
If code conversion is required, identify the code category from the list in Appendix B.
Identify the from or to value to determine if the required values are available in the database. If the values are not available, they must be be added.
If the DTD (target) element cannot be sourced from a database view (source) column, determine if the value can be derived. If yes, identify the derivation rule. The derivation rule can be, for example, a combination of several view columns, a procedure call, or a function call. Make a notation that an XML Gateway Action may be required (for example, to get a value from another column, or to combine the values of several columns).
Refer to Appendix C. for a list of XML Gateway supported Actions.
Determine if the derived value requires code conversion. If code conversion is required, identify the code category from the list in Appendix B.
Attention: Identify the from or to value to determine if the required values are available in the database. If the values are not available, they must be added.
If the DTD (target) element cannot be sourced from a database view (source) column or derived, determine if the value can be defaulted. If yes, identify the default value. The default value can be a literal or based on a value from another database view column. Make a notation that an XML Gateway Action may be required.
The default value can be set directly in the map using the Message Designer or as an XML Gateway Action if the default value is based on a condition.
Refer to Transaction Map - Actions for a list of XML Gateway supported Actions.
Determine if the default value requires code conversion. If code conversion is required, identify the code category from the list in Appendix B.
Attention: Identify the from or to value to determine if the required values are available in the database. If the values are not available, they must to be added.
For each DTD (target) element containing attributes (lower case tags), determine the appropriate setting by checking the usage of the database view or table column and then identifying a valid setting for the attribute by reviewing the options in OAG's Appendix D that lists Segment Descriptions for the DTD element. The appropriate attribute setting is set directly in the target definition as a default value using the Message Designer.
For example, if a view column is used for creation date, the DATETIME "qualifier" attribute value of "CREATION" will be set as the default value using the Message Designer.
For each DTD (target) DATETIME, AMOUNT, OPERAMT, or QUANTITY element, identify the database view or table (source) column to map from.
Oracle E-Business Suite represents date, amount, operating amount, and quantity in a single database column. OAG represents these as a collection of data. Oracle XML Gateway provides an Action to convert the Oracle representation to the OAG representation. Make a notation that this column requires an Action for "Convert to OAG" that will be defined using the Message Designer.
For the DATETIME element, identify the database view or table (source) column for the date.
Follow Step 4D to set the "qualifier," "type," and "index" attributes
All other OAG fields are set by the "Convert to OAG" Action based on the date value.
TIMEZONE is defaulted to Greenwich Mean Time (GMT).
Note: OAG DATETIME is made up of the following attributes and elements: qualifier, type, index, YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, SUBSECOND, TIMEZONE.
For the AMOUNT element, identify database view or table (source) columns for currency code and debit/credit flag if available. The XML Gateway "Convert to OAG" Action can be defined to use the view or table column values or default to OAG recommended values if the view or table columns are not available.
Follow Step 4D to set the "qualifier," "type," and "index" attributes.
The OAG fields for NUMOFDEC and SIGN are set by the "Convert to OAG" Action based on the amount value.
Note: OAG AMOUNT is made up of the following attributes and elements: qualifier, type, index, VALUE, NUMOFDEC, SIGN, CURRENCY, DRCR.
For the OPERAMT fields, identify database view or table (source) columns for currency and unit of measure code if available. The XML Gateway "Convert to OAG" Action can be defined to use the view or table column values or default to OAG recommended values if the view or table columns are not available.
Follow Step 4D to set the "qualifier" and "type" attributes.
The OAG fields for NUMOFDEC, SIGN, UOMVALUE, and UOMNUMDEC are set by the "Convert to OAG" Action based on the operating amount value.
Note: OAG OPERAMT is made up of the following attributes and elements: qualifier, type, VALUE, NUMOFDEC, SIGN, CURRENCY, UOMVALUE, UOMNUMDEC, UOM.
For the QUANTITY element, identify database view or table (source) column for the unit of measure code if available. The XML Gateway "Convert to OAG" Action can be defined to use the view or table column value or default to the OAG recommended value if the view or table column is not available.
Follow Step 4D to set the "qualifier" attribute.
The OAG fields for NUMOFDEC and SIGN are set by the "Convert to OAG" Action based on the quantity value.
Note: OAG QUANTITY is made up of the following attributes and elements: qualifier, VALUE, NUMOFDEC, SIGN, UOM.
A DTD defines a single occurrence of a node or element. If you have multiple occurrences from the database view or table (source) to map from, make a notation on your worksheet showing the duplicate node or element and then map the element and attributes of the duplicate node or element. Make a notation to ADD SIBLING using the Message Designer.
An example is the DTD element for PARTNER used to map SHIP-TO, BILL-TO, and REMIT-TO from the Oracle E-Business Suite. You will need to add two PARTNER sibling nodes (same hierarchy level) to map BILL-TO and REMIT-TO.
If there is a database view or table column you wish to map from but no DTD element is defined to support it, you can use the USERAREA. You can add a USERAREA as a sibling (same hierarchy level) of another USERAREA or extend an existing USERAREA by adding a child (next level of hierarchy) element and then mapping the element. Make a notation to ADD CHILD using the Message Designer.
This approach is necessary to support all the flexfields included in the database views and tables. Since we do not know which flexfields are implemented at a user's site, all flexfields must be mapped.
Refer to How to Extend DTDs for details.
Note: The only updates allowed for a DTD are to the USERAREA. Any other changes will invalidate the DTD.
At this point, you have identified database view and table (source) columns for as many DTD (target) elements as possible. Any required DTD (target) element that has not been mapped represents a data gap.
Consider resolving the data gap using an application flexfield that is included in the database view or table. If this is a valid option, you must implement the designated flexfield by defining and populating it in the Oracle E-Business Suite. Consider carefully which flexfield to implement as you do not want to overwrite a flexfield implemented by the user.
Consider resolving the data gap using an application column not included in the database view. If this is a valid option, you must modify the database view to include the application column as opposed to referencing the table and column directly. Load the modified database view into the database schema. Remember to map the field.
If neither of the above considerations resolves the data gap, then you must add functionality to your application module, create new database views, load the new views into the database schema, and then create the message map.
Identify the application business events to trigger message creation. The common trigger points are when the document is created, confirmed, updated, or deleted.
Use the Oracle Workflow Business Event System to register the business event to define the corresponding event subscription to create and send the message.
See: Integrating Oracle XML Gateway with Oracle Workflow Business Event System for details on how to register and subscribe to application business events.
All outbound messages require the following Actions to identify the selection criteria. Make a notation on your worksheet to include them.
If you are using ECX_OAG_CONTROLAREA_TP_V use the Append Where Clause action to bind transaction type, transaction subtype, party ID, and party site ID
If you are using ECX_OAG_CONTROLAREA_V use the Append Where Clause action to bind transaction type and transaction subtype
Note: The ECX_OAG_CONTROLAREA_TP_V view is an upgraded version of the ECX_OAG_CONTROLAREA_V view. Oracle XML Gateway supports both versions of the database view. The more information see the Note.
Use the Append Where Clause action to bind document ID to the header view to select the document