Working With XML and SOAP Web Services Resources

What is an XML resource?

An XML resource provides access from an Ebase Xi form to XML data from a variety of sources. This documentation applies to both XML Resources and SOAP Web Services Resources. The term XML Resource used below applies to either an XML Resource or a SOAP Web Services Resource.

How the resource works

An XML resource can be configured with any number of documents, each one capable of holding a single XML document. When an Ebase Xi form is run, these documents are populated with XML using form field values, or via an XML resource adapter. XML resource adapters have the job of transporting XML to and from external systems such as SOAP web services. An XML resource can be set up with any number of fields and tables providing forms with access to the XML data. Normally a field or table is bound to a location within an XML document using an XPath expression. This allows data from anywhere in an XML document to be exposed as a simple field value or table. Script statements are used to move data between an XML resource and a form. Script expressions are used to invoke a specific adapter as shown below.

See XML Resource Concepts for full details.

Learning to use the XML resource

This section presents an introduction to use of the XML resource.

1. Use the import wizards to set up a resource.

The XML resource works best when used with a well defined XML Schema or WSDL. Wizards are included that can import an XML schema (xsd file) or WSDL (wsdl file) and perform most, if not all, of the steps necessary to build a resource. Where insufficient schema information is provided, the resource has to be configured manually and a greater understanding of the XML resource is required.

The first tutorial introduces the necessary steps to set up a web service resource using the Import WSDL feature.

2. Modify or add new fields.

The import mechanism attaches fields and tables to the structure of an XML document. It is quite likely that some of these will not be required and that others will need to be adjusted or augmented. Extra fields may be attached and redundant fields may be detached by hand in the document structure view.

3. Advanced use

A field may also use an XPath statement to perform a query on the XML data. Familiarity with the basics of XPath is recommended, especially XPath location paths and predicates (e.g. /plants/plant[@colour=red]/flowerSize). Tutorial 2 steps through adding a column to a table. It also demonstrates the use of variables in XPath expressions.

Further information can be found in the documents listed above.

Advanced use of the XML resource requires a good understanding of XML, XPath and XML Schema. Knowledge of XSLT is a prerequisite for use of the XSL Transform adapter.

Specifications for many XML technologies can be found at http://www.w3.org/. http://www.w3schools.com/ has some excellent tutorials on XML subjects. Otherwise, please refer to one of the numerous XML information resources.

Script expressions

Between Resource and External system

All adapters are invoked via a simple script command. This takes the form:

FPL:

API based language (Javascript):

command resource_name 'adapter_name';

resources.resource_name.command(adapter_name);

command - The command is specific to the adapter type. For example, file adapters have two commands, read and write. See XML Resource Adapters for details of individual adapters

resource_name – the name of the resource.

adapter_name – the name of the adapter. Omit to invoke the default adapter.

Examples:

1. To write a file from an XML resource called MYRESOURCE with a File Adapter called MyFileAdapter:

FPL:

API based language (Javascript):

write MYRESOURCE 'MyFileAdapter';

resources.MYRESOURCE.write("MyFileAdapter");

2. To call a web service from a Web Service resource called MYWSRESOURCE with a default web service adapter:

FPL:

API based language (Javascript):

call MYWSRESOURCE;

resources.MYWSRESOURCE.call();

Between Form and Resource

Resource fields can be mapped to form fields in exactly the same way as other Ebase resources. Use the FPL commands fetch and update or API methods DatabaseResource.fetch() and DatabaseResource.update() to read and write mapped form field values.

i.e.

To read all resource field values in an XML resource called ANXMLRESOURCE:

FPL:

API based language (Javascript):

fetch ANXMLRESOURCE;

resources.ANXMLRESOURCE.fetch();

To write resource field values to an XML resource called ANXMLRESOURCE:

FPL:

API based language (Javascript):

update ANXMLRESOURCE;

resources.ANXMLRESOURCE.update();

Note: Many of the XML resource adapters perform FETCH and UPDATE automatically and this does not need to be specifically coded. Please refer to individual adapter documentation

Form tables can be backed by resource tables in exactly the same way as other Ebase resource. Use the FPL commands fetchtable and updatetable or API methods Table.fetchTable() and Table.updateTable() to read and write mapped form table values.

i.e.

To read values for a table called 'ALLITEMS' from its backing XML resource:

FPL:

API based language (Javascript):

fetchtable ALLITEMS;

tables.ALLITEMS.fetchTable();

To write values for a table called 'ALLITEMS' to its backing XML resource:

FPL:

API based language (Javascript):

updatetable ALLITEMS;

tables.ALLITEMS.updateTable();

Comparison to other resources

Adapters

The XML resource makes use of adapters. This is important owing to the large number of backend systems that communicate with XML.

Local storage

The XML resource keeps a local copy of the XML documents, whereas many other resources pass their data straight through to the form or external system. Consequently, communication is a two-stage process:

1. Between the external system and the resource.

2. Between the resource and the form.

Multiple tables and fields

An XML resource can have any number of tables and fields. Many other resources support fields only, or a single table.

Internal query expressions (XPath)

The way in which resource fields are bound to XML using XPath adds extra indirection. This increases the power and flexibility of the resource, but it also adds to its complexity. The mechanism can be compared to queries in a database resource. However the query is performed on the local XML data, rather than the remote system.