|
|
W3C schemas is rapidly becoming the most common way to describe the structure of XML documents. The tool provides functionality to create a Plex XML import file, which can then be imported into Plex.
Run the SchemaImportGUI.exe file to import a W3C schema file. The following panel will be shown:
Specify the location of the file containing the W3C schema in the input field "XML schema file".
You can either specify a file location or a URL specifying the location of the file on a webserver.
Specify the location of the file where you want to save the generated Plex import document. Note that Plex expects this file to have the extension .xml.
If you leave the "Create Limits All triples" checkbox checked, each field created by the schema import will have a FLD limits all triple. If you uncheck the checkbox, no limits triples will be assigned to the field.
When you press the "Generate" button, the schema is read and validated and the Plex import file is generated.
Errors before import
If you have not specified a value for the location of either the schema file or the Plex import file an error will be shown.
An error will also be shown if the specified schema file does not contain a valid W3C schema. By pressing "Details" on the panel showing the error message more information about the error will be shown.
More than one potential top element
A W3C schema can contain more than one potential top element - or in other words, it can describe several potential XML documents.
To create the simplest possible XML model in Plex, we have chosen to create one document at the time.
So if there are several possible top elements described by the schema, a list of these top elements is shown.
Select the top element you want to import by double clicking on the name of the top element in the grid. This starts the creation of the import file.
Potential top elements are the elements that are globally defined in the schema. These are identified as being the <element> tags scoped directly under the <schema> tag.
One top element
If the schema only specifies one potential top element, the import is started immediately.
No top elements
It is possible to create a schema that does not contain any potential top elements. If such a schema is specified, the following message will be shown:
"No top element was selected - the import file has not been finalized".
A dialog message is shown.
In some cases, event though the import has been successful, the import tool has some information about the import which the user should be aware of. If this is the case, the following panel will be shown.
The most common cases are:
Renaming of an element/attribute
In some cases, the import tool has had to rename a field or entity. When this is the case, a LongName sourcecode is used to contain the "real" name. The names selected by the import tool will all be of the format WSY_LongNamen (n=integer).
TransacXML handles this automatically so you do not need to change anything. However, you might want to change the name of the entity/field in the Plex model to a more understandable name. To do so, perform the import into the Plex model, and then use the Plex editors to change the name.
An element is defined as a child of a parent element more than once
In some cases, the same element has been declared more than once as a child of a parent element. In these cases, the import tool only creates the first parent ENT includes ENT or parent ENT has FLD triple.
You might have to change the order of the "has" triples for the parent element after performing the Plex import to correctly model the schema.
Recursive structures
W3C XML Schemas can describe recursive structures. When such structures occurs, only the the top element is created as Plex can't handle the recursive structures (an entity includes itself).
Information about special cases in the import.
If an error has occurred, the error is shown in a dialog message, by pressing "Details" on the panel showing the error message, you can obtain detailed information about the error.
The import tool translates a number of structures described in the W3C schema to Plex objects. For certain of these objects you might want to create your own abstract objects. Pressing the "Settings" button opens a grid showing the Plex objects that you can specify a different inheritance for.
The objects you specify must be available in the Plex local model that you import the definitions into - either as locally defined objects or as objects belonging to a library model of the local model.
You specify an alternative Plex object by specifying the group model and the scoped object name of the Plex object in the grid.
If the object belongs to the local model you are going to import the schema into, you must blank the group model field.
Pressing the "Restore Default" button restores the original system settings from the Plex objects.
Pressing the "Save Settings" button saves the current content of the grid to a file. When the schema import tool is opened, this file is used to define the abstract objects to use.
This is useful in cases where you always want to specify your own inheritance for the Plex objects.
Please note that if you have saved the content of the settings grid using the "Save Settings" button, the saved settings will be used to generate the Plex import file even if you have not opened the Inheritance grid.
Use the Plex import tool to import the definitions into Plex.
The Plex version must support XML import (Plex 5.1 and later).
The Plex local model must have WSYXML and WSYDOM as library models.
Open the Plex local model that you want to import the definitions into.
The import tool is started using the menu item Tools→Import→XML Import.
You can read more about using the Plex import in the Plex help.
The top element of the generated XML document will be created as an unscoped entity having the name of the top element specified in the schema. All other objects created in the model will be scoped under this entity.
Depending on the choices made for the Plex import, existing objects might be overwritten. If you already have an entity having the name of the top element in the schema, you should move or rename this entity so that it will not be changed during the import.
This section explains the most common warning and error messages that can occur when performing the import.
Warning: Referenced object '...' not found in XML but exists in model
This is not an error and can be disregarded.
Error: Reference to object '...' found but object was not imported
This error means that the import file specifies that an object should refer to another object - but that this object is not specified in the import file - and that it does not already exist in the model you are importing into.
There can be two different reasons for this error:
1. The local model that you are importing into has not got the WSYXML group model as a library model.
2. You have specified an object in the inheritance grid that does not exist in the local model you are importing into.
Error: Triple '..' was not imported because '...' was not imported
This error is related to the previous one, it simply states that a triple could not be created as the parent object was not imported.
The Plex object names has certain limitations that does not correspond to the naming allowed by the XML standard. The two most common cases are:
Plex objects that according to the schema should have a name that is not a valid Plex name will inherit from WSYXML/LongName, the name that will be used on the XML documents are created as the literal value of the scoped LongName source code. The name of the Plex object itself will be autogenerated (WSY_LongName followed by a number).
If the top element has an invalid Plex name, it will get the name WSY_LongName1. If this is the case, you should rename the top element at once as any other schema having an invalid Plex name will also have this name assigned.
To make sure that the inheritance of namespaces performed by TransacXML are resolved correctly, all XMLElement entities and all ElementFields inherit from NamespaceAware. Only the elements actually belonging to a namespace will have a literal specified for the namespace source code.
This will typically occur when there is a <choice> construct in the schema where the same child element occurs in more than one of the optional groups.
For instance:
In this case, the element "top" has two different sequences as possible children, in this case either the A followed by ID or B followed by ID.
This will lead to the creation of three fields:
Top.Fields.A, Top.Fields.B, Top.Fields.ID.
And the following triples:
Top ENT has FLD Top.Fields.A
Top.ENT has FLD Top.Fields.ID
Top.ENT has FLD Top.Fields.B
However, in this case this means that the ID field will be inserted before the B field, if you select to insert B and ID - this is not correct according to schema. To correctly model the schema, you will have to manually change the sequence of the triples to:
Top ENT has FLD Top.Fields.A
Top.ENT has FLD Top.Fields.B
Top.ENT has FLD Top.Fields.ID
In general, you will have to look into the sequence of the has triples specifying the sequence of the child elements in the cases where it is reported that more a child element occurs more than once.
The tool uses .Net's SOM (Schema Object Model) implementation to access the W3C schema data.
It seems that this implementation demands a very strict adherence to the W3C schema standard. This means that event though other tools (e.g. XMLSpy) accepts certain schemas, the .Net framework might return an error.
This also means that only schemas belonging to the namespace http://www.w3.org/2001/XMLSchema are accepted.
The W3C standard allows recursive structures in the described XML documents. This can't be modeled fully in TransacXML. Where the tool is able to identify that it is a recursive structure, it only creates the first level of the recursive structure.
There might be some cases where a recursive structure is not identified correctly by the tool. To ensure that the tool does not end in an endless loop, the tool will stop processing if an element that should be created is scoped under more than 50 layers of elements.
All fields are just defined as character strings, no field types, values etc. are imported.
Online documentation - Websydian v6.5