Web Services Custom Resource (prior to V3.3)
Overview
Components
Creating a Web Services
Custom Resource
Resource Parameters
SOAP Faults
Implemented
Script Verbs
Namespaces
XML Schema Imports
Web Services Custom Resource
Java File
Importing a WSDL File
Session Management
See
also:
XMLRequestResponseCustomResource
Understanding
Ebase Integration
!! Use of WebServicesCustomResource is
deprecated and this documentation is provided to support forms created prior to
Ebase V3.3. New forms requiring access to XML or Web Services should use XML Resources.
Web Services Custom Resource is an extension of XMLCustomResource. Web Services are a means of transferring XML Data between client and server machines. Web Services is written using the Apache Axis and implements SOAP (a specification maintained by the w3C) using their API. For more information on XML and SOAP, see XML and SOAP documentation.
The Web Services Custom Resource only supports Request and Response communications. Ebase sends a SOAP request message and receives a response. The response is the processed by Ebase and maps the XML elements back to the Ebase form.
Web Services Custom Resource is very flexible and supports most common features required to implement Web Services, including sending request message, receiving response message, SOAP Actions, SOAP Faults and Namespaces. Web Services Custom Resource only supports transferring data via HTTP (HyperText Transfer protocol).
Web Services Custom Resource is not deployed with the standard Ebase application and is available from the Ebase website.
The following components comprise the Web Services Custom Resource:
- The custom resource specification in the
designer:
IT elements/External resources/Custom resources/WebServicesCustomResource - The implementation jar file containing the Java
class used by this resource:
ebaseCustomResource.jar which contains WebServicesCustomResource class file. - Apache Axis binary files used for the
implementation of SOAP messaging:
axis.jar, commons-discovery-0.2.jar, saaj.jar and wsdl4j-1.5.1.jar.
Creating a Web Services Custom Resource
Web Services Custom Resource is an extension of XMLCustomResource and supports all the functionality of the XML Custom Resource. Web Services custom resource inherits all the Namespace functionality from the XML Custom Resource. Web Services Custom Resource also supports SOAPAction and SOAPFault (see SOAPFault section). Web Services Custom Resource only supports HTTP calls. HTTP is the most common way to communicate to a web service. This is a synchronous service call and the resource expects a response from the web service called. This resource does not support a fire and forget web service call.
A new Custom Resource must be implemented for each Web Service call required. The request and response root fields must be configured in the 'Resource Parameter Fields' panel. These map to the structure configured within the 'Resource Fields' panel. This is distinguish between the request and the response root elements when mapping resource fields to form fields.
To create a new Web Services Custom Resource, create a new Custom Resource from the file menu: File/New/External resources/Custom Resource:
- Give the Web Service a name based upon its purpose.
- Enter WebServicesCustomResource in the implementing class name dialog box.
You can either import the XML structure using an XML Schema file or enter manually. N.B. The root element for the request and response must be entered into the Resource Parameters panel.
Web Service schemas
are usually published with the URL required to call
the web service:
The Web Service description shows how to communicate and describes the Request, Response and SOAPAction required to call the service. The image above shows the SOAP request for SOAP 1.1 and 1.2 required XML structure required to call the HelloWorld service.
The SOAP Message is broken into 2 parts. The first part for each SOAP standard is broken into request message sent to the server including the SOAPAction that is a required mime header for this service (this is configured within the resource parameter panel) and the request XML message. The second part is the expected response if not a SOAPFault.
N.B The example above contains a default namespace of 'http://ebasetech.com/webservices' that is configured in the default namespaces textfield of resource parameters panel.
Enter the structure based on the service in the resource fields panel and enter the namespaces and SOAPAction (if applicable): in the resource parameters panel. Enter the Target HTTP URL into the 'Target URL' textfield:
Create the form and import resource field from the custom resource. For more information on custom resources see custom resource section.
Resource Parameters
Web Services Custom
Resource supports 8 parameters. The following table describes the configurable
Resource Parameters as defined by the Web Services Custom Resource.
|
Resource Parameter |
Description |
|
Namespaces (default) |
see XMLCustomResource
for a detailed description |
|
Namespaces (prefixed) |
see XMLCustomResource
for a detailed description |
|
Request Root Field |
Root element of the SOAPBody in the
request document |
|
Response Root Field |
Root element of the SOAPBody in the
response document |
|
SOAP Action |
This is an optional parameter that should
be set if the web service call requires this. This is usually required for
routing purposes in .Net web services. This will be defined within the WSDL
file is required and automatically imported if the web service is imported
using the Import from WSDL
functionality. |
|
SOAP Fault Root Field |
The root element of SOAPFault element if
an error is returned from the server or generated by the Web Services Custom
Resource (e.g cannot create connection to server). This should default to Fault.
see SOAP Faults. |
|
Target URL |
Endpoint URL that the Web Service Custom
Resource calls. |
|
XML Encoded |
Optional flag that can be set to Y
or Yes if the SOAP Response Document contains XML Encoded data. If the
XML is encoded (e.g <xmlElement>Some
Data</xmlElement> this parameter should be set to decode the
XML Response to <xmlElement>Some Data</xmlElement>. If the XML is
not encoded then this parameter can be left blank. |
SOAP Faults
SOAPFault is a special response from the Client or Server when an error occurs when invoking the web service. There are typically two kinds of fault codes:
- soap:Client : Client side error.
- soap:Server: Server side error.
A Web Services SOAPFault consists of 4 elements:
- faultcode: typically soapClient or soap:Server
- faultstring: description of the error
- faultactor: Server URL processing the request
- detail: This can contain many elements
customizing the error detail: e.g
<detail>
<errorCode>000001</errorCode>
<error>Could not determine element HelloData</error>
</detail>
The SOAPFault structure must be added to the Resource Fields Panel if you require these to be mapped back to the form fields in the Ebase Forms Designer. The SOAPFault structure is defined in the SOAP specification.
Implemented Script Verbs
Web Services Custom
Resource supports the script verb call.
A Web Services Custom Resource can be invoked from a script by calling:
|
FPL: |
API based language
(Javascript): |
|
call
<custom-resource-name>; |
resources.<custom-resource-name>.call(); |
Web Services Custom
Resource also supports the following script statements 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.
Web Services Custom Resource implements the namespace implementation from XMLCustomResource. The example above demonstrates how to configure a .Net web service call using default namespaces (typical .Net configuration).
For more information configuring Web Services that support namespaces see XMLCustomResource.
An XML Schema can be imported in the same way as the XMLCustomResource. A schema is often available with the Web Services WSDL (Web Services Definition Language) file. This is published with the Web Service to describe the XML structure of the request/response available to the web service.
For more information on how to import an XML structure from an XML Schema file, see XMLCustomResource.
Web Services Custom Resource Java File
WebServicesCustomResource.class is deployed within a separate jar file and is contained within ebaseCustomResource.jar. The jar is available from Ebase as a seperate package from the Ebase application.
Web Services Custom Resource extends XMLCustomResource and supports all the implemented functionality from the XMLCustomResource.class. WebServicesCustomResource implements the Apache AXIS API to create and send SOAP messages.
AXIS currently supports SOAP 1.2, but SOAP 1.1 is more widely used.
The Web Services Custom Resource allows you to automatically import a Web Service Definition Language (WSDL) File from either:
· A URL e.g http://www.ebase.com/mywebservice/service.asmx?WSDL
· A local file e.g c:\mywebservices\service.wsdl
When importing a WSDL from a http location, the URL must resolve to the actual WSDL definition of the web service. In the example above, the URL shows a link to a .Net web service. The URL has ?WSDL appended onto the http web service location, which resolves to the WSDL file for that particular service.
Note: ?WSDL may not apply for non .Net web services.
To import from a WSDL file/url, click the 'Import from WSDL' button on the Web Services Custom Resource Panel.
1. Enter a URL or the filename to the WSDL file (as described at the beginning of this section) into the URL textfield.
2. Select 'Get WSDL' Button
3. In the left hand panel a list of the available Web Service operations imported from the WSDL will display into a tree. The tree structure shows the available web service operations under the supported SOAP version.
4. Select the Web Service operation you would like to import. When selecting a web service operation, the SOAPAction, SOAP Input (request) and SOAP Output (response) fields will automatically update. In the SOAP Input field, the request message to send to the server is displayed. In the SOAP Output field, the response message from the server is displayed. The SOAPAction field will populate (if applicable) for this web service These fields are for information purposes only and cannot be edited.
5. Select the 'Import from WSDL' button to import the selected web service operation or select the 'Close' button to cancel the import.
6. Your web service resource will automatically populate including the Resource Parameters at the top of the web services custom resource panel. A default SOAP fault will automatically create for you. This is a standard SOAP fault representation and should not need to be edited.
7. Save the web service resource.
Occasionally web services require session id management between the Ebase server and the web service provider. A typical use of session management is when a login is required before any other calls can be made to the web service. If a successful login is achieved then a session ID is written back in the form a HTTP Header field "Set-Cookie". The sesssion ID is stored on the form and used for all proceeding calls the to web server which is written on the request "Cookie" HTTP header. This value is then used by the Web Service to authenticate the session ID to allow the web service request to continue.