Configuration and settings XML-Module

XML-Scheme

A new XML schema can be integrated into the XML module, by copying the .xsd files of the schema into the XSD directory of the module. The directory is located under:

CODE

/I-EFFECT/VXRXM0/MAPPER/XML/XSD

After all required XSD files for the XML scheme have been copied into the XSD directory, the schema can be displayed by refreshing the *MAPGUI. After this the XML schema is available to create mapping definitions.

Deleting or moving XML schemas can make existing mapping definitions unusable.

XML target module settings

Open the XML-header (double click) to edit the settings.

Within the XML header section you can define the following settings as target for the XML module:

Value	Description
Validate Output File	Determines if an output file should be validated against the relative XML schema in the mapping definition.
Use Pretty Printer	Determines if the output file should be formatted and if line breaks should be inserted.
XML Encoding	Determines the XML encoding for the output file. There is a fixed correlation between the XML encoding and CCSID of the output file. For this reason the inapplicable CCSIDS will automatically not be displayed.
CCSID	Determines the CCSID of the output file.

Add XML Schema

Deleting or moving XML schemas can make existing mapping definitions unusable.

Invalid XML Schemas

If an XML schema contains errors, it will denoted with the marking Invalid XSD in the module view when the schema is opened. By clicking on the invalid XSD element, a detailed description of the problem will appear in the detailed information of the *MAPGUI Plug-In.

Module Specific Tasks

writeFile	Writes all currently collected data into one file.
filePath	The file's path.

Define Mapping Group

The structure of an XML schema defintion can be as deep and nested as desired. This can cause mapping definitions to be very complex. For this reason it is possible to define mapping groups in the XML module view. A user defined mapping group is distinguished by the fact that it applies fto all elements nested in it. For example a root element of an XML schema can be set as a mapping group, and then all mapped elements of this schema will be displayed in this mapping group. If a new mapping group should be defined for the partial structure X, the child element, the root element of the partial structure X must be defined as a mapping group.

Setting Elements as a Mapping Group

Every element that is a complex type can be set as a mapping group, by right-clicking on it and selecting Set as group. If an element was set as a group, its icon will be changed accordingly see Icons. If an element was set as a group, it can be reset by right-clicking on it and selecting the function Remove Group. This does not affect existing mapping groups and only applies to the newly mapped elements.

Icons

Directories, Schemas

	Schema Directory
	XML Schema Definition (XSD file)
	Invalid XML Schema

Elements of Complex Types

	Element of a complex type (not required).
	Element of a complex type (required).
	Choice-Element of a complex type. The element can be selected with other elements with the same icon. Only one element can be selected/mapped.
	End of Elements.

Elements of Simple Types

	Element of a simple type (not required).
	Element of a simple type (required).
	Choice-Element of a simple type. The element can be selected with other elements with the same icon. Only one element can be selected/mapped.

Attributes of Simple Types

Attributes. Attributes can only be used once.

Grouping Elements

	Element of a complex type that was set as a mapping group (not required).
	Element of a complex type that was set as a mapping group (required).
	Choice-Element that was set as a mapping group.

Substitution Groups

	Substitution group for an element of complex type (not required).
	Substitution group for an element of complex type (required).
	Substitution group for a Choice-Element of a complex type.
	Substitution group for an element of a simple type (not required).
	Substitution group for an element of a simple type (required).
	Substitution group for a Choice-Element simple type

Abstract Types

	Abstract element of a complex type (not required).
	Abstract element of a complex type (required).
	Abstract element of a complex type (select).
	Abstract element of a simple type (not required).
	Abstract element of a simple type (required).
	Abstract element of a simple type (select).

XML Partner Master Data

Using the XML partner master data, incoming XML files can be tested for specific criteria and then correctly processed. This occurs by specifying expected values and XPaths1, which indicate values in an XML file.

Partner master data for the XML module is managed by the file PRTXML with the following fields:

PID	Partner ID
MAPID	Mapping definitions for the mapping to be run if the file meets all required criteria.
NAMESPACE	Namespace is not a required file but can be used to improve performance. The value entered here must be the same as the namespace of the root element of the XML document, so that the XML file can be tested for further criteria (empty stands for all possible name spaces).
XPATH_REC	This field contains an Xpath used to find the recipient. The value that is found by analysis of the Xpath must be the same as the value in the field RECIPIENT.
RECIPIENT	Contains the expected values for the recipient.
XPATH_SND	The field contains an Xpath used to find the sender. The value that is found by analysis of the Xpath must be the same as the value in the filed SENDER.
SENDER	Contains the expected value for sender.

In order to assign a file to a mapping definition, the values found for recipient and sender must be the same as the expected values, and if name-space was defined, the namespace in the document's root element must also be the same.

The following illustration clarifies the relationship between XML files and partner master data entry:

Abstract Types, Substitution Groups and Derived Types in Instance Documents

Abstract types, substitution groups and derived types are powerful mechanisms, used to expand and reuse XML schemas. They are explained in detail in section of of the XML schema reference 1, which is used as a basis for understanding this chapter.

This illustration shows the module view from a slightly modified variant of the International Book Order example from the XML schema reference. It is important to note in this illustration that three billing addresses are present. This happened because in the XML schema definition two new types were derived from the type Address, namely the German address - DeAddress and an address in the US - USAAddress. These two derived types can be used everywhere where an element type Address is defined. For this reason the two additional elements Shipping address and Billingaddress were added. The elements that are created by type derivation are specially marked in the module view. Their designation is created by the name of the element and the name of the derived type in this form ELEMENT_NAME{DERIVED_TYP_NAME}.

Furthermore the elements Shipping address and Billingaddress are marked in green. This indicates that both elements are abstract or are from an abstract type. In this case, both are from the basic type Address, which was defined as abstract.

One way to substitute elements with other elements in XML schemes is by using substitution groups. As with derived types, all possible substitution elements are displayed where the head element of the substitution group occurs. In this example the element Comment is the head element for the substitution group, which contains the elements shipComment and customerComment. The head element can be replaced by either of the other elements.

Mapping of Abstract Elements, Elements with Derived Types, and Substitution Groups

Abstract Elements:

Mapping abstract elements or child elements of abstract elements is not possible with *MAPGUI, because instances cannot be created by them and such elements cannot exist in a valid output file.

Substitution Groups:

Mapping substitution groups functions similarly to the mapping of normal elements, but it is important to note the following.

If the XML module is used as the Source-Module, every element, which is a substitution element, will be considered according to its occurrence. Using the International Book Order example, if in the third element deliveryComment occurs in the list, it will be counted as the third, even if there were 2 customerComment elements beforehand. The head element of the element is not important only the actual occurrence.

If the XML module is the Target Module, things occur differently. Every inserted element that is a substitute element will be counted as an head element. That means, if a list that can contain two Comment elements and one shipComment element and one customerComment element were inserted, the list is full and any further Comments elements will be added to a new list. If inserted at a specific place, the occurrence will be counted and the head element will be used again. If in a list with three Comment elements, a shipComments element should be inserted, it doesn't matter what type of Comment element is first, it will be simply placed in the second Comment position.

Derived Types:

Mapping of derived types corresponds to the rules for mapping Substitution elements. The basic type element corresponds to the head element and the derived types are the substitute elements that were assigned to the group.
It is important to note that an element can be substituted with another element (substitution group) and substituted by one element of a derived type. Both will be counted on the Target-module side as the head/base type and as different elements on the source module side.