XML Custom Resource

XMLRequestResponseCustomResource

Overview
Components
Creating an XML Request Response Custom Resource Specification
XML Custom Resource, Resource Parameters
Implemented FPL script commands
Namespaces
XML Schema Import

See also:

XML Concepts

Working with Custom Resources
XMLCustomResource

WebServicesCustomResource

How Resources Work

Overview

XMLRequestResponseCustomResource is a java class deployed with Ebase Server to integrate reading and writing XML Documents via HTTP into Ebase forms. XMLRequestResponseCustomResource is an extension to the XMLCustomResource class. The XMLRequestResponseCustomResource allows importing of multiple XSD (XML Schema Definition) files into the Custom Resource panel and mapping resource the fields to a form. The major difference between this custom resource and the XMLCustomResource is that you can import multiple XSD schemas and write the XML to a HTTP connection using either a HTTP POST or HTTP GET method. You can specify whether to write the XML to a HTTP as a parameter (e.g similar to a HTML FORM parameter) or as an XML message to a HTTP connection. The custom resource does not support writing XML to a file.

XMLRequestResponseCustomResource supports the CALL command using a script. This is an extension of CustomResource and may not provide some functionally required. If extra functionality is required then please read the section on creating a CustomResource.

Components

The following items comprise this XML custom resource:

1. The custom resource specification in Ebase Designer:
Shared/Resources/Custom_resources

2. The java implementation jar file containing the java class used by this resource:
ebaseCustomResource.jar which contains XMLRequestResponseCustomResource.class used for this particular custom resource.

Creating an XML Request Response Custom Resource Specification

This section demonstrates how to create a new XML Request Response Custom Resource.

1. Right click in the designer tree, select New > Custom Resource

2. Enter the name for the Custom Resource and the name of the implementing Custom Source class. For this particular resource type: XMLRequestResponseCustomResource

3. You will be presented with an empty Custom Resource template to enter the configuration information for this resource. Enter the configuration details specific for your custom resource. For more information on XMLRequestResponseCustomResource parameters see XML Custom Resource, Resource Parameters section.

4. Enter the XML structure into the Resource Fields section manually by right clicking the Root and selecting Add Child. Enter the name of the XML Element and repeat this process until the entire XML for each of the Request and Response messages is complete. Alternatively you can import the Request and Response messages from a single XSD or multiple XSD's. To import the structure from an appropriate XSD see section XML Schema Import. The Request Root Field and Response Root Field, configured in the Resource Parameters panel must match the Child node elements configured in the Resource Fields panel directly underneath the Root node.

Save the Resource.

5. Note: This resource is a Request/Response resource and requires Request and Response XML configuration. You must configure both for this particular resource. When called from a script, the request message is sent to the recipient server as defined in the Resource Fields. The request message is known to be the request XML by mapping the Request Root node to the root of the request. This resource always expects a response message from the server and the response XML has to be predefined and mapped to the Response Root Field.

XML Custom Resource, Resource Parameters

XML Custom Resource supports seven Custom Resource parameters.

1. Http Method: Specify either POST or GET to set this call to either HTTP POST or HTTP GET as you would in an HTTP Form.

2. Namespaces (Default): A list of default namespaces that can be mapped to an element in the resource fields panel. See Namespaces section in this document for more information on how to use namespaces..

3. Namespaces (Prefixed): A list of prefixed namespaces that can be mapped to an element in the resource fields panel. See Namespaces section in this document for more information on how to use namespaces.

4. Parameter Name: If you require the XML to be sent as a HTTP parameter field then specify the name of this parameter. If this value is set then the XML will be written onto the Target URL as:

http://myservice.com/service1/xml.jsp?XMLParameter=<MyXMLContent>....</MyXMLContent>.

If the Parameter Name is not specified then the Request XML is written directly down the HTTP connection stream.

5. Request Root Field: Name of the first child element (root element) of the Request XML message.

6. Response Root Field: Name of the first child element (root element) of the Response XML message.

7. Target URL: HTTP URL to write the XML data to. e.g a Java servlet or JSP file.

Implemented script commands

XML Custom Resource supports only the CALL script command. This is displayed as read only and cannot be altered.

To call the XML Custom Resource from a script, it is invoked in the same way as any other external resource e.g databases:

FPL:

API based language (Javascript):

call XMLREQRESEXAMPLE;

resources.XMLREQRESEXAMPLE.executeCommand(CustomResource.COMMAND_CALL);

XML Custom Resource also supports the following FPL script to update and retrieve table data:

FPL:

API based language (Javascript):

fetchtable <tablename>;
updatetable <tablename>;

tables.<tablename>.fetchTable();
tables.<tablename>.updateTable();

For more on how using tables with a custom resource, see custom resource.

Namespaces

XML Custom Resource supports namespaces associated with an element. Using the Resource Parameters panel you can configure either default namespaces (no prefix) or prefixed namespaces.

(See XML Concepts for more information)

Configuring Namespaces in the Resource

The Namespaces (Default) and Namespaces (Prefixed) can be entered as a list of URLs delimited with a ','. The URI must be associated with a prefix regardless of whether prefix is used (default namespaces will omit the prefix). To add a namespace to either default or prefixed namespace, enter the following into the relevant text field: <prefix>=<uri> and to add more than one enter : <prefix>=<uri>,<prefix>=<uri>,<prefix>=<uri> etc...

e.g to configure two prefixed namespaces, the following namespace configuration would be entered into the Namespaces (Prefixed) text field:

po=http://www.somecomapany.com/order/po,addr=http://www.somecompany.com/order/addr

Or to configure one default namespace, the following configuration would be entered into the Namespaces (Default) text field:

d=http://www.somecompany.com/order/purchaseorder

Mapping Namespace to element

To map the namespace to the appropriate element, add the prefix to the beginning of the External Name for the element configured in the Resource Fields Panel and separate using ':'. The prefix will then be associated with that element.

e.g to associate a namespace to an element with the name PurchaseOrder and Address edit the External Name in the Resource Fields Panel:

po:PurchaseOrder
addr:Address

N.B. When assigning prefixed namespaces, you should associate all child elements with the same prefix as its parent. When assigning default namespaces to an element, the namespace is automatically inherited by all the children of namespace element.

XML Schema Import

It is possible to import from an XML Schema using the 'import from XML Schema' button.

Using the import from XML Schema, automatically populates the Resource Fields panel. To import from an XML Schema click the 'Import from XML Schema' Button:

1. Select the XML Schema file to import. N.B Must be well formed and have a file extension of .xsd

2. Select the Elements that you would like to import

3. Click OK

4. To add other XSD documents repeat the steps 1-3.