External API

 

Documentation home

 

Introduction. 1

Using the External API 2

API 3

startForm. 3

reconnectToForm. 4

executeFunctionAsynchronously. 5

Security. 6

Technical Issues 7

Debugging. 7

 

See also: Client API Reference, Client API Guide

 

Introduction

The External API is a client Javascript API that provides access to the Verj.io server from a web page served from another server or from a native phone app using the phone’s Web View. The main feature of the API is that it provides stateful access to the server i.e. multiple requests can be made to the server within a session; this distinguishes it from a Restful web service published on the Verj.ioi server which provides stateless access.

 

 

 

 

The External API provides the means to connect a web page to an Verj.io form and provides a session between the client and the form. This session can then be used to send/retrieve data to/from the server by calling executeFunctionAsynchronously() to run a Javascript function on the server. The pages of the form, if any, are not used in any way by this API.

Using the External API

 

Prerequisites:

 

1)                           The Tomcat CorsFilter must be enabled on the Verj.io Server. This filter is available from Tomcat 7.0. To enable the filter remove the comments surrounding it in the web.xml file in the WEB-INF folder of the Verj.io server web application. Then restart the Verj.io Server. By default, this filter will allow cross origin requests from all servers but this can be configured if required.

 

2)                           The CookieProcessor element must be configured for sameSiteCookies=’none’ on the Verj.io Server. The sameSiteCookies=’none’ setting always send the JSession cookie across sites. To enable the cookie policy, add the following to the context.xml in the tomcat/conf folder of the Verj.io server web application:

 

<CookieProcessor sameSiteCookies="none" />

 

                       Then restart the Verj.io server. Click here for more information.

 

The External API can be added to a web page as shown in the snippet below:

 

Click here for the snippet.

 

 

1.      Add the xiRemoteApixxx.js Javascript file – this file contains the external API and is loaded from the Verj.io server, xxx is the Verj.io version. JQuery Javascript is also required which must be level 1.6.4 or later, this can also be loaded from the Verj.io server if required. JQuery Javascript should be loaded before the external API Javascript.

2.      Call $eb.startForm() – this initializes the Verj.io form on the server and creates a session, in this example we are calling the server at URL http://myserver/ebase and initializing form HtmlTest1. This request is only issued once, typically when the page is loaded.

3.      Call $eb.executeFunctionAsynchronously() – this runs the named Javascript function on the server passing and receiving data as required, in this example we are calling the server function function1 and passing the number 25.

 

API

startForm

 

Syntax:

$eb.startForm(successCallback, failureCallBack, formName, serverUrl)

 

 

Description:

Initializes communication with the Verj.io form specified by formName on the server specified by serverUrl. Use this function to enable communication with the Verj.io server from an unrelated HTML page. Once this function has been called, additional external api functions can be invoked e.g. $eb.executeFunctionAsynchronously().

 

This call is asynchronous and either the successCallBack or failureCallBack functions, if specified, will be called when it completes. However both of these functions can be specified as null in which case this call will process silently.

 

This call returns an Verj.io form session id (“ebz”) which is saved internally within the API and is then used for any subsequent calls to the server from the same web page. This mechanism is used to implement a session with the server. The ebz value is also returned to the successCallBack function: it can then be passed to a second web page where it can be used to reconnect to the same session using $eb.reconnectToForm.

 

Params:

    successCallBack – a function: called when the execution has been successful and a result has been returned from the server. The result is passed into the function at its first parameter. The result will contain the Verj.io form session id (the “ebz” value). Null can be specified for this parameter.

 

    failureCallBack – a function: a call back function which will be called when there is a failure during communication with the server or when the server cannot initialize the specified form. A textual representation of the error (if known) is passed in as a parameter.

 

    formName – string: the name of the Verj.io form on the server.

 

    serverUrl – string: the url of the Verj.io web app e.g. http://myserver/ebase. If omitted, the call to the Verj.io server is made using a relative URL – this is only possible when the web page has been loaded from the same server used for the external API.

 

Returns:

    Nothing (undefined). The supplied successCallBack function will be called with the ebz form session id as its parameter.

 

 

 

 

Example:

// ignore successful feedback, minimum connection call

$eb.startForm(null, function(resp){alert(resp);}, "HtmlTest1", "http://myserver/ebase");

 

// save returned ebz form session id

var success = function(resp) {

   var ebz = resp;

}

var error = function(resp) {

  alert(error);

}

$eb.startForm(success, error, "HtmlTest1", "http://myserver/ebase");

 

 

 

Since:

V5.1.0

 

reconnectToForm

 

Syntax:

$eb.reconnectToForm(formSessionId, serverUrl)

 

 

Description:

Reconnects the API to the server using a form session id (“ebz”) obtained via an earlier call to $eb.startForm(). This API call can be used on a second or subsequent page where $eb.startForm() was issued on the first page.

 

Params:

    formSessionId – a string: the form session id (“ebz”) obtained via an earlier call to $eb.startForm()

 

    serverUrl – string: the url of the Verj.io web app e.g. http://myserver/ebase. This should have the same value as used with the earlier call to $eb.startForm()

 

Returns:

    Nothing (undefined).

 

 

 

 

Example:

// obtain the ebz value from the ebz URL parameter

var ebz = location.search.split('ebz=')[1];

$eb.reconnectToForm(ebz, "http://myserver/ebase");

 

 

Since:

V5.1.0

 

executeFunctionAsynchronously

 

Syntax:

$eb.executeFunctionAsynchronously(successCallBack, failureCallBack, functionName, parameter)

 

 

Description:

Executes the named Client Callable Function on the server asynchronously. A single Javascript object can be passed to the server function as parameter, any object returned by the server is passed into the successCallback function.

 

Params:

    successCallBack – a function: called when the execution has been successful and a result has been returned from the server. The result is passed into the function at its first parameter.

 

    failureCallBack – a function: a call back function which will be called when there is a failure during communication with the server or when the server cannot execute the function. A textual representation of the error (if known) is passed in as a parameter.

 

    functionName – string: the name of the server function to execute.

 

    parameter (optional) - a javascript object/value/array. This parameter will be passed into the named function on the server as its first parameter. It is your responsibility to ensure that the function accepts a parameter in the server-side script e.g. myfunction(param1){...}.

 

Returns:

    Nothing (undefined). The supplied successCallBack function will be called with the value/array/object returned from the server as its parameter.

 

The Client Callable Function has complete access to all constituent parts of the form – fields, tables, resources etc. Any functions defined in library scripts associated with the form are available within the called function, but are not available to the API directly and attempts to execute one will result in an error.

 

It’s important to note when passing objects from and to the server, only the data within that object is passed - methods and functions are not.

 

This method makes it calls to the server asynchronously. That means it makes a call to the server and immediately finishes. The user can continue to interact with the web page - it does not become 'frozen' as a synchronous call might. When the server eventually returns, the supplied call back function (successCallBack) will be executed with the result of the execution passed in as its first parameter. Should there be an error (either a communication to the server failure, or a failure on the server itself) then the specified failure call back function (failureCallBack) is called instead of the success call back.

 

 

Example:

client side:

   var successCallBack = function(data){ alert(data) };

   var failureCallBack = function(reason){ alert(reason) };

   $eb.executeFunctionAsynchronously(successCallBack, failureCallBack, "addition", [2,3]);

   // more code which is immediately executed – the results of the function execution are not waited for.

 

server side (defined in script: SCRIPT_WITH_FUNCTIONS):

    function addition(params)

    {

        return params[0]+params[1];

    }

 

    function returnTheSameObjectAsReceived(params)

    {

        return params;

    }

 

client side:

   alert(data)

    The call back function supplied is invoked, along with the data returned from the server as its first argument. An alert would pop up with 5 in it (the server-returned result of the addition). If there was an error, the failureCallBack would be called instead of the successCallBack, and an alert containing a reason for the failure (if available) will be shown.

 

 

Since:

V5.1.0

 

Security

Calling a second server using the external API (the first server is the one from which the web page was loaded) is known as Cross Origin Resource Sharing or CORS. There are two requirements for this to work:

 

  • The browser must be willing to issue an Ajax request to a second server (the Verj.io server) and this is controlled by HTTP Response Headers from the Verj.io server. These headers are generated by the CorsFilter implemented in the web.xml file of the Verj.io application on the server. Once this filter has been enabled (see prerequisites) it will by default allow all CORS requests from any origin server.

 

Here is an example of more advanced configuration of this filter, click here for further details:

 

<filter>

  <filter-name>CorsFilter</filter-name>

  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>

  <init-param>

    <param-name>cors.allowed.origins</param-name>

    <param-value>https://myite.com</param-value>

  </init-param>

  <init-param>

    <param-name>cors.allowed.methods</param-name>

    <param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>

  </init-param>

  <init-param>

    <param-name>cors.allowed.headers</param-name>

    <param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers</param-value>

  </init-param>

  <init-param>

    <param-name>cors.exposed.headers</param-name>

    <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>

  </init-param>

  <init-param>

    <param-name>cors.support.credentials</param-name>

    <param-value>true</param-value>

  </init-param>

  <init-param>

    <param-name>cors.preflight.maxage</param-name>

    <param-value>10</param-value>

  </init-param>

</filter>

         

 

          The parameter cors.allowed.origins must contain the same name of the corresponding Origin request header. The parameter cannot contain the wildcard *. If the parameter does not contain the same name, a 403 response will be returned.

 

 

  • The browser or client must attach the session cookie for the Verj.io server received on the first request ($eb.startForm) to all subsequent requests. See same site cookie.

 

 

Technical Issues

At the time of writing this documentation, the only browser known to cause problems is Safari which requires setting Block Cookies > Always Allow on all ios client devices. Without this setting Safari will block all Ajax requests to the Verj.io Server containing a session cookie.

 

Debugging

Suggested approach for debugging problems using the External API:

 

  • Check the Verj.io target server’s access log to see if the requests are being received – these requests are for the externalapi servlet
  • Check the server’s main log for any issues initializing a form or executing a function
  • Implement failureCallBack functions to check for errors
  • Use a debugging tool on the client browser/device to:
    • Check the console log for Javascript errors or information messages
    • Check the CORS response headers are correct. You should see:
      • Access-Control-Allow-Origin: to include the same value as on the corresponding Origin request header
      • access-control-allow-credentials: should be “true” (this is required to enable the browser to send session cookies)
    • Check the session cookie is being sent for all requests other than the first request