XML Interface Toolkit
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! |
Contents
Workflow
Import
- Create a XML data file to be imported in UBIK® according to the description for the mapping configuration
- Use the Interface Manager to create a proper interface command file specifying the required server parameters, folder and file locations
- Manually start and test the import by executing the interface via the Interface Manager
Export
- Use the Interface Manager to create a proper interface command file specifying the required server parameters, folder and file locations
- 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
| Key | Application | Description |
|---|---|---|
| Server | Import/Export | Name of the SQL Server (DataSource) |
| InitialCatalog | Import/Export | The name of the instance on the SQL Server (DataBase) |
| UserID | Import/Export | SQL Server user name (User) |
| Password | Import/Export | SQL Server password (Password) |
| RecordLifeTime | Import/Export | Duration how long records are valid before they will be requeried for changes by the kernel; -1 to turn off |
| WorkingFolder | Import/Export | Defines a folder where temporary files will be placed and deleted after processing |
| DataFile | Import/Export | Import: File path to XML data file to be imported; Export: Exported XML data will be stored in this file |
| DataMappingFile | Import/Export | File path to file containing the XML mapping information, both for import as well as export |
| DataView | Export | Name of a UBIK® view object defining the scope and hierarchy of exported objects |
| DataObject | Export | Guid of a single UBIK® object to be exported |
| DeleteFile | Import/Export | Defines whether or not the specified DataFile should be deleted after processing |
| LogFolder | Import/Export | Defines a folder where log files will be created into; if set a log file will be created always! |
| LogFile | Import/Export | Optional: defines a certain log file name; it not set the system will create an arbitrary one |
Example: Export
<InterfaceManager>
<Commands>
<Interface FullName="UBIK.Interface.Module.XML, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" File="C:\UBIK\Studio\Interfaces\UBIK.Interface.Module.XML.dll" Class="UBIK.Interface.Module.XML.XMLDataInterface" Direction="E">
<Parameter Key="Server" Value="sqlserver" />
<Parameter Key="InitialCatalog" Value="ubik" />
<Parameter Key="UserID" Value="sa" />
<Parameter Key="Password" Value="sa" />
<Parameter Key="RecordLifeTime" Value="-1" />
<Parameter Key="WorkingFolder" Value="C:\UBIK\Xml\Work" />
<Parameter Key="DataFile" Value="C:\UBIK\Xml\Data\data.xml" />
<Parameter Key="DataMappingFile" Value="C:\UBIK\Xml\Map\map.xml" />
<Parameter Key="DataView" Value="VIE_EXPORT" />
<Parameter Key="DeleteFile" Value="0" />
<Parameter Key="LogFolder" Value="C:\UBIK\Log\Temp" />
<Parameter Key="LogFile" Value="export.log" />
</Interface>
</Commands>
</InterfaceManager>
<Commands>
<Interface FullName="UBIK.Interface.Module.XML, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" File="C:\UBIK\Studio\Interfaces\UBIK.Interface.Module.XML.dll" Class="UBIK.Interface.Module.XML.XMLDataInterface" Direction="E">
<Parameter Key="Server" Value="sqlserver" />
<Parameter Key="InitialCatalog" Value="ubik" />
<Parameter Key="UserID" Value="sa" />
<Parameter Key="Password" Value="sa" />
<Parameter Key="RecordLifeTime" Value="-1" />
<Parameter Key="WorkingFolder" Value="C:\UBIK\Xml\Work" />
<Parameter Key="DataFile" Value="C:\UBIK\Xml\Data\data.xml" />
<Parameter Key="DataMappingFile" Value="C:\UBIK\Xml\Map\map.xml" />
<Parameter Key="DataView" Value="VIE_EXPORT" />
<Parameter Key="DeleteFile" Value="0" />
<Parameter Key="LogFolder" Value="C:\UBIK\Log\Temp" />
<Parameter Key="LogFile" Value="export.log" />
</Interface>
</Commands>
</InterfaceManager>
Example: Import
<InterfaceManager>
<Commands>
<Interface FullName="UBIK.Interface.Module.XML, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" File="C:\UBIK\Studio\Interfaces\UBIK.Interface.Module.XML.dll" Class="UBIK.Interface.Module.XML.XMLDataInterface" Direction="I">
<Parameter Key="Server" Value="sqlserver" />
<Parameter Key="InitialCatalog" Value="ubik" />
<Parameter Key="UserID" Value="sa" />
<Parameter Key="Password" Value="sa" />
<Parameter Key="RecordLifeTime" Value="-1" />
<Parameter Key="WorkingFolder" Value="C:\UBIK\Xml\Work" />
<Parameter Key="DataFile" Value="C:\UBIK\Xml\Data\data.xml" />
<Parameter Key="DataMappingFile" Value="C:\UBIK\Xml\Map\map.xml" />
<Parameter Key="DataView" Value="" />
<Parameter Key="DeleteFile" Value="0" />
<Parameter Key="LogFolder" Value="C:\UBIK\Log\Temp" />
<Parameter Key="LogFile" Value="import.log" />
</Interface>
</Commands>
</InterfaceManager>
<Commands>
<Interface FullName="UBIK.Interface.Module.XML, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" File="C:\UBIK\Studio\Interfaces\UBIK.Interface.Module.XML.dll" Class="UBIK.Interface.Module.XML.XMLDataInterface" Direction="I">
<Parameter Key="Server" Value="sqlserver" />
<Parameter Key="InitialCatalog" Value="ubik" />
<Parameter Key="UserID" Value="sa" />
<Parameter Key="Password" Value="sa" />
<Parameter Key="RecordLifeTime" Value="-1" />
<Parameter Key="WorkingFolder" Value="C:\UBIK\Xml\Work" />
<Parameter Key="DataFile" Value="C:\UBIK\Xml\Data\data.xml" />
<Parameter Key="DataMappingFile" Value="C:\UBIK\Xml\Map\map.xml" />
<Parameter Key="DataView" Value="" />
<Parameter Key="DeleteFile" Value="0" />
<Parameter Key="LogFolder" Value="C:\UBIK\Log\Temp" />
<Parameter Key="LogFile" Value="import.log" />
</Interface>
</Commands>
</InterfaceManager>
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 <Identifiers>
- 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>
<Import EvaluateReferences=”1” EvaluateRelations=”0” DataEnvelope=”UbikXMLData”>
...
</Import>
<Export EvaluateReferences=”1” EvaluateRelations=”0” DataEnvelope=” UbikXMLData” EvaluateUTS=”1”>
...
</Export>
...
</Import>
<Export EvaluateReferences=”1” EvaluateRelations=”0” DataEnvelope=” UbikXMLData” EvaluateUTS=”1”>
...
</Export>
Attributes
| Attribute | Values | Description |
|---|---|---|
| EvaluateReferences | 0 or 1 | Set to 1 if references shall be evaluated (default = 1) |
| EvaluateRelations | 0 or 1 | Set to 1 if relations shall be evaluated (default = 1) |
| DataEnvelope | Text | Specify XML envelope (root node, default = UbikXMLData) |
| EvaluateUTS | 0 or 1 | Set to 1 to export UpdateTimeStamp of objects (default = 0) |
 | 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
Example: map a XML element NameOfXmlElement to the MetaClass SAPObject
<NameOfXmlElement MetaClass=”SAPObject”> or
<NameOfXmlElement MetaClass=”UID:11ffa6b5-0ada-41f5-bcd8-89fff9247d4d”>
...
</NameOfXmlElement>
<NameOfXmlElement MetaClass=”UID:11ffa6b5-0ada-41f5-bcd8-89fff9247d4d”>
...
</NameOfXmlElement>
Attributes
| Attribute | Values | Description |
|---|---|---|
| MetaClass | Text | Specify the UBIK® MetaClass either by its name or its Guid (via UID:Guid) |
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>
<id1>ID1</id> Map XML element id1 to property ID1
<id2 LogicalAND=”0”>ID2</id2> Concatenate identifier with OR
<id3 UsesGuid=”1”>ID3</id3> Use a Guid as key value
</Identifier>
<id1>ID1</id> Map XML element id1 to property ID1
<id2 LogicalAND=”0”>ID2</id2> Concatenate identifier with OR
<id3 UsesGuid=”1”>ID3</id3> Use a Guid as key value
</Identifier>
Attributes
| Attribute | Values | Description |
|---|---|---|
| LogicalAND | 0 or 1 | Concatenate the sequent identifier with AND (default = 1) |
| UsesGuid | 0 or 1 | Inner text of XML element will be a Guid string (default = 0) |
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.
Example: map XML element id1 to property ID1
<Property>
<name>NAME</name> Map XML Element name to property NAME
<descr Value="Fix">DESCR</descr> Use constant value during import
<descrDE Index="0">TXT</descr> Access index values of properties
<descrEN Index="1">TXT</descr>
<meas Validate="1">12.45</meas> Validate property
</Property>
<name>NAME</name> Map XML Element name to property NAME
<descr Value="Fix">DESCR</descr> Use constant value during import
<descrDE Index="0">TXT</descr> Access index values of properties
<descrEN Index="1">TXT</descr>
<meas Validate="1">12.45</meas> Validate property
</Property>
Attributes
| Attribute | Values | Description |
|---|---|---|
| LogicalAND | 0 or 1 | Concatenate the sequent identifier with AND (default = 1) |
| UsesGuid | 0 or 1 | Inner text of XML element will be a Guid string (default = 0) |
