TransacXML Implementation Guide

Introduction    Implementing    Other Uses    Parts    Tutorial    Glossary

This document explains how to build a XML model in TransacXML. Most often this XML model has already been defined in another format, e.g. a DTD, XML schema, or the XML model is just defined with a sample XML document.

Even though this document describes the conversion process when transforming a DTD or sample XML document into a XML model in CA Plex, the information will also be useful when designing XML models from scratch in CA Plex.

We have found that persons with no or little experience with XML and TransacXML find that it is very hard to identify the information that is needed in this document. To ease the introduction to TransacXML, we have created a series of documents, that contains basic information about XML and how you can use TransacXML to create XML processing.

If you do not have experience with TransacXML, we recommend that you start by having a look at these documents:

Information in the CA Plex Model

A DTD or XML schema will contain much more information about the XML documents they describe than is necessary for the corresponding CA Plex model. The CA Plex model only needs the following information:

• Element structure: How are elements organized. Which element has which elements as children?
• Element cardinality: Can an element appear more than once within the scope of its parent element?
• Data representation: Is data represented as attributes or as simple elements?

This is the only information that needs to be extracted from the DTD or XML schema when carrying out the modeling process.

Data Stored in the XML Document

In TransacXML, the following ways of representing data in an XML document are supported:

• Attributes (<a b="data">)
• Simple elements (<a>data</a>)
• Complex elements (<a b="data1"><c>data2</c></a>)

Each of these data representations will be described below in more detail.

Data in Attributes

TransacXML can retrieve data from element attributes:

In TransacXML, attributes are represented as fields inheriting from the abstract field AttributeField.

Data in Simple Elements

TransacXML can retrieve data from the value of a text node being the only child of an element:

Simple Elements
Simple elements are elements with exactly one child node that is a text node.

In TransacXML, simple elements are represented as fields inheriting from the abstract field ElementField or RepeatingElementField (depending on how many times they are allowed to occur).

In the above example, the elements name and age are simple elements whereas the element person is a complex element.

The following restrictions apply to this type of data representation:

• The simple element (in the above case, name and age) must have zero or one children. Zero children means the element holds no data. If the simple element has one child, this must be of the type text. The child's value is the actual data.
  
• As a consequence of the above restriction, the text in simple elements cannot be "broken into pieces" by element tags (mixed content elements). Thus, although perfectly legal in XML, the following construction is not recognized by TransacXML as being data:

  <name>Peter<b>James</b>Jenkins</name>

Data in Complex Elements

TransacXML also supports a combination of the two data representations described above:

An XML construction carrying a sub structure is defined as a complex element in TransacXML, and it is represented as an entity inheriting from XmlElement or XmlRepeatingElement. The structure scoped under the complex element is either simple elements (represented as entity fields), or more complex elements (represented as scoped entities).

The following restriction apply to this type of data representation: 

An attribute is not allowed to have the same name as any of the simple elements. However, an attribute can have the same name as elements that do not have the role as simple elements. Consider these examples:

Example 1

is illegal since the attribute and the simple element carry the same name.

Example 2

is legal since the job element is not a simple element.

Repeated Elements

TransacXML supports elements that are repeated multiple times within the scope of a particular parent element:

Example 1

Example 2

In example 1, the simple element item is repeated. In example 2, the complex element person element (that scopes the simple element name) is repeated. Examples 1 and 2 represent two different cases when converting into CA Plex objects and triples.

How to Create XML Model

This section contains information about how to model the XML document structure into triples and objects in the CA Plex model. Typically the XML model is created from either a DTD or an XML document sample, so for each triple and object there will be examples on how the corresponding DTD or XML document snippet look like.

The creation of triples and objects includes two basic activities:

• Creation of entities to reflect the parent/child structure of elements..
• Creation of entities and fields to reflect the attributes and simple elements.

When the modeling process has been completed, the CA Plex model will contain an entity with the same name as the document element (root element) of the XML document. This entity scopes entities which themselves scope entities according to the element structure of the XML document.

To carry out the modeling process go through the steps specified below (each step is explained in detail in the following sections):

1. Specify the root element of the XML document
   Model the document element (root element).
2. Specify element structure
   Identify the structure of elements in the XML document or DTD.
3. Specify data fields
   For each entity created specify the data fields connected to that entity.

Declaration of Document Element (Root Element)

XML documents have exactly one root element (the document element). The modeling of the document element into an entity in CA Plex is the starting point of the modeling process. Often, the first declaration in a DTD will be the declaration of the document element. 

Identify the document element declaration in the DTD this way: 

Find the one DTD declaration which declares an element that does not occur within the parentheses of another element declaration.

Consider the following DTD declaration:

If no element declaration can be found in which MyDocumentElement occurs within the parentheses, then MyDocumentElement is the document element of XML documents described by the DTD being converted. For XML documents the document element is the top element.

When the document element has been identified (e.g. MyDocumentElement) create the following triple:

Structure Declarations

The organization of elements into parents and children is specified using the following DTD declarations:

If MyChild elements are later declared using the <!ELEMENT MyChild (#PCDATA) > declaration, MyChild is a simple element and should thus be represented as a field in the CA Plex model. Refer to the data field section for further information. This applies to all declarations mentioned in the present section.

Information about whether the element can occur more than once should be imported into the CA Plex model. There are three cases to consider:

• The child element occurs once
• The child element occurs at the most once
• The child element can occur more than once

The quantity indicators ?, +, and * in the DTD declaration determine how many times an element can occur within the scope of its parent. ? specifies that the element can occur zero or one time. + specifies that the element can occur once or more times. * specifies that the element can occur zero or more times. 

Below, the corresponding triples are specified for each of the mutually exclusive cases.

Child Element Occurs Once

If the element MyChild is declared using no quantity indicators the corresponding element occurs once within the scope of its parent. The corresponding DTD declarations have the following structure:

Suppose an entity MyParent has already been created then the following triples should be created:

Child Element Can Occur More than Once

If either of the quantity indicators + or * is used when declaring child elements, the child element can occur more than once. 

Such declarations have the following structure:

In this case, the following triples should be declared:

Optionality for Complex Elements

If a complex element is optional, this is handled by specifying the option Optional VAL YES on the scoped function ElementOptions.

If the element MyChild is declared using the quantity indicator ? the corresponding element occurs at the most once within the scope of its parent. The corresponding DTD declarations have the following structure:

Suppose an entity MyParent has already been created then the following triples should be created:

Complex Elements with Long Names

Complex elements are modeled in the CA Plex model as entities with the same names as their XML element counterparts. However, the maximum length of objects in CA Plex is 32 characters. A complex element with a name longer than 32 characters requires an extra inheritance triple to be created.

Suppose a DTD declaration specifies an element with the name MyLongElementName where MyLongElementName is longer than 32 characters.

First, find a short name (MyShortElementName) to represent the element internally in the CA Plex model.

Now specify triples as specified above, depending on whether or not the element can occur more than once. Use the MyShortElementName when creating the triples.

An extra inheritance triple should now be created:

Inheritance from the abstract LongName entity yields a source code object LongName scoped to MyShortElementName.

In the large property of this source code object specify the long name of the element (MyLongElementName). 

Example

Consider the following DTD and XML document

Let the entitiy equivalent to the XML element with the rather elaborate name ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong inherit from the LongName entity. In the CA Plex model a name that conforms to the CA Plex standards, e.g. ThisElementLong, should be specified for the entity.

The following should be specified in the respective LongName source code object:

ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong

The XML element MyChild is specified exactly as if its parent did not had a long name.

Namespaces for Complex Elements

In order to specify that a complex element belongs to a namespace the entity representing the complex element must inherit from the enity NamespaceAware.

Consider the following DTD and XML document:

To specify that the XML element MyParent belongs in a namespace the following steps must be followed:

1. Add the following triples to the MyParent entity:

2. Source Object	Verb	Target Object
   MyParent	is a ENT	NamespaceAware
   		XmlElement

3. In the source code object MyParent.Namespace specify the name of the namespace: http://www.websydian.com/ns.
4. Optionally specify a prefix for the element in the source code object MyParent.Prefix. Please note that this prefix is only used when creating MyParent elements. In most cases the prefix should be left blank.

Please be aware of that namespace definitions in the XML model are inherited. This means that all descendant elements to MyParent also belongs to the namespace http://www.websydian.com/ns. More information can be found here.

For an introduction to namespaces in TransacXML please refer to this document.

Data Fields and Their Representation in the XML Document

TransacXML supports three representations of data:

• Data in the attributes of an element,
• Data in child elements which have exactly one child, a text node (simple elements),
• A variant of the latter in which child elements can occur more than once within the scope of the parent element.

Information about the individual data fields' representation in the XML document must also be present within the CA Plex model. The three types of data field representation will now be dealt with in turn. 

Data in Attributes

Data represented in attributes have DTD declarations with the following structure:

The keyword #REQUIRED is an optionality keyword indicating that the attribute must be present in the element. The other optionality keyword is #IMPLIED indicating that the attribute is optional in the element. The optionality keywords should be disregarded in the conversion process.

Assuming the MyParent entity has already been created, create triples as specified below. For each of the attributes declared in the ATTLIST declaration for MyParent, create the following triples:

Remember to substitute the actual name of the attribute for AttrDataN when creating the triples. 

Data in Simple Elements

TransacXML uses child elements with a text node as its only child (simple elements) to hold data in equivalence with data in attributes. As was the case with non-simple elements, there are two cases to consider:

Simple Element Occurs at the Most Once

Simple elements occurring at the most once within the scope of their parents are declared using one of the the two following pairs of DTD declarations (The simple element MyChild occurs at the most once):

The pairs are converted equivalently into triples in the CA Plex model.

When converting a particular  DTD, keep in mind that the two declarations in each pair do not necessarily occur as two consecutive declarations in the DTD.

Assuming the entity MyParent has already been created, create triples as specified below to reflect this in the Plex model. For each simple child element create the triples:

Remember to substitute the real name of each element for MyChild when creating the triples.

Simple Elements Can Occur More Than Once

Simple elements which can occur more than once within the scope of their parent elements are declared using one of the two following DTD declaration pairs (The simple element MyChild can occur more than once):

The pairs are converted equivalently into triples in the CA Plex model.

Assuming the entity MyParent has already been created, create triples as specified below to represent repeating simple elements in the Plex model. For each repeating simple child element create the following triples:

Remember to substitute the real name of the child element for MyChild when creating the triples.

Example of implementing and using the RepeatingElementField check the RepeatingElementFieldExample.

Simple Elements are optional

If a simple element is optional, i.e. it can occur zero or once (in the DTD written as ?), or zero or multiple times (written as *), this is represented in the model using the standard Optionality SYS triple:

This is the same for fields inheriting from either ElementField or RepeatingElementField.

Combinations of the Above Data Representations

Often, all three types of data representations described above are present within the scope of the same element. This situation is reflected in the DTD as a combination of the DTD declarations dealt with in the previous sections.

Example

Consider this XML document excerpt:

<!ELEMENT shop (city,employee*)>
<!ELEMENT city (#PCDATA) >

<!ELEMENT employee (#PCDATA) >
<!ATTLIST shop country CDATA #REQUIRED
               name    CDATA #REQUIRED>

Here, the element shop uses both attributes and simple elements to contain data. There are two types of simple elements: The simple element city occurs only once, the element employee occurs more than once. Consequently, the two simple elements city and employee yield different triples in the CA Plex model.

Attributes and Simple Elements with Long Names

The attributes and simple elements declared in the DTD are modeled into fields in the CA Plex model. The model fields carry the same names as those of their DTD counterparts. When a simple element or an attribute is declared which name is longer than 32 characters, an extra inheritance triple has to be created in the CA Plex model.

Suppose a DTD declaration specifies an attribute or a simple element with the name MyLongName where MyLongName is longer than 32 characters.

First, find a short name (MyShortName) to represent the element in the CA Plex model.

Now specify triples as specified above, depending on whether or not the element can occur more than once. Use the MyShortName when creating the triples.

An extra inheritance triple should now be created:

Inheritance from the abstract LongName field yields a source code object LongName scoped to the MyLongName field.

In the large property of the LongName source code specify the real name of the attribute/simple element.

Example

Consider a DTD declaring an element with a long name attribute:

<MyElement ThisAttributeHasANameWellOverThirtyTwoCharactersLong="Data"> </MyElement>

First, a short name ThisAttribute is used as the name of the model field. Then inheritance from the LongName abstract field is specified.

In the large property of the LongName source code object scoped to ThisAttribute, now specify the real long name of the attribute:

ThisAttributeHasANameWellOverThirtyTwoCharactersLong

Namespaces for Attributes and Simple Elements

Namespaces are specified for attributes and simple elements by inheriting from the field NamespaceAware.

Consider the following DTD and XML document:

To specify that AttrData and MySimpleElement belongs to the namespace http://www.websydian.com/ns simply let the fields representing the simple element and attribute inherit from NamespaceAware.

The table below show total set of triples neccessary in order to create the above simple elements and attributes in the given namespace:

The inheritance from the field NamespaceAware will have the effect that two source code objects are scoped to the fields AttrData and MySimpleElement:

1. Namespace
   This source code object should contain the namespace that the field belongs to. In this example this is the URI http://www.websydian.com/ns.
2. Prefix
   This source code object contains the prefix to be used when TransacXML creates attributes/simple elements. In most cases this should be left blank and a value should only be specified if it is required to use a specific prefix.

Although namespaces for attributes and simple elements are specified in exactly the same way there is one fundamental difference: If no namespace is specifed for a simple element, then the simple element will inherit the namespace from the scoping complex element, whereas attributes do not inherit the namespace defintion. More information can be found here.

For an introduction to namespaces in TransacXML please refer to this document.

Specifying Null Value Literals

When retrieving data from an XML document, it may happen that a particular attribute or simple element is not present in the XML document, for instance if it has been declared as optional in the DTD. Optional attributes/simple elements should always be converted into CA Plex fields.

If data corresponding to a particular CA Plex field is not present in the XML document being read,  the field will contain a null value when execution returns from a TransacXML SingleFetch or FlatView call. 

When an attempt is made to retrieve data (using either of the TransacXML functions SingleFetch or FlatView) from an XML element that is not present in the XML document (e.g. because the element is optional), all the data fields specified for that element will contain their respective null values. 

By default, the null value literal is the empty string ( *Blank ). However, the null value literal can be overridden by the Websydian developer. Each field in the entity structure created as a result of the modeling process scopes a value Null. In this value, specify the desired literal to be returned for the field in question.

Example

Take a look at this excerpt from an XML document:

<MyElement>
  <MyOptionalSimpleElement>Data</MyOptionalSimpleElement>
</MyElement>

The modeling process results in an entity MyElement whose Fields function scopes a field MyOptionalSimpleElement. This field has a Null value. Now suppose that the string "MyNullLiteral" has been specified as the literal of the Null value.

If the MyOptionalSimpleElement simple element is not present in an XML document being read, the corresponding CA Plex field will contain the string "MyNullLiteral" when execution returns from the SingleFetch call.

The Choice Construct

This section describes how to convert the choice construct in the DTD into CA Plex triples and objects.

The choice construct looks like this:

<!ELEMENT MyParent (a|b)>

The choice symbol (|) indicates that either a or b can occur as children of MyParent.  

The CA Plex model needs information about which elements it can encounter when retrieving data from the corresponding XML document. In other words, it needs to know the set of all possible choices. Therefore, what should be mapped to the CA Plex model is the union of all elements in the choice construct. In the above example, both of the child elements a and b should be converted into triples in the CA Plex model.

Tables of Conversion

This section contains tables that describe the different cases that can be met in a DTD or existing XML document, and how this is converted into a TransacXML representation in CA Plex.

Create/Process documents

ExportXMLDocument

Inherit from ExportXMLDocument to get a function with the framework of doing exports to XML documents. Combined with ImportXMLDocument the developer is enabled to both import and export XML documents in the same function.

The ExportXMLDocument function takes input regarding the XML document to be created (Filename, encoding, and xml version). If the filename is *blank the function does not save the document to file. Useful when doing Web Services with WsySoap.

E.g.

Please refer to the XML tutorial for an example on how to use ExportXMLDocument.

ImportXMLDocument

Inherit from ImporttXMLDocument to get a function with the framework of doing import from XML documents. Combined with ExportXMLDocument the developer is enabled to both import and export XML documents in the same function.

The ImportXMLDocument function takes input regarding the XML document to be processed (Filename). If the filename is *blank the function does not load any file. Useful when doing Web Services with WsySoap.

E.g.

Please refer to the XML tutorial for an example on how to use ImportXMLDocument.

TraverseAndFetch

The TraverseAndFetch functions are used to navigate through the XML document, fetch all of the data and make the data available in a local variable.

The following triples assumes that an XML document, where the top element is called MyTopElement, has been defined in the Plex model.

Enter the processing needed for the data retrieved for each XMLElement in the edit point Handle Element in the TraverseAndFetch function scoped by the XMLElement.

The function will enter the edit point once for each instance of the XMLElement in the document. The data for the XMLElement is placed in the local variable View.

Generate and build MyTraverseFunction and all of the functions scoped by the XMLElements, which are part of the document if these functions have not already been built.

See the Tutorial for more information concerning the necessary library packages etc. if these have not already been built.

Call the MyTraverseFunction - and the document will be processed.

Transferring parameters

When calling the TraverseAndFetch function of a child element (from TraverseAndFetch function scoped by the parent element) the following local variables are used for mapping the input for the called TraverseAndFetch functions:

1. Local.Reference
2. Local.ParameterData
3. Local.View
4. Input.ParentData

The variable Reference contains the reference to the parent element. This is populated automatically and should never be changed or have fields added.

The variable ParameterData is empty.

The Variable View contains the data read from the current element.

The Input.ParentData variable contains the data transferred from the calling function.

When a TraverseAndFetch function needs a new input parameter do the following:

Add the field/fields to the called TraverseAndFetch function's Input.ParentData variable

If the value should be taken from the parent element nothing further is needed.

If the data should be taken from the Input.ParentData of the calling function nothing further is needed.

If the data is not present in the Input.ParentData or the Local.View - add the field to the Local.ParameterData variable and populate the field in the action diagram.

More Information

Getting started with TrransacXML - 1: Basic XML terms

Getting started with TransacXML - 2: Basic XML structure

Getting started with TransacXML - 3: Modeling XML documents in TransacXML

Getting started with TransacXML - 4: Creating XML documents using TransacXML

Getting started with TransacXML - 5: Reading XML document using TransacXML

DomServices Function Suite

Understanding the ObjectStore

Error handling