TransacXML Tutorial

Introduction    Implementing    Other Uses    Parts    Tutorial    Glossary

Introduction

This tutorial shows how to access an XML document using the Websydian TransacXML patterns. The examples cover the use of core TransacXML functions, that combines import, export, and update functionality.

In Specify XML Export Functionality, an XML document is created and populated with data from a sample database. This process illustrates the export process also shown in the figure below. Also, a more advanced example is shown, where data is exported from the database into an XML document as a result of data imported from another XML document.

In Specify XML Import Functionality, a sample database is populated with data from an XML document. This process is a "test lab equivalent" to the import process shown in the figure below.

The TransacXML module enables the Websydian developer to access data in XML documents using well-known relational database functions such as SingleFetch and ProcessGroup.

Application Context

This tutorial implements functionality being used in the Web Services tutorial. The choice of names and placement of entities and functions might appear strange at first look, but the risk of initial confusion is a trade-off for better integration between the two tutorials.

TransacXML allows the developer to exchange data between XML documents and the application. In this tutorial import and export is demonstrated in simple examples. The functionality created here is then used in the Web Services tutorial to demonstrate the strength of TransacXML when developing Web Services.

The examples in this tutorial has no other purpose than demonstrating import and export capabilities of TransacXML. When used in the Web Services tutorial, however, even these simple examples gain power by allowing a broker to collect data from distributors placed in disparate systems, possibly only connected via the Internet.

It might be of benefit to see the application context description in the Web Services tutorial before continuing with this tutorial.

In this example, the following database entities are used to gather information about Items:

• First, a database entity containing data on the Items possessed by the distributor (see the Web Services tutorial for more on distributor and broker)
• Second, two database entities containing Item data known to the distributor; 
  • one with only name and ID of the item, and
  • another with all information about the contained items

Preparations

The steps performed in this section has to be completed in order to complete the TransacXML tutorial. As a service a local model has been made available for download at the Websydian download area which implements the Sample Database Structure described in this section for Windows. 

Setup a new Plex model and database

Create a new group model and local model as described in the Plex documentation and make sure to attach the following Websydian libraries:

• WSYDom
• WSYXml
• WsySoap

Specify the variant WSYDOM to one of the following variants:

• MSXML (for Windows)
• Java Parser (for Java)

For further information on how to setup the local model please follow the guidelines specified in Setting up your Plex  model.

Make sure to set the variant of the Storage library and create a new database if required, consult the Plex documentation if in need of further information on databases and Plex.

Check XML parser dependencies

In order to work through this tutorial in the Windows version, you need to download the Microsoft XML Parser 4.0 (download the latest version of Microsoft XML Parser 4.0 from the Microsoft web site).

For a Java implementation, TransacXML uses the Xerces XML parser created by the Apache Organization. This parser is included in the Websydian distribution.

Sample Database Structure

A simple database is defined, containing information about items in stock for a distributor. The database is defined by the triples specified below.
 

Specify the following triples to define the Distributor database, the Data entity scopes all database related functionality:

Add the following triples to specify each field:

The broker has two database entities, a simple one containing limited information on items, and a full one containing all information:

Specify the following triples to define the Broker All Items database:

Specify the following triples to define the Broker Returned Items database:

Model the XML documents in the Plex model

In this tutorial you will be implementing the XML documents ItemList and ReturnOffer.

The modeling of the XML document within Plex can be performed from a number of different sources, schemas, DTD or existing XML documents. In this tutorial the modeling will be performed from a number of XML documents and DTD's acting as examples. For further information on modeling your XML documents in your Plex model see the TransacXML implementation guide.

Add the following triples to describe the two XML documents used in this tutorial. Consider taking a look at the Implementation Guide for an understanding of the different objects used to model the XML documents.

First the ItemList XML document

The CommonXML entity scopes the different XML documents.

Then the ReturnOffer XML document

In an application processing several different kinds of XML documents, it may be convenient to scope the XML document representations and functionality to a dedicated entity object (e.g. XmlDocuments).  In this way, the XML entity objects will not be mixed up with the entity objects specifying the application database.

Create a function to import sample data from an XML document

In this step you will be implementing a function that imports an XML document with sample data for your database. The sample XML data document is made available here. Please note there is no error handling in this function.
 

Specify triples to define the ImportSampleData function:

Insert the following action diagram code into the specified Edit Points.  [Action diagram code]

Edit Point Process XML document

Call CommonXML.ReturnOffer.Item.GetFirstOccurrence

  // Map Local/InputDocument<ObjectStoreReference>
  // Map Local/InputDocument<ObjectDocument>

  // Map <ParentElement.NULL>

Go Sub Check error

Set Local/InputDocument<ObjectElement> = CommonXML.ReturnOffer.Item.GetFirstOccurrence/Output<ObjectNode>
While Local/InputDocument<ObjectElement> != <ObjectElement.NULL>

  Call CommonXML.ReturnOffer.Item.SingleFetch

    // Map Local/InputDocument<ObjectStoreReference>
    // Map Local/InputDocument<ObjectElement>

  Go Sub Check error

  Set Local/InputDocument<ObjectElement> = CommonXML.ReturnOffer.Item.SingleFetch/Output<NextOccurrence>
  Cast ItemData<ItemID>, Data<CommonXML.ReturnOffer.Item.Fields.ItemID>
  Cast ItemData<MyName>, Data<CommonXML.ReturnOffer.Item.Fields.Name>
  Cast ItemData<MyPrice>, Data<CommonXML.ReturnOffer.Item.Fields.Price>
  Cast ItemData<Delivery Time>, Data<CommonXML.ReturnOffer.Item.Fields.DeliveryTime>

  Call Data.DistributorA.Item.Update.InsertRow

    // Map ItemData<ItemID>
    // Map ItemData<MyName>
    // Map ItemData<MyPrice>
    // Map ItemData<Delivery Time>

Edit Point Handle error message

Dialog Message Message: OBJECTS/Message
  // Map Environment<*Message text>
 

Pre Point Start load input document
Format Message Message: ImportSampleData.ImportFile, Local/InputDocument<FileName>
 

Set the contents of the ImportFile message to the location of the sample xml file; e.g.  c:\temp\SampleData.xml

Generate and Build Library Packages and functions

It is now time to generate and build functions from the Plex model created in this tutorial.
 

Generate and build the objects contained in the subject area specific for your choice of variant. Please refer to Generate and Build Considerations for more details.

Make sure that the supplied Websydian functions scoped to the following subject areas are generated and build

WSYDOM/DomObjectsToGenerateAndBuild
SDSTRING/SDStringObjsToGenerateAndBuild
WSYXML/XMLObjectsToGenerateAndBuild

Generate and build the following

Everything scoped to Data
Everything scoped to CommonXml

Generate, build, and create an exe file for the function ImportSampleData.

Create Test Data

Run the ImportSampleData function to create a number of sample records.

Specify XML Export Functionality

With the application database and the XML document structure specified in the CA Plex model it is now time to specify the functionality that will export data from the database to an XML document.

In the first example the entire item database will be exported into an XML document conforming to the ItemList XML document.

In the second example, which is a bit more advanced, an external XML document determines which items to be exported. The specified items will be exported into an XML document conforming to the ReturnOffer XML document.

Export of data into ItemList document

In this example, all the items in the Distributor database is exported into a new XML document. Not all available information about the items are exported (Price and DeliveryTime are omitted).

First a function is created which loops over all the items in the database. The function should take a filename as input, allowing the calling function to determine where the resulting XML document should be saved.
 

Declare the fields:

Specify triples to define the ExportItemListToXml function:

Open the action diagram for ExportItemListToXml and insert the following code into the specified edit points and sub routines. [Action diagram code]

Pre Point Subroutines

Sub Create root element

Sub Fetch item data

Sub Error check
 

Pre Point Execute

Go Sub Create root element

Go Sub Fetch item data

Go Sub Terminate
 

Sub Create root element

Set OutputDocument = Input

Call CommonXML.ItemList.InsertRow

  // Map OutputDocument<ObjectStoreReference>
  // Map OutputDocument<ObjectDocument>
  // Map OutputDocument<ObjectDocument>

Go Sub Error check

Set OutputDocument<ObjectElement> = CommonXML.ItemList.InsertRow/Output<ObjectElement>
 

Sub Fetch Item Data

Set Local<ItemID> = <ItemID.*Blank>

Set Local<EndOfView> = <EndOfView.No>

Set Local<Position> = <Position.Tes>

While Local<EndOfView> == <EndOfView.No>

  Call Data.DistributorA.Item.Fetch.BlockFetch

    // Map Local<ItemID>
    // Map Local<Position>
    // Map Local<RowsFetched>

  Set Local<Position> = <Position.No>

  If Environment<*Returned status> IS <State: OBJECTS/*Returned status.*Abnormal>

    Set Local<EndOfView> = <EndOfView.Yes>

  If Local<RowsFetched> >> <RowsFetched.*Zero>

    Set Local<GridRow> = <GridRow.*One>

    While Local<GridRow> <= Local<RowsFetched>

      Use FetchedData, Local<GridRow>

      Cast ItemList<CommonXML.ItemList.Item.Fields.ItemID>, FetchedData<ItemID>

      Cast ItemList<CommonXML.ItemList.Item.Fields.Name>, FetchedData<MyName>

      Call CommonXML.ItemList.Item.InsertRow

        // Map OutputDocument<ObjectStoreReference>

        // Map OutputDocument<ObjectElement>

        // Map OutputDocument<ObjectDocument>

        // Map ItemList<CommonXML.ItemList.Item.Fields.ItemID>

        // Map ItemList<CommonXML.ItemList.Item.Fields.Name>

      Go Sub Error check
      Set Local<GridRow> = Local<GridRow> + <GridRow.*One>

Gub Error check

If Environment<*Returned status> IS <State: OBJECTS/*Returned status.*Abnormal>

  Set Environment<*Returning status> = <*Returning status.*Error>

  Go Sub Terminate

Create a simple wrapper function to run the ExportItemListToXml function:

Set the contents of the OutputDocument message to c:\temp\Request.xml

Open the action diagram for TestExportItemList and insert the following code into the specified edit points and sub routines. [Action diagram code]

Edit Point Process XML document

Call ExportItemListToXml

  // Map Local/OutputDocument<ObjectStoreReference>
  // Map Local/OutputDocument<ObjectDocument>

Format Message Message: TestExportItemList.OutputDocument, Local/OutputDocument<FileName>

Post Point Handle error message

Dialog Message Message: OBJECTS/Message
  // Map Environment<*Message text>

Generate and build the following functions:

ExportItemListToXml
TestExportItemListToXml

Create an exe file for the TestExportItemListToXml function

As a result of running TestExportItemList, the file named Request.xml now exists in c:\temp. The contents of Request.xml is the exported list of items from the DistributorA database.
 

 View the file by opening it in an XML-capable browser. E.g. Internet Explorer

Export of data into ReturnOffer document

In this example, an existing XML document containing a list of items is processed, and a new XML document is created with extended information about each of the items contained in the input document.

Specify triples to define the ExportToReturnOffer

Open the action diagram for ExportToReturnOffer and insert the following code into the specified edit points and sub routines. [Action diagram code]

Pre Point Subroutines

Sub Initialize XML input document

Sub Initialize XML output document

Sub Loop through requested items

Sub Error check
 

Pre Point Execute

Go Sub Initialize XML input document

Go Sub Initialize XML output document

Go Sub Loop through requested items

Go Sub Terminate
 

Sub Initialize XML input document

Set InputDocument = InputDoc

Sub Initialize XML output document

Set OutputDocument = OutputDoc

Call CommonXML.ReturnOffer.InsertRow

  // Map OutputDocument<ObjectStoreReference>
  // Map OutputDocument<ObjectDocument>

  // Map OutputDocument<ObjectDocument>

Go Sub Error check

Set OutputDocument<ObjectElement> = CommonXML.ReturnOffer.InsertRow/Output<ObjectElement>

Sub Loop through requested items

Call CommonXML.ItemList.Item.GetFirstOccurrence

  // Map InputDocument<ObjectStoreReference>
  // Map InputDocument<ObjectDocument>

  // Map <ParentElement.NULL>

Set InputDocument<ObjectElement> = CommonXML.ItemList.Item.GetFirstOccurrence/Output<ObjectNode>

Go Sub Error check

While InputDocument<ObjectElement> != <ObjectElement.NULL>

  Call CommonXML.ItemList.Item.SingleFetch

    // Map InputDocument<ObjectStoreReference>
    // Map InputDocument<ObjectElement>

  Set InputDocument<ObjectElement> = CommonXML.ItemList.Item.SingleFetch/Output<NextOccurrence>

  Go Sub Error check

  Cast Local<ItemID>, Data<CommonXML.ItemList.Item.Fields.ItemID>

  Call Data.DistributorA.Item.Fetch.SingleFetch

    // Map Local<ItemID>

  Go Sub Error check

  Cast OutputDocument<CommonXML.ReturnOffer.Item.Fields.DeliveryTime>, FetchedData<Delivery Time>

  Cast OutputDocument<CommonXML.ReturnOffer.Item.Fields.ItemID>, FetchedData<ItemID>

  Cast OutputDocument<CommonXML.ReturnOffer.Item.Fields.Name>, FetchedData<MyName>

  Cast OutputDocument<CommonXML.ReturnOffer.Item.Fields.Price>, FetchedData<MyPrice>

  Call CommonXML.ReturnOffer.Item.InsertRow

    // Map OutputDocument<ObjectStoreReference>

    // Map OutputDocument<ObjectElement>

    // Map OutputDocument<ObjectDocument>

    // Map OutputDocument<CommonXML.ReturnOffer.Item.Fields.DeliveryTime>

    // Map OutputDocument<CommonXML.ReturnOffer.Item.Fields.ItemID>
    // Map OutputDocument<CommonXML.ReturnOffer.Item.Fields.Name>
    // Map OutputDocument<CommonXML.ReturnOffer.Item.Fields.Price>

  Go Sub Error check

Sub Error check

If Environment<*Returned status> IS <State: OBJECTS/*Returned status.*Abnormal>

  Set Environment<*Returning status> = <*Returning status.*Error>

  Go Sub Terminate
 

Create a simple wrapper function to test the ExportToReturnOffer function:

Specify the contents of the InputDocument message to c:\temp\Request.xml

Specify the contents of the OutputDocument message to c:\temp\Response.xml

Open the action diagram for TestExportToReturnOffer and insert the following code into the specified edit points and sub routines. [Action diagram code]

Edit Point Process XML document

Call ExportToReturnOffer

  // Map Local/InputDocument<ObjectStoreReference>
  // Map Local/InputDocument<ObjectDocument>

  // Map Local/OutputDocument<ObjectStoreReference>
  // Map Local/OutputDocument<ObjectDocument>

Format Message Message: TestExportToReturnOffer.OutputDocument, Local/OutputDocument<FileName>

Pre Point Start load input document

Format Message Message: TestExportToReturnOffer.InputDocument, Local/InputDocument<FileName>

Post Point Handle error message

Dialog Message Message: OBJECTS/Message
  // Map Environment<*Message text>

Generate and build the following functions:

ExportToReturnOffer
TestExportToReturnOffer

Create an exe file for the TestExportToReturnOffer function

As a result of running TestExport, the file named Response.xml now exists in c:\temp.

 View the file by opening it in an XML-capable browser. E.g. Internet Explorer

Specify XML Import Functionality

In this part, functionality is specified that will import data from the XML documents created in the previous part into the Broker database.

Two examples are shown; one that imports from an XML document conforming to the ItemList XML document, and another that imports from an XML document conforming to the ReturnOffer XML document.

Import of data from ItemList document

It is now time to specify the functionality which will read and process an XML document conforming to the ItemList XML document, creating corresponding records in the Broker database.

Specify triples to define the CommonXML.ItemList.Item.BrokerProcessGroup function:

Open the action diagram for CommonXML.ItemList.Item.BrokerProcessGroup and insert the following code into the specified edit points and sub routines. [Action diagram code]

Edit Point Process element

Call CommonXML.ItemList.Item.SingleFetch

  // Map Input<ObjectStoreReference>
  // Map CurrentElement<ObjectElement>

Call Meta.CheckDOMCallError

Cast ItemData<ItemID>, CommonXML.ItemList.Item.SingleFetch/Data<CommonXML.ItemList.Item.Fields.ItemID>

Cast ItemData<MyName>, CommonXML.ItemList.Item.SingleFetch/Data<CommonXML.ItemList.Item.Fields.Name>

Call Data.Broker.All Items.Update.InsertRow

  // Map ItemData<ItemID>
  // Map ItemData<MyName>

Call Meta.CheckDOMCallError
 

Specify triples to define the ImportItemListFromXml function:

Open the action diagram for ImportItemListFromXml and insert the following code into the specified edit points and sub routines. [Action diagram code]

Pre Point Subroutines   

Sub Error check

  If Environment<*Returned status> IS <State: OBJECTS/*Returned status.*Abnormal>

    Call DomServices.ErrorPop
    While DomServices.ErrorPop/Output<ExceptionCode2> IS <State: WSYDOM/ExceptionCode2.NO_EXCEPTION>

      Cast Environment<*Message text>, DomServices.ErrorPop/Output<ErrorDescription>

      Call DomServices.ErrorPop
    Set Environment<*Returning status> = <*Returning status.*Error>
    Go Sub Terminate
 

Edit Point Execute

Set InputDocument = InputDoc

Call CommonXML.ItemList.GetFirstOccurrence

  // Map InputDocument<ObjectStoreReference>
  // Map InputDocument<ObjectDocument>

  // Map <ParentElement.NULL>

Go Sub Error check

Set InputDocument<ObjectElement> = CommonXML.ItemList.GetFirstOccurrence/Output<ObjectNode>
Call CommonXML.ItemList.Item.BrokerProcessGroup

  // Map InputDocument<ObjectStoreReference>
  // Map InputDocument<ObjectElement>
Go Sub Error check

Go Sub Terminate
 

Create a simple wrapper function to run the ImportItemListFromXml function:

Specify the contents of the InputDocument message to c:\temp\Request.xml

Open the action diagram for TestImportItemList and insert the following code into the specified edit points and sub routines. [Action diagram code]

Edit Point Process XML document

Call ImportItemListFromXML

  // Local/InputDocument<ObjectStoreReference>
  // Local/InputDocument<ObjectDocument>

Pre Point Start load input document
Format Message Message: TestImportItemList.InputDocument, Local/InputDocument<FileName>

Generate and build the following functions:

CommonXML.ItemList.Item.BrokerProcessGroup
ImportItemListFromXML
TestImportItemList

Make sure creating an exe file for the TestImportItemList as well

As a result of running TestImportItemList, the items listed in the Request.xml file should now be in the Broker All Items database.

Import of data from ReturnOffer document

This example is almost identical to the first example, the only difference being the structure of the input document, and the number of fields imported for each item.

Specify triples to define the CommonXML.ReturnOffer.Item.BrokerProcessGroup function:

Open the action diagram for BrokerProcessGroup and insert the following code in the Edit Point Process element. [Action diagram code]

Edit Point Process element

Call CommonXML.ReturnOffer.Item.SingleFetch

  // Map Input<ObjectStoreReference>
  // Map CurrentElement<ObjectElement>

Call Meta.CheckDOMCallError

Cast ItemData<ItemID>, CommonXML.ReturnOffer.Item.SingleFetch/Data<CommonXML.ReturnOffer.Item.Fields.ItemID>
Cast ItemData<MyName>, CommonXML.ReturnOffer.Item.SingleFetch/Data<CommonXML.ReturnOffer.Item.Fields.Name>
Cast ItemData<MyPrice>, CommonXML.ReturnOffer.Item.SingleFetch/Data<CommonXML.ReturnOffer.Item.Fields.Price>
Cast ItemData<Delivery Time>, CommonXML.ReturnOffer.Item.SingleFetch/Data<CommonXML.ReturnOffer.Item.Fields.DeliveryTime>
Call Data.Broker.Returned Items.Update.InsertRow

  // Map ItemData<ItemID>
  // Map ItemData<MyName>
  // Map ItemData<MyPrice>
  // Map ItemData<Delivery Time>

Specify triples to define the ImportReturnOfferFromXml function:

Open the action diagram for ImportReturnOfferFromXml and insert the following code into the specified edit points and sub routines. [Action diagram code]

Pre Point Subroutines

Sub Error Check
If Environment<*Returned status> IS <State: OBJECTS/*Returned status.*Abnormal>
  Call DomServices.ErrorPop
  While DomServices.ErrorPop/Output<ExceptionCode2> IS <State: WSYDOM/ExceptionCode2.NO_EXCEPTION>
    Cast Environment<*Message text>, DomServices.ErrorPop/Output<ErrorDescription>
    Dialog Message Message: OBJECTS/Message
    Edit Point Handle error message
    Call DomServices.ErrorPop
  Set Environment<*Returning status> = <*Returning status.*Error>
  Go Sub Terminate
 

Edit Point Execute

Set InputDocument = InputDoc

Call CommonXML.ReturnOffer.GetFirstOccurrence

  // Map InputDocument<ObjectStoreReference>
  // Map InputDocument<ObjectDocument>

Set InputDocument<ObjectElement> = CommonXML.ReturnOffer.GetFirstOccurrence/Output<ObjectNode>
Go Sub Error check

Call CommonXML.ReturnOffer.Item.BrokerProcessGroup

  // Map InputDocument<ObjectStoreReference>
  // Map InputDocument<ObjectElement>

Go Sub Error check

Go Sub Terminate

Create a simple wrapper function to run the ImportItemListFromXml function:

Specify the contents of the InputDocument  message to c:\temp\Response.xml

Open the action diagram for TestImportReturnOffer and insert the following code into the specified edit points and sub routines. [Action diagram code]

Edit Point Process XML document

Call ImportReturnOfferFromXML

  // Map Local/InputDocument<ObjectStoreReference>
  // Map Local/InputDocument<ObjectDocument>

Pre Point Start load input document
Format Message Message: TestImportReturnOffer.InputDocument, Local/InputDocument<FileName>
 

Generate and build the following functions:

CommonXML.ReturnOffer.Item.BrokerProcessGroup
ImportReturnOfferFromXML
TestImportReturnOffer

Make sure creating an exe file for the TestImportReturnOffer as well

As a result of running TestImportReturnOffer, the items listed in the Response.xml file should now be in the Broker Returned Items database.