The Map Creation Wizard guides you through the map creation process. A series of windows are presented to create a map based on the source and target definitions.
Launch the Map Creation Wizard by selecting
(M) File > New > Transaction Map
or by clicking the Create New Map icon on the toolbar. The first window welcomes you to the wizard.
The following buttons are available for all Wizard steps:
Cancel
Exit the Wizard and cancel all completed Wizard steps.
Back
Return to the previous Wizard step.
Next
Advance to the next Wizard step. The Next button is disabled until you supply all required data for a step.
Click Next to continue. The Wizard will display the Specify a Map Name window.
Specify a unique map name. This is the name assigned to the message map you are creating. It is also the name to be used when associating a message map to a Trading Partner.
Enter a unique map name. This name is stored as the map code in the map definition file.
In addition to being unique, the name should describe the intended use of the map for easy identification. The recommended naming convention is as follows:
Product mnemonic or user ID
Transaction subtype as entered in the Define Transactions form
XML standard and version used (for example, OAG, Rosettanet, iFX)
Inbound or outbound message
Examples of map names using the recommended naming convention are:
AR_INVO_OAG70_OUT_INVOICE
This map name is used for an Oracle Receivables outbound invoice message that uses the OAG standard, version 7.0 DTD.
USER_ACK_OAG70_IN
This name represents a user-developed map for an inbound acknowledgment message that uses the OAG standard, version 7.0 DTD.
Note: You can use the File > Properties menu option to change the Map Name and Map Description as necessary.
Enter a description for the map.
Note: You can use the File > Properties menu option to change the Map Name and Map Description as necessary.
Click Next to continue. The Wizard will display the Select/Create a Source Data Definition window.
Select an existing data definition file or create a new data definition file.
Select this option to create a new data definition. The Wizard will guide you through creating your new .XGD file.
Existing definition files are stored on the file system as <filename>.XGD. Use the Browse button to view the available data definition files.
If you are defining your Source data definition and you selected...
Create a new source data definition, proceed to Specify Source/Target Data Definition Name and Type.
Select an existing Source data definition, repeat this step for your Target Data Definition.
If you are defining your Target data definition and you selected...
Create a new target data definition, proceed to Specify Source/Target Data Definition Name and Type.
Select an existing Target data definition, proceed to Map Creation Wizard Summary.
For a new data definition, enter a data definition name, description, and type.
Enter a name that describes the contents of the data definition to allow easy identification.
This name is displayed in the Transaction Map window as the root node, if you select database as the data definition type. If you select XML as the data definition type, the DTD root element is displayed in the Transaction Map window as the root node instead of the data definition name entered here.
The recommended naming convention is as follows:
Product mnemonic or User ID
Transaction subtype as entered in the Define Transactions form
XML standard and version used (for example, OAG, Rosettanet, iFX)
Database or XML data definition type
Examples of data definition names using the recommended naming convention are:
AR_INVO_OAG70_DB
This name describes an Oracle Receivables-developed outbound invoice message that uses the OAG standard, version 7.0 DTD. This data definition is for the Database data definition type intended for use as the source data definition for an outbound message.
USER_ACK_OAG70_XML
This name describes a user-developed inbound acknowledgement message that uses the OAG standard, version 7.0 DTD. This data definition is for the XML data definition type intended for use as the source data definition for an inbound message.
Use the File > Properties menu option to change the Data Definition Name as necessary.
Enter a description for the data definition.
Use the File > Properties menu option to change the Data Definition Description as necessary.
Select a data definition type from the following list of values:
Database
XML
The wizard steps to follow will vary based on the data definition type selected.
If you selected Database, proceed to Specify Source/Target Definition Database Information.
If you selected XML, proceed to Specify Source/Target XML File and Root Element.
The default database access information is displayed from the Database tab of the File > Properties menu. Enter the password and make changes to the database access information if necessary.
Note: Changes made on this screen are not copied back to the Properties file. Entries on this screen are used for the current session only.
This step does not apply if the source/target is a DTD because database access is not required.
Enter the user name for the database schema to be accessed.
Enter the password for your User Name.
Enter the connect string for the database.
Enter the host name for the database.
The default value of "1521" is displayed. Enter another valid port value (if necessary) for the database to be accessed.
Click Next to continue. The Wizard will display the Select Source/Target Tables or Views window.
If you selected a Data Definition Type of Database, you will be prompted for the database schema, database views, and tables required by the message.
All application database views are defined in the APPS schema. The associated database tables are defined in the application-specific database schema. Access to application-specific database tables must be granted by defining a synonym in the APPS schema.
For applications with database views or tables shared across multiple hierarchical levels of the data model representing the business document, a database view or table alias is required for the second and each subsequent use of the view or table. This is necessary because this wizard step deletes a database view or table from the Available Tables/Views list once it has been selected.
This step does not apply if the source/target is a DTD, because database information is not necessary.
Expand the APPS database schema tree to view all the available database tables and views.
Select the desired database views and tables from the left window, click on the right shuttle to move the selected database view or table from Available Tables/Views to Selected Tables/Views. Continue this process until you have selected all the required database views and tables for each schema selected.
Once you have selected all the database views and tables required by the message, select any special XML Gateway database views you may have defined to support the specific requirements of the XML standard you are using.
For example, select the ECX_OAG_CONTROLAREA_TP_V (formerly ECX_OAG_CONTROLAREA_V) database view to map to the OAG CNTROLAREA data type.
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 upgraded view includes new fields for USERNAME, SOURCE_TP_LOCATION_CODE, PARTY_ID, PARTY_SITE_ID, and PARTY_TYPE as well as changes to the following existing fields:
REFERENCE_ID is based on the system name, event name, and event key defined by the application business event. REFERENCE_ID was previously defaulted to "1" with recommendations to use the ECX_REFERENCE_ID sequence to get a unique number. The use of this field varies by message map.
You must add the ECX_EVENT_MESSAGE item attribute to your Workflow item type to have access to the event details.
CONFIRMATION is based on the setting defined for the Trading Partner and business document entered using the Define Trading Partners window. CONFIRMATION was previously defaulted to "0".
COMPONENT is based on the internal transaction type entered on the Define Transactions window for the business document. COMPONENT was previously based on the external transaction type.
TASK is based on the internal transaction subtype entered on the Define Transactions window for the business document. TASK was previously based on the external subtype.
TRANSACTION_SUBTYPE is based on the internal transaction subtype entered on the Define Transactions window. TRANSACTION_SUBTYPE was previously defaulted to the TRANSACTION_TYPE if no value was found in the database.
To deselect a selected database view or table, select the desired database view/table from the right window, click on the left shuttle button to move the selection from the Selected Tables/Views back to Available Tables/Views.
Click Next to continue. The Wizard will display the Select Source/Target Columns window.
This window prompts you for the columns required from each of the database views or tables selected in the previous step.
This step does not apply if the source/target is a DTD because database information is not necessary.
Expand each of the database views and tables to view all the available database view and table columns.
Select the desired database view or table column from the left window, click on the right shuttle button to move the selected database view or table column from Available Columns to Selected Columns. To move all the columns from a view or table, select the table or view and click the double right shuttle button to move all its columns from Available Columns to Selected Columns. Continue this process until all the required database view and table columns are selected.
You cannot proceed to the next wizard step until you have selected at least one column from each of the selected database views and tables. If necessary, return to the previous wizard step to deselect a database view or table and then resume the column selection process.
To deselect a selected database view or table column, highlight the desired column from the right window and click the left shuttle button to move the highlighted column from Selected Columns back to Available Columns. To deselect all the columns from a table or view, highlight the table or view name under Selected Columns and click the double left shuttle button to move all the columns back to the Available Columns area.
Click Next to continue. The Wizard will display the Specify Source/Target Levels window.
If you selected a Data Definition Type of Database, you will be prompted to identify the hierarchy of the source or target data definition. This step is necessary only if your source/target data definition contains more than one level.
A level represents a collection of data that repeats. For example, Purchase Order lines represent a level within a Purchase Order because there are multiple PO lines to a single PO.
The purpose of this step is to identify the parent and child relationships of each database view. The source hierarchy will be used to relate to the target hierarchy as part of the map creation process.
This step does not apply if the source/target is a DTD because database information is not necessary.
The available database views and tables are displayed for your selection.
This window allows you to define the parent and child relationships of the selected database views and tables along with the special database views necessary to relate the database data model to the DTD data model.
Start by identifying the parent node. For OAG, the parent node is the ECX_OAG_CONTROLAREA_TP_V view (formerly ECX_OAG_CONTROLAREA_V). Related to the parent node are sibling or child nodes.
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. For more information see the Note.
Sibling and child relationships are defined by first identifying the parent node in the Selected Tables/Views window (right). The database view or table you move from the the Available window to the Selected window will always be added as the last child of the parent node selected.
Therefore, to specify a sibling relationship to a specific node, select its parent node in the Selected Tables/Views column (right window). Next select the database view or table in the Available Tables/Views (left window) that you want to define as its sibling. Click on the right shuttle. The selected database view or table will be displayed as the last child of the parent node selected, or as a sibling to the desired node.
To specify a child relationship to a specific node, select the node in the Selected Tables/Views column (right window). Next select the database view or table in Available Tables/Views (left window) that you want to define as its child, and click on the right shuttle. The selected database view or table will be displayed as the last child of the selected parent node.
Continue this process until all available database views and tables have been moved to Selected Tables/Views.
This completes the data definition process.
If you have just finished your Source Data Definition, return to Select/Create a Source/Target Data Definition to define your Target Data Definition.
If you have just finished your Target Data Definition, proceed to Map Creation Wizard Summary.
If you selected XML as the data definition type, you will be prompted for the XML information. You can use a DTD or a production XML message as the data definition.
Enter the XML standard used.
"OAG" (Open Application Group XML Standard) is the default.
Select the DTD from the list of available DTDs presented when you click on the Browse button, or enter a specific DTD including the file path. The selected DTD and its file path are displayed.
To base the data definition on a production XML message, enter the file path and file name of the XML message.
The DTD or production XML message is used to create the definition tree for the Message Designer.
This step assumes that the required DTD and the associated external reference DTD files are available on the file system and are accessible by the Message Designer. For example, the OAG definition files are
oagis_domains.dtd
oagis_resources.dtd
oagis_fields.dtd
oagis_segments.dtd
Enter the XML root element. Open the DTD or production XML message using a browser or XML editor to determine the root element name if you do not know it.
Note: Because the representation of root element varies by XML standard, this step is required to inform the Execution Engine where to begin reading the DTD.
Use the File > Properties menu option to change the Root Element as necessary.
If you entered a DTD above, the DTD file name will display automatically.
If you entered a production XML message above, click the Browse button to select the corresponding DTD from the list of available DTDs, or enter a specific DTD if available.
The DTD file name entered is used to validate a message to ensure that it is well-formed and valid before placing an outbound message on the outbound queue or processing a message dequeued from the inbound queue.
In addition, the primary DTD and its associated definition files must be loaded into the XML Gateway repository for access by the XML Gateway Execution Engine.
Note: Refer to How to Load/Delete Message Maps and DTDs for more details.
Use the File > Properties menu option to change the DTD File Name as necessary.
Enter the subdirectory name using the following naming convention:
<application code>/xml/<standard><standards version>
Examples:
ar/xml/oag62
ap/xml/oag70
Note: Do not use a period (.) when referencing a standards version.
The combination of the runtime DTD location and the DTD file name provides a unique identifier for the DTD required.
Use the File > Properties menu option to change the Runtime Location of a DTD as necessary.
If you have just finished your Source Data Definition, return to Select/Create a Source/Target Data Definition to define your Target Data Definition.
If you have just finished your Target Data Definition, proceed to Map Creation Wizard Summary.
Click Finish to exit the Map Creation Wizard. If you wish to change any selections you have made in defining your map, use the Back button to return to the appropriate Wizard window.
Before proceeding to the level and element mapping process, the XML Gateway, in conjunction with the XML Parser, performs the following validations:
When the DOCTYPE tag is present in an XML message, verify that the DTD referenced is accurate.
Verify that the XML root element matches the DTD identified. When a production XML message is identified, verify that the root element and DTD identified match the production XML message.
Verify that external DTDs referenced by the primary DTD are available.
Check for circular DTD references. Process the first occurrence, truncate the remainder and warn user to manually add the necessary repeating occurrences.