Web Service Adapter

Documentation home

 

Configuring the Web Service Adapter 1

Document and RPC style web services 4

Handling Errors 4

SOAP Faults 5

Maintain Session. 6

Testing the Web Service. 6

Web Services over HTTPS. 8

 

 

Configuring the Web Service Adapter

 

The web service adapter currently supports web services using two-way literal SOAP messages.  (SOAP encoding is not supported)

 

 

 

Target URL – target URL of web service, as specified by a wsdl's <soap:address location> attribute. Target URL supports substitutable parameters. See substitutable parameters section for more details.

SOAP Action – If the target web service requires a SOAP action, it can be set here. SOAP Action supports substitutable parameters. See substitutable parameters section for more details.

Soap Version – The web service resource supports SOAP 1.1 or SOAP 1.2.

Character Encoding – Sets the character encoding type for the request and response document.  If the value is left blank, UTF-8 is assumed.   This is an editable combo with a list of common encoding types available, but you can add your own if applicable.

Response Timeout - Time to wait in seconds for a response, once a remote connection has been made. If no response is returned within the configured timeout the web service client generates an error. The default is 60 seconds if no value is specified. Specifying 0, the web service client will wait indefinitely. NB – Response timeout is not applicable when testing the web service adapter.

Treat SOAP fault as error – Determines how SOAP Faults are handled. When using an API programming language such as Javascript, it is recommended that this option is not selected. When using FPL, if this option is selected then the calling form/service/workflow process will abort and an error page will be displayed (forms only); if unselected, $COMMAND_STATUS is set to ERROR and the application can interrogate the SOAP fault document fields if this is required.  Regardless of this setting, the response document will remain unchanged and the fault message will be written to the fault document.  Click here for more details of error handling and SOAP Faults.

Maintain Session – When checked, the session cookies for the web service are stored for the lifetime of the Form. See Maintain Session.

 

Request Body – Choose a request document.   This will be wrapped in the outbound SOAP message, which is sent to the target web service.

Request Headers – Select the documents to be added as Headers to the outbound SOAP message.  Headers may be added , removed , moved up  or down .

Response Body – Choose a response document.   The body of the inbound SOAP message will be extracted and written to this document.

Response Headers – Select the documents to be added as Headers to the inbound SOAP message.  Headers may be added , removed , moved up  or down .

Fault Document – Choose a fault document.  If the web service request results in a SOAP fault, it will be written to this document.

 

Debug – When checked, the inbound and outbound SOAP messages are logged.

 

Import WSDL – see Importing from a WSDL

Configure WSS – see WS Security

Configure WS-Addressing – see WS-Addressing

Test Web Service – see below

 

The web service is invoked using the CALL script command.

 

Example:

To call the web service configured in the 'myWebServiceAdapter' adapter of resource 'WS1':

 

FPL:

API based language (Javascript):

 

call WS1 'myWebServiceAdapter';

 

 

resources.WS1.call("myWebServiceAdapter");

 

Before a CALL command, an UPDATE command is automatically executed (i.e. non tabular field data is transferred from the form to the resource).

After a CALL command, a FETCH command is automatically executed (i.e. non tabular field data is transferred to the form from the resource).

 

 

Document and RPC style web services

The web services adapter does not distinguish between Document and RPC web service styles.  It simply places the request document in the SOAP Body.  The structures of the request and response documents must therefore be correct for the style of web service being invoked.  The Import WSDL wizard generates the required structures for either style.

 

Handling Errors

If any error occurs, a SOAP Fault document is returned. This includes both an explicit SOAP Fault returned by the called web service and a client fault caused by some sort of communication failure. This SOAP Fault can be interrogated by the application if required.

 

Errors are handled differently depending on the scripting language used:

 

FPL:

The web services adapter returns a status code in system variable $COMMAND_STATUS.

 

  1. OK – web service call invoked successfully
  2. ERROR – web service call is unsuccessful and returned a SOAP Fault. This is only applicable if Treat SOAP fault as error is false. If this flag is true, the form will abort.
  3. NOT_FOUND – web service adapter not found when invoking the web service resource.

 

The value of $COMMAND_STATUS should be used to decide on the action to be taken within the script.

 

API language (e.g. Javascript):

All errors are handled by catching exceptions. If there is a failure, the exception type varies based on the setting of the Treat SOAP fault as error flag:

 

 

This distinction is largely academic and it is recommended that when using API scripting languages such as Javascript, this flag is always set to false (unchecked).

 

Examples:

These examples assume Treat SOAP fault as error is false (unchecked).

 

FPL:

API based language (Javascript):

 

call WS1 'myWebServiceAdapter';

 

if [$COMMAND_STATUS = 'OK ']

  //call to web service successful, write code here

  //e.g fetchtable

  fetchtable myTable;

endif

 

if [$COMMAND_STATUS = 'ERROR']

  // call to web service failed, write recovery code here

  //e.g show message with mapped fault_string value

  if [FAULT_CODE = 'soap:Server']

    message 'Error return from server: ' + FAULT_STRING;

  else

    message 'Error from calling remote server: ' + FAULT_STRING;

  endif

endif

 

 

 

try 
{
   resources.WS1.call("myWebServiceAdapter");

  // call to web service successful, write code here

  //e.g load any tables from the response document

  tables.MYTABLE.fetchTable();
}
catch (e if e.javaException instanceof com.ebasetech.xi.exceptions.SoapFaultException)
{
  log(e.javaException.message);

  // call to web service failed, write recovery code here

  //e.g show message with mapped fault_string value

  if (fields.FAULT_CODE.value == "soap:Server")

  {

    event.owner.addErrorMessage("Error return from server: " + fields.FAULT_STRING.value);

  }

  else

  {

    event.owner.addErrorMessage("Error from calling remote server: " + fields.FAULT_STRING.value);

  }

}

 

 

SOAP Faults

This section describes the generation and content of SOAP Fault documents. See the previous section for examples of how these can be handled.

 

When Treat SOAP fault as error is set to false and any error occurs calling a web service, a SOAP Fault is generated. The fault is added to the configured Fault Body document and the fields inside the fault can then be interrogated by the calling application.

 

The style of the SOAP fault returned is determined by the SOAP version of the document. This SOAP fault can represent an error returned from the called server or it can represent a client side fault generated by the client if it is unable to contact the remote server. The SOAP Fault will either be a SOAP 1.1 Fault or a SOAP 1.2 Fault document. In order to interrogate the SOAP Fault details, the appropriate fault document must first be added to the ‘Fault Body’; this is normally done automatically when the web service is imported. To check this, click on documents in the selection panel at the top left of the Web Service Resource Editor and you should see a Fault document structure. Resource fields in the fault document e.g. fault code, fault string etc should be mapped to corresponding form fields.

 

The table below describes a typical SOAP fault code that could be received if an error occurs and some common causes:

 

SOAP 1.1 Fault Code

SOAP 1.2 Fault Code

Common Cause/Description

soap:Client

soap:Sender

1.      The target URL is not available because the service has been taken down for maintenance.

2.      The target URL is not configured properly.

 

soap:Server

soap:Receiver

1.      There was an error processing the request on the remote server.

2.      The remote web service is unavailable

3.      The remote web service does not exist

 

soap:VersionMismatch

soap:VersionMismatch

1.      Soap 1.1 style message sent to a web service that expects a Soap 1.2 message

 

 

 

A more detailed explanation can be obtained from the additional fault elements of the SOAP Fault.

 

Note that the SOAP Fault document is not cleared between web service calls.

 

Maintain Session

Some web services require session management between the Verj.io server (the client) 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 cookie is written back to the web service caller (Verj.io). The session cookie is stored on the form and used for all subsequent calls to the web service. The cookie might then be used by the web service to authenticate the session to allow the web service request to continue. The session cookie is stored on a per user basis and lasts for the lifetime of the Verj.io form session.

 

To enable maintain session: Select the checkbox on the web service adapter – Maintain Session.

 

 

Testing the Web Service

Press the Test Web Service button to perform a test on the web service adapter.

 

The web service test populates the operations dropdown box with the adapter name. There will only be one operation available to test from the web service test dialog which is the selected web service adapter.

 

The web service test also supports WS-Security headers that are configured with the web service. This is inserted into the SOAP document after the Submit is pressed and is hidden from the user. The entire SOAP message can be viewed in the server log which includes the WS-Security headers as the test is invoked on the server. See WS Security for more details.

 

The web service test supports SOAP 1.1 and SOAP 1.2. The appropriate SOAP Envelope is automatically created based on the SOAP version configured in the web service adapter properties.

 

NB It is not required to save the web service adapter before testing.

 

 

To test the web service:

 

1)     The request SOAP document is automatically created an added to the request panel when the web service test dialog is opened.

2)     Edit the request SOAP document by replacing all the element values highlighted in red, where applicable.

3)     Click the Submit button to perform the test.

4)     The response from the test call will automatically populate the response panel.

 

 

 

 

Web Services over HTTPS

If the remote web service server’s certificate is self-signed or signed using an in-house CA, it must first be imported into the caller’s Java trust store. This is required for any of the following:

 

 

If the certificate has been signed by one of the recognised Certificate Authorities, Verisign etc, no action is required and the web service should work without the need to import a certificate.

 

See the web services https documentation for more details and instructions on obtaining and importing certificates.