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 and maps XML elements to UBIK® MetaClasses.
- Each XML element representing an UBIK® MetaClass requires an appropriate mapping
The example below maps 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 syntax can be for example be read as "Map XML Element id1 to property ID1"
<Identifier>
<id1>ID1</id>
<i2 LogicalAND=”0”>ID2</id2>
<id3 UsesGuid=”1”>ID3</id3>
</Identifier>
<id1>ID1</id>
<i2 LogicalAND=”0”>ID2</id2>
<id3 UsesGuid=”1”>ID3</id3>
</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) |
