See also Working with REST Web Services
The following
documentation is available for XML and Web Service resources:
This page provides an overview of the
facilities available using XML Resources and SOAP Web Services Resources. Links from this document present more
detailed information.
Learning to use the XML resource
An XML resource provides access from
a Verj.io 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.
An XML resource can be configured with any number of documents, each one capable of holding a single XML document. When a Verj.io 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.
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.
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(); |
Resource fields can be mapped to form fields in exactly the same way as other Verj.io 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 Verj.io 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(); |
The XML resource makes use of adapters. This is important owing to the large number of backend systems that communicate with XML.
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.
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.