Jump to: navigation, search

Difference between revisions of "XML Interface Toolkit"

m (Text replacement - "{{UBIKSTUDIO" to "{{UBIK Studio")
 
(31 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
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 [[Interface_Manager#Configuration|default parameters]].
 
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 [[Interface_Manager#Configuration|default parameters]].
−
{{Attention|The XML data file must use the correct encoding, e.g. UTF-8!}}
 
  
 
== Workflow ==
 
== Workflow ==
Line 13: Line 12:
  
 
== Parameters ==
 
== 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 [[UBIK_Studio_Basics#Settings|settings section]] for a detailed description.
+
The general parameters, marked by Import/Export, are equivalents of the settings used by {{UBIK Studio}} to connect to a database, please refer to its [[UBIK_Studio_Basics#Settings|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
 
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
Line 49: Line 48:
 
|-
 
|-
 
| LogFile || Import/Export|| Optional: defines a certain log file name; it not set the system will create an arbitrary one
 
| LogFile || Import/Export|| Optional: defines a certain log file name; it not set the system will create an arbitrary one
 +
|-
 +
| LogLevel || Import/Export|| Optional: defines a certain log level
 +
|-
 +
|}
 +
=== Log level ===
 +
{| class="wikitable" | width = "88%"
 +
|-
 +
! Log level !! Label !! Description
 +
|-
 +
| -1 || SYSTEM || Name of the SQL Server (DataSource)
 +
|-
 +
| 0 || ERROR || Runtime errors or unexpected conditions
 +
|-
 +
| 10 || WARNING || Almost errors, runtime situations that are undesirable or unexpected
 +
|-
 +
| 20 || INFO || Interesting runtime events (startup/shutdown)
 +
|-
 +
| 25 || DETAIL || Similar to INFO, but more detailed information
 +
|-
 +
| 30 || DEBUG || Detailed information on system relevant conditions
 +
|-
 +
| 40|| TRACE || Everything is logged
 
|-
 
|-
 
|}
 
|}
Line 102: Line 123:
 
A mapping configuration file consists of two distinctive sections for the [[#Section_.3CImport.3E_.2F_.3CExport.3E|general import and export configuration]], labeled as '''<Import>''' and '''<Export>''', respectively.
 
A mapping configuration file consists of two distinctive sections for the [[#Section_.3CImport.3E_.2F_.3CExport.3E|general import and export configuration]], labeled as '''<Import>''' and '''<Export>''', respectively.
  
−
Each such section consists of multiple sections describing the [[#Section_.3CNameOfXmlElement.3E|mapping of {{UBIK}} MetaClasses to XML elements]], labeled similar to the name of the related XML element.
+
Each such section consists of multiple sections describing the mapping of [[#Section_.3CNameOfXmlElement.3E|{{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
 
These class related mapping sections (also called '''ClassMapping''') consist of sections for defining
−
* possible key properties, labeled '''<Identifiers>'''
+
* possible key properties, labeled '''[[#Section_.3CIdentifier.3E|<Identifier>]]'''
−
* general properties, labeled '''<Property>'''
+
* general properties, labeled '''[[#Section_.3CProperty.3E|<Property>]]'''
−
* references for objects, labeled '''<Reference>'''
+
* references for objects, labeled '''[[#Section_.3CReference.3E|<Reference>]]'''
−
* relations between objects, labeled '''<Relation>'''
+
* relations between objects, labeled '''[[#Section_.3CRelation.3E|<Relation>]]'''
−
* possible child objects, labeled '''<Object>'''
+
* possible child objects, labeled '''[[#Section_.3CObject.3E|<Object>]]'''
  
 
{{Attention|The mapping information must be enveloped by a XML tag <UbikXMLMap>!}}
 
{{Attention|The mapping information must be enveloped by a XML tag <UbikXMLMap>!}}
Line 141: Line 162:
 
* This section defines the ClassMapping (as mentioned above) for mapping XML elements to {{UBIK}} MetaClasses
 
* 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
 
* Each XML element contained in the data file requires an appropriate mapping
 +
 +
{{Attention|The XML class mapping must be unique in the '''<Import>''' section and has to map to one specific MetaClass.}}
 +
{{Attention|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.}}
  
 
<source lang="xml">
 
<source lang="xml">
Line 163: Line 187:
 
* Values of identifier properties can have data type {{Guid}}
 
* 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.
 
* 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.
 +
 +
{{Hint|Identifier attributes of reference and relation elements in the data file must be similar to identifier elements '''TargetType'''.}}
  
 
<source lang="xml">
 
<source lang="xml">
Line 218: Line 244:
 
* 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.
 
* 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 an import process set '''UseHierarchy=1''' to load a content object corresponding to any parental XML element of the one currently processed.
 +
{{Hint|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.}}
  
 
<source lang="xml">
 
<source lang="xml">
Line 241: Line 268:
 
* The related object is tried to be loaded according to the '''<Identifier>''' mappings of the class mapping found for '''TargetType'''.
 
* 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.
 
* 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.
 +
 +
{{Hint|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.}}
  
 
<source lang="xml">
 
<source lang="xml">
Line 272: Line 301:
  
 
=== Section <Object> ===
 
=== Section <Object> ===
−
* Listof possible child '''TargetTypes'''
+
* 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).
 
* 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.
 
* Export: each element defined in '''<Object>''' tells the interface to check, whether or not the child objects in the view should be exported.
 +
 +
{{Attention|A non-existing or empty <Object> section leads to skipping of all child objects.}}
  
 
<source lang="xml">
 
<source lang="xml">
Line 282: Line 313:
 
</Object>
 
</Object>
 
</source>
 
</source>
 +
 +
=== Remarks ===
 +
==== UseHierarchy ====
 +
Be aware of the different usage of the '''UseHierarchy''' attribute in import / export processes. In an export the system will try load all objects related to the current exported object via the given relations / refernces. To skip the current view parent enable UseHierarchy, this exports all related objects except the view parent. If relational information should not be exported do not include a relation element in this section at all. Nevertheless, certain hierarchical information will always be exported due to the view hierarchy.
 +
 +
==== Encoding ====
 +
The XML files must use the correct encoding, for example UTF-8!
  
 
== See also ==
 
== See also ==
 
* [[Interface Tools Library]]
 
* [[Interface Tools Library]]
 
* [[XML Interface Toolkit Library]]
 
* [[XML Interface Toolkit Library]]
 +
* [[XML Interface Toolkit (Example)]]
  
−
[[Category:UBIK Studio]]
+
[[Category:XML]]
−
[[Category:Interfacing]]
+

Latest revision as of 10:09, 8 May 2015

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.

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 UBIK® Studio 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
LogLevel Import/Export Optional: defines a certain log level

Log level

Log level Label Description
-1 SYSTEM Name of the SQL Server (DataSource)
0 ERROR Runtime errors or unexpected conditions
10 WARNING Almost errors, runtime situations that are undesirable or unexpected
20 INFO Interesting runtime events (startup/shutdown)
25 DETAIL Similar to INFO, but more detailed information
30 DEBUG Detailed information on system relevant conditions
40 TRACE Everything is logged

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>

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>

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

IC Attention.pngThe 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>

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)
IC Hint square.pngThe 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
IC Attention.pngThe XML class mapping must be unique in the <Import> section and has to map to one specific MetaClass.
IC Attention.pngThe 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.
<NameOfXmlElement MetaClass="SAPObject">                                        Map a XML element NameOfXmlElement to MetaClass SAPObject
<NameOfXmlElement MetaClass="UID:11ffa6b5-0ada-41f5-bcd8-89fff9247d4d">         Using its Guid
  ...
</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.
IC Hint square.pngIdentifier attributes of reference and relation elements in the data file must be similar to identifier elements TargetType.
<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.
  • 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.
<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
Value Text Constant value (default = null)
Index Numeric Index value (default = -1)
Validate 0 or 1 Import: If "1" the validation time stamp is set (default = 1)
Export: If "1" only validated property values will be exported; if "0" property values will always be exported.

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.
IC Hint square.pngFor 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.
<Reference>
  <sap TargetType="SAP">SAPID</sap>                             Set a reference of an object SAP with key values sap to MetaProperty SAPID of the current processed object
  <cad TargetType="CAD" UseHierarchy="1">CADID</cad>            Set a reference of an object CAD, which is a XML parent object, to MetaProperty CADID of the current processed object
</Reference>

Attributes

Attribute Values Description
TargetType Text Name of class mapping of referenced object
UseHierarchy 0 or 1 Import: Ignore key attribute of XML element, use parental object instead(default = 0); the system will always create the reference whether or not a XML data element is available
Export: parent object in view will not be exported (default = 0) as reference element

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.
IC Hint square.pngFor 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.
<Relation>
  <sap TargetType=”SAPobj” Name=”SAP_REL”>
    <Property>                                  Relation data properties
      <rd1>RelData1</rd1>
      <rd2>RelData2</rd2>
    </Property>
  </sap>
  <cad TargetType=”CADobj” Name=”CAD_REL”>
    <Property>
      <rd1>RelData1</rd1>
      <rd2>RelData2</rd2>
    </Property>
  </cad>
</Relation>

Attributes

Attribute Values Description
TargetType Text Name of class mapping of related object; ignored in export if UsesGuid=1
UseHierarchy 0 or 1 Import: Ignore key attribute of XML element, use parental object instead (default = 0); if no XML data element is available the system will only create the relationship without setting the relation data
Export: parent object in view will not be exported (default = 0) as relation element
Name Text Name of UBIK® relation

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.
IC Attention.pngA non-existing or empty <Object> section leads to skipping of all child objects.
<Object>
  <SAPObj />                    Name of class mapping of child object
  <CADObj />   
</Object>

Remarks

UseHierarchy

Be aware of the different usage of the UseHierarchy attribute in import / export processes. In an export the system will try load all objects related to the current exported object via the given relations / refernces. To skip the current view parent enable UseHierarchy, this exports all related objects except the view parent. If relational information should not be exported do not include a relation element in this section at all. Nevertheless, certain hierarchical information will always be exported due to the view hierarchy.

Encoding

The XML files must use the correct encoding, for example UTF-8!

See also

Retrieved from "https://wiki.augmensys.com/index.php?title=XML_Interface_Toolkit&oldid=15126"