The map analysis process for inbound messages consists of the following steps:
Compare DTD (source) to Application Open Interface tables (target)
Add XML Gateway required Actions
Add XML Gateway optional Actions
Identify source and target document levels
Use the following table as a checklist to track your progress when analyzing an inbound message. Details of each step are provided in the following sections. Use the "Completed" column to enter completion data or to check off the step when completed.
| Step | Completed | Description |
|---|---|---|
| 1 | CREATE WORKSHEET: Create a worksheet to identify all data. | |
| 2 | SET UP SOURCE: Get the DTD (source) for the required message or use a production XML message. | |
| 3 | SET UP TARGET: Populate the target column of the worksheet with the Application Open Interface table definitions or Application API parameter list. | |
| 3A | Identify the required Application Open Interface (target) table columns or Application API parameters. | |
| 4 | RELATE SOURCE ELEMENT TO TARGET ELEMENT: For each Application Open Interface (target) table column, identify the DTD (source) element to map from. | |
| 4A | Identify where code conversion is needed. | |
| 4B | Identify Derivation Rules | |
| 4C | Identify Defaulting Rules | |
| 5 | CONVERT FROM OAG FORMAT TO ORACLE FORMAT: For each OAG DTD (source) DATETIME, AMOUNT, OPERAMT, or QUANTITY element, identify the Application Open Interface (target) column or Application API parameter to map to. 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 Siblings nodes/elements if needed. | |
| 7 | REVIEW DTD USERAREA: Review all OAG's USERAREA definitions and determine whether they should be mapped to the Application Open Interface table column or Application API parameter. Other XML standards may have similar elements. | |
| 8 | RESOLVE DATA GAPS: The DTD (source) elements for as many Application Open Interface (target) table columns or Application API parameters have been identified, and identify any data gaps. | |
| 9 | OPTIONAL Actions: For Application products that use Application Open Interface tables to stage incoming data and utilize an Application Open Interface API to validate the staged data Use Insert to Database Table action to insert data into Application Open Interface tables Use Procedure Call action to execute Application Open Interface API For Application products that use application APIs that combine staging tables and the validation API. Use Procedure Call action and map source (DTD) data to the Application API parameter list. | |
| 10 | REQUIRED ACTION: Add root-level, post-process action to raise business event indicating inbound process is complete. Add Procedure Call action for ECX_STANDARD.setEventDetails. See setEventDetails in the API Appendix. | |
| 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 |
|---|---|---|---|---|---|---|
Get the DTD (source) for the required message or use a production XML message.
Include the the Field Identifier and Segment Descriptions, from the Open Applications Group Integration Specification Appendixes C and D, respectively.
Note: You may use third party software to expand the DTD or use a production XML message.
Populate the target column of the worksheet with the Application Open Interface table definitions or Application API parameter list.
Note: You may use third party software to expand the DTD or use a production XML message.
Identify the required Application Open Interface (target) table columns or Application API parameter list as follows:
NOT NULL columns defined in the data model
Application Open Interface API or Application API code to enforce required columns that are not defined as NOT NULL
Open Interface or Application API documentation (for the product) identifying the required columns and associated derivation and defaulting rules.
For each Application Open Interface (target) table column, identify the DTD (source) element to map from.
Note: Use the Open Applications Group Integration Specification Appendix C (Field Identifier Descriptions) and D (Segment Descriptions) to get detailed descriptions of each element identified on the DTD.
If the target column is for an internal ID, you must resolve this using a derivation or defaulting rule as outlined in steps 4B and 4C below. The sender cannot send an ID as they do not know what the valid internal IDs are. XML Gateway provides derivation actions to derive address and organization ID.
DTD attributes (lowercase tags) are not stored in the Oracle E-Business Suite, and therefore are not mapped. However, the value of the attribute can be used to determine the exact Application Open Interface table column or Application API parameter to map to.
If the Application Open Interface (target) table column can be sourced from a DTD (source) element, determine if the DTD (source) element value requires code conversion so the resulting value is meaningful to the Oracle E-Business Suite.
If code conversion is required, identify the code category from the list in Appendix B.
Identify the from/to value to determine if the required values are available in the database you are using. If the values are not available, they must be added.
If the Application Open Interface (target) table column cannot be sourced from a DTD (source) element, determine if it can be derived. Refer to your product's Application Open Interface documentation for any predefined derivation rules. If a derivation rule is defined, make sure the incoming message provides the data to support the derivation rule because the Application Open Interface API will use the data to derive the value for the target column. Make a notation of the derivation rule on your worksheet so that you can verify this during unit testing.
If no derivation rule is defined, you can define one. The derivation rule can be based on several DTD elements or some default values. Make a notation of the derivation rule on your worksheet. Make a notation that an Action may be required.
Refer to Transaction Map - Actions for a list of XML Gateway supported Actions.
Determine if the derivation rule (element or literal) requires code conversion for the trading partner. If code conversion is required, identify the code category from the list in Appendix B.
Identify the from/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 Application Open Interface (target) table column cannot be sourced from a DTD (source) element or derived, determine if it can be defaulted. Refer to your product's Application Open Interface documentation for any predefined defaulting rules. If a defaulting rule is defined, make sure the incoming message provides the data to support the defaulting rule. The Application Open Interface API will use the data as the default value for the target column. Make a notation of the defaulting rule on your worksheet so that you can verify this during unit testing.
If no defaulting rule is defined, you can define one. The default value may be set directly in the target definition using the Message Designer or as an XML Gateway Action if the default value is based on a condition. See Appendix C - XML Gateway Supported Actions.
Determine if the defaulting rule (element or literal) requires code conversion for the trading partner. If code conversion is required, identify the code category from the list in Appendix B.
Identify the from/to value to determine if the required values are available in the database. If the values are not available, they must be added.
For each DTD (source) DATETIME, AMOUNT, OPERAMT, or QUANTITY element, identify the Application Open Interface (target) column or Application API parameter to map to.
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 OAG representation to the Oracle representation. Make a notation that this column requires an Action for "Convert from OAG" that will be defined using the Message Designer.
For the DATETIME element, identify the Application Open Interface (target) table column for date.
Values for attributes "qualifier," "type," and "index" are not mapped because the meaning is implied in the Application Open Interface table column for date.
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 the Application Open Interface (target) table columns for currency code and debit/credit flag if available. The XML Gateway "Convert from OAG" Action can be defined to store the OAG currency code and debit/credit flag in the columns identified, or ignored if the columns are not available.
Values for attributes "qualifier," "type," and "index" are not mapped because the meaning is implied in the Application Open Interface table column.
Values for NUMOFDEC and SIGN are implied in the Oracle representation of the amount value. The values are not mapped unless your application supports it. If so, you will need to map them using the Message Designer.
Note: OAG AMOUNT is made up of the following elements and attributes: qualifier, type, index, VALUE, NUMOFDEC, SIGN, CURRENCY, DRCR.
For the OPERAMT element, identify the Application Open Interface (target) table columns for the currency code and unit of measure code if available. The XML Gateway "Convert from OAG" Action can be defined to store the OAG currency code and unit of measure code in the columns identified, or ignored if the columns are not available.
Values for attributes "qualifier" and "type" are not mapped because the meaning is implied in the Application Open Interface table column.
Values for NUMOFDEC, SIGN, UOMVALUE, and UOMNUMDEC are implied in the Oracle representation of the operating amount value. The values are not mapped unless your application supports it. If so, you will need to map them using the Message Designer.
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 the Application Open Interface (target) table column for the unit of measure code if available. The XML Gateway "Convert from OAG" Action can be defined to store the OAG unit of measure code in the column identified, or ignored if the column is not available.
The value for the "qualifier" attribute is not mapped because the meaning is implied in the Application Open Interface table column.
Values for NUMOFDEC and SIGN are implied in the Oracle representation of the quantity value. The values are not mapped unless your application supports it. If so, you will need to map them using the Message Designer.
Note: OAG QUANTITY is made up of the following attributes and elements: qualifier, VALUE, NUMOFDEC, SIGN, UOM.
A DTD defines a single occurrence of an element, but additional occurrences can be added during message implementation to accommodate the business data. Map the duplicate node to the appropriate Application Open Interface table columns.
An example is the DTD element for PARTNER used to identify the trading party. If the Application Open Interface requires a SHIP-TO, BILL-TO, and REMIT-TO, then two PARTNER sibling nodes (same hierarchy level) were added to the original DTD to accommodate the BILL-TO and REMIT-TO. Map these entities to the appropriate Application Open Interface table columns.
Consider that the original DTD may have been extended to support additional data required by the message. Review all USERAREA definitions and determine whether they should be mapped to the Application Open Interface table column or to an application API parameter.
For outbound messages, all application flexfields were mapped to USERAREA fields. If the outbound message is being processed as an inbound message to another Oracle E-Business Suite application module, the values may be meaningful. If so, they must be mapped to Application Open Interface table columns or Application API parameters.
At this point, you have identified DTD (source) elements for as many Application Open Interface (target) table columns or Application API parameters as possible. Any required Application Open Interface (target) table column or Application API parameter that has not been mapped represents a data gap.
If the required column is an internal ID, you must resolve this using a derivation or defaulting rule as described in Steps 4B and 4C, or use the Derive Address ID or Derive Parent ID actions.
Consider resolving the data gaps by extending the DTD to include the required data. You can extend the DTD by adding sibling (same hierarchy level) or child (next level hierarchy) USERAREA elements or by adding new elements to an existing USERAREA. Refer to How to Extend DTDs for information on how to define these.
Consider creating new Application Open Interface tables and associated API. If this is a valid option, create and load the new table definitions into the database schema and create the message map.
Note: The only updates allowed for a DTD are to the USERAREA. Any other changes will invalidate the DTD.
For Application products that use Application Open Interface tables to stage incoming data and utilize an Application Open Interface API to validate the staged data:
Use the Insert to Database Table action to insert data into Application Open Interface tables.
Use the Procedure Call action to execute Application Open Interface API.
For Application products that use application APIs that combine the staging tables and the validation API:
Use the Procedure Call action and map source (DTD) data to the Application API parameter list. Refer to How to Map to an API for additional instructions.
Add root-level, post-process action to raise business event indicating inbound process is complete.
Add Procedure Call action for ECX_STANDARD.setEventDetails. See setEventDetails in the API Appendix.