Calling Metrici web services from the SPA

The SPA can also call web services on Metrici.

These calls make use of the session established when the user signed into Metrici, and do not require additional authorisation.

The SPA does not have direct access to the Metrici session. Instead, it uses a technique involving a hidden iframe:

  • A hidden iframe is generated into the document, with a src attribute that points to a special URL on the Metrici server. This iframe can use the Metrici session.
  • Service calls are passed to the iframe using the postMessage() method, which passes them on to the Metrici server and then passes the results back to the caller.

This is achieved by the Session class. This is available from the script at

${rootPath}files/session/session.js

where ${rootPath} identifies your Metrici instance, e.g. https://www.metrici.com/.

var session = await Session.ready();
var result = await session.service(url,settings);

setting is a JavaScript object. settings is optional. If there is a single parameter and it is a JavaScript object, it is assumed to be settings.

The settings names are taken from the jQuery.ajax() method (although there is no dependency on jQuery). The following are supported.

method "POST" or "GET". The default is "GET".
data Data to be passed to the request.
processData Whether the data should be processed. Default is true. If set to true, this means that the data is a JavaScript object which contains the names and values of request parameters.
contentType The content type for the request. Defaults to form encoded data.
url The URL. This is useful when only settings are passed, not a URL.

If processData is true and is a JavaScript object, the object will be converted to a parameter string. For a GET request, this will be added to the URL. For a POST request, this will be sent as form data.

If processData is false, the data will be treated as a string and either appended to the URL of a GET request or sent as the body of a POST request. If you want to send data other than form data, set the data accordingly, set processData to false, and set contentType.

The servicejson() method is also available. This makes a post request to the Metrici servicejson web service end point. This takes two parameters: the name of the service, and a data object which will be passed as the body of the request. The result from servicejson() will be a JSON object.

For example, the following call would using the Send User Email call to send an email from the current user:

var emailResult = await session.servicejson(
  'SendUserEmail',{
    to: 'recipient@somewhere.com',
    subject: 'Awesome',
    message: 'This is an awesome email!
  }
);
if ( emailResult.errorNumber != 0 ) {
  // do something with emailResult.errorDescription
}

The session object also provides the rootPath prefix that is required for any URLs in Metrici, using the session.getRootPath() call. For example, to sign out from Metrici directly from an SPA you could use:

window.location.href = session.getRootPath() + 'app/sign_off.jsp';