Difference between revisions of "XML Interface Toolkit"

Revision as of 15:59, 11 February 2014

The XML interface toolkit provides mechanisms to import and export data in XML format. Arbitrary structured XML data is mapped to according UBIK^® objects and its properties by a mapping specified in a separate mapping configuration file. Both files have to be specified in the interface command file additional to the default parameters.

The XML data file must use the correct encoding, e.g. UTF-8!

Workflow

Import

1. Create a XML data file to be imported in UBIK^® according to the description for the mapping configuration
2. Use the Interface Manager to create a proper interface command file specifying the required server parameters, folder and file locations
3. Manually start and test the import by executing the interface via the Interface Manager

Export

1. Use the Interface Manager to create a proper interface command file specifying the required server parameters, folder and file locations
2. Manually start and test the export by executing the interface via the Interface Manager

Parameters

The general parameters, marked by Import/Export, are equivalents of the settings used by UBIKSTUDIO to connect to a database, please refer to its settings section for a detailed description.

The parameter DataView is used only for export purposes and defines the name of a UBIK^® View object. In an export process the XML toolkit

• evaluates the view hierarchy and its objects
• exports an object as defined in the mapping
• in the same hierarchy as placed in the view

Example: Export

Example: Import

Mapping configuration

The XML data is converted into according UBIK^® data (objects, property values,...) by applying a mapping between XML elements / attributes and UBIK^® MetaClasses / MetaProperties.

Sections of mapping file

A mapping configuration file consists of two distinctive sections for the general import and export configuration, labeled as <Import> and <Export>, respectively.

Each such section consists of multiple sections describing the mapping of UBIK^® MetaClasses to XML elements, labeled similar to the name of the related XML element. These class related mapping sections (also called ClassMapping) consist of sections for defining

• possible key properties, labeled <Identifier>
• general properties, labeled <Property>
• references for objects, labeled <Reference>
• relations between objects, labeled <Relation>
• possible child objects, labeled <Object>

The mapping information must be enveloped by a XML tag <UbikXMLMap>!

Section <Import> / <Export>

Attributes

The default envelope for the XML data is <UbikXMLData> and can be modified via the mapping configuration settings.

Section <NameOfXmlElement>

• This section defines the ClassMapping (as mentioned above) for mapping XML elements to UBIK^® MetaClasses
• Each XML element contained in the data file requires an appropriate mapping

The XML class mapping must be unique in the <Import> section and has to map to one specific MetaClass.

The XML class mapping must be unique for the MetaClass name in the <Export> section. The XML class mapping used to determine properties of the currently exported object is determined by the object's MetaClass name. Hence, the class mapping for each MetaClass in the <Export> mapping section must be unique by the MetaClass name.

Attributes

Section <Identifier>

• Mapping of XML elements to key properties used to identify an UBIK^® object
• The value of the XML attribute of the XML object in the data file will be used as key value
• Identifier properties can be concatenated with AND or OR
• Values of identifier properties can have data type Guid
• If one identifier mapping has UsesGuid enabled, it will always be tried to load the object using its Guid. The other identifier mappings will be used only, if the XML object is missing a proper XML element for the Guid identifier.

Identifier attributes of reference and relation elements in the data file must be similar to identifier elements TargetType.

Attributes

Section <Property>

• Mapping of XML elements to properties
• The data type of the inner texts of the XML elements in the data file must be Text. The casting of the values to the actual MetaProperty's data type happens internally. The user does not have to care about the data type.
• Identifier properties can be concatenated with AND or OR
• Values of identifier properties can have data type Guid
• If one identifier mapping has UsesGuid enabled, it will always be tried to load the object using its Guid. The other identifier mappings will be used only, if the XML object is missing a proper XML element for the Guid identifier.
• Indexed MetaProperties can additionally have an Index mapping attribute
• Use the Value attribute if a constant value shall be imported
• Set Validate = 0 if the validation time stamp of a validated property should not be not during import and/or the property value should be always exported.

Attributes

Section <Reference>

• Mapping of a XML elements to an MetaProperty representing either, a foreign key or a Guid value, linking to an another UBIK^® object
• The system tries to load the content object of the MetaClass as defined in the class mapping identified by TargetType with key values similar to the values of the according XML attribute in the data file. If an object can be found, a reference to this object is set on the MetaProperty named similar to the inner text of the XML element in the mapping file.
• For an import process set UseHierarchy=1 to load a content object corresponding to any parental XML element of the one currently processed.

For each reference mapping specified in the <Reference> section, the interface will try to read from / create an appropriate XML element. To ignore the reference information during import or if it should not be exported do not include a reference element in this section at all or set EvaluateReferences to 0.

Attributes

Section <Relation>

• Mapping of XML elements to an UBIK^® relation
• The system tries to load a content object of the MetaClass as defined in the class mapping identified by TargetType with key values similar to the values of the according XML attribute in the data file. If an object is found a relation between this and the current object is created using the relation <Identifier>.
• The related object is tried to be loaded according to the <Identifier> mappings of the class mapping found for TargetType.
• A property mapping list for the relation data object can be set, where the XML elements of the currently processed XML relation element are processed similar to MetaProperties de-fined as <Property> elements.

For each relation specified in the <Relation> section, the interface will try to create a relation between the current and a linked object during import. To ignore the relational information during import or if it should not be exported do not include a relation element in this section at all or set EvaluateRelations to 0.

Attributes

Section <Object>

• List of possible child TargetTypes
• Import: each element defined in <Object> tells the interface to treat child elements with a similar name as XML object (instead of property, reference or relation).
• Export: each element defined in <Object> tells the interface to check, whether or not the child objects in the view should be exported.

A non-existing or empty <Object> section leads to skipping of all child objects.

See also

• Interface Tools Library
• XML Interface Toolkit Library