OpenWGA 7.11 - OpenWGA Concepts and Features

Design and development » TMLScript

Remote actions

Remote actions are TMLScript modules which are callable as WebTML actions from other processes and programs. They therefor can be used for inter-process communication. This functionality can be enabled for each TMLScript module that is contained the design of an OpenWGA application.

Defining remote actions

Generally every TMLScript module qualifies as remote action whose code can be run on a non-web context. The TMLScript environment under which remote actions are run is very similar to the one of TMLScript scheduler tasks:

  • Always executed under master login
  • No web or user related resources available like WebTML tags, requests, user profiles or portlets

So all functionalities marked in the TMLScript reference to be available to scheduler tasks are also available to remote actions.

For security purposes OpenWGA prevents TMLScript modules from being called that way if they have not explicitly being markes as being remote actions.

You mark a TMLScript module as a remote action in the configuration of the design that holds the module. There a tab "Remote Actions" is available where you can list those modules that qualify as remote actions and set the authorisations needed to do so.

Once a remote action is registered here it may be called via WGAServices web service.

Using the WGA SOAP Web Services Client API

Remote actions use the "OpenWGA SOAP Web Service", which is a SOAP-based Web Service interface to OpenWGA servers.

If your application is written in Java you can use the WGA SOAP Web services client classes that come with the distribution. You can find them on the OpenWGA Web Services XFire server plugin.

  • Open the OpenWGA admin client
  • Choose menu "Plugins"
  • Find the plugin named "OpenWGA Web Services XFire Server" and click on it's title
  • The homepage of this plugin is displayed offering a link to a ZIP archive which contains JAR libraries of the WGAServices Client API. Add these libraries to your applications classpath

If you use some other programming environment that offers a SOAP webservice API you may as well use the WGAServices WSDL which describes the offered services. You should be able to call these services or even generate some client functionalties for your programming environment with it.

On your OpenWGA Server you find it under URL:

http://<hostname>/services/core?wsdl

The most important classes of the WGA SOAP Web Services Client API are:

  • de.innovationgate.wgaservices.ClientFactory: Contains static methods to create the most important objects of the WGAServices API. One of it is method createCoreServiceClient() creating an object of type...
  • de.innovationgate.wgaservices.WGAServices. This is the base class of all service functionalties. It represents a connection to a special OpenWGA server. As all WGAService functionalities need a login to the server you first call methods login() or adminLogin() to obtain a...
  • de.innovationgate.wgaservices.types.RemoteSession which represents your login to the server. It then can be used to call method createActionCaller() on object ClientFactory which returns an object of type...
  • de.innovationgate.wgaservices.ActionCaller. This finally can be used to call remote actions on a special OpenWGA application.

Creating a WGA Web Services connection

First we need to create a WGA Web Services connection pointing to your server. We use the method createCoreServicesClient() with the OpenWGA server root URL to create one:

// Enter the root URL of your OpenWGA installation
WGAServices services = ClientFactory.createCoreServiceClient("http://my.openwga.com");

The WGAServices object represents a web service connection to the OpenWGA Server. But to start working you first need a to login to the server. You have the choice either to use a normal authoring login that gives you all the rights that the author user would have in content manager for the accessed application, or an administrative login which gives you full rights. Both logins are represented by an object of type RemoteSession.

Authoring logins are obtained by method login() on the WGAServices object:

RemoteSession session = services.login("default", "demouser", "demopassword");

An administrative login is created by method adminLogin():

RemoteSession session = services.adminLogin("admin", "wga");

Calling remote actions

The object type de.innovationgate.wgaservices.ActionCaller is used to call remote actions. It is created via the ClientFactory object and allows calling remote actions of one specified application. The Method createActionCaller is given the WGAServices object, a remote session and the key of the application to be called:

ActionCaller actionCaller = ClientFactory.createActionCaller(wgaservices, remoteSession, "myapp");
Object returnValue = actionCaller.callAction("theaction");

Values returned by the TMLScript modules code are also returned by remote actions to be evaluated on the client side.

Just like normal WebTML action remote actions can take parameters, given as list to the callAction method. The objects will be available as "tmlparam1" to "tmlparamn" as usual, where the first list entry is 1

ActionCaller actionCaller = ClientFactory.createActionCaller(wgaservices, remoteSession, "myapp");

List params = new ArrayList();

params.add("whatnot");

params.add("whatever");

Object returnValue = actionCaller.callAction("theaction", params);


The object de.innovationgate.wgaservices.types.Form can be used to pass the data of a WebTML form to the action. This will be available to the script as object "tmlform" as usual:

Form form = new Form("params");
form.setField("customerkey", "2c9481940e7bc7a2010e7ebad76b0b0b");
List result = (List) actionCaller.callAction("queryContacts", form);


This form data can carry binary attachments just like normal WebTML forms. Add local files as attachments to the form with method Form.addFileAsAttachment().

The method setExecutionContext() of the ActionCaller object influences the WebTML context under which the action called. Normally this is a dummy context of the called app, but here you can set a WebTML context expression that sets the actions execution context:

actionCaller.setExecutionContext("name:user.demo");

actionCaller.callAction("setUserInactive");



If the remote action modifies object that are given as parameters to the action then these modifications will not be transported back to the action caller. So they will not be visible on the client side!

Data type restrictions to parameters, return values, form field values

Although the WGAServices API allows any Java object to be passed as remote action parameter, form field value or action return value it is up to the WGAServices web service implementation what types of objects are actually transportable.

Safe object types for these usages should be:

  • Primitive objects like
    • java.lang.String
    • java.lang.Number and descendants
    • java.lang.Date
    • java.lang.Boolean
  • Basic collection classes like java.util.ArrayList and java.util.HashMap that contain the other possible object types
  • Basic java beans with a default constructor containing the other possible object types
You should generally prevent usage of objects that are not is this list or objects that contain references to objects not in this list as they might fail to be transported to the remote action or back from it.

Security considerations

The web service API to call remote actions has not own means of securing transported data, including the login that is used. It is all transported in cleartext.

So if using remote actions in an insecure network you should do this via an encrypted channel like HTTPS or a VPN.

Regarding HTTPS you may experience problems when the target server has a SSL certificate that is not certified by a trust organisation. See the XFire documentation on how to treat with this situation. The most common way is to provide a trust store that contains the celf-signed certificate.

1. Create a trust store file by importing the servers SSL certificate via JDK tool "keytool":

keytool -import -v -alias ssl -file ssl.cert -storepass <password> -keystore <storefile>

2. Give your OpenWGA Java Runtime the trust store by specifying an additional Java system variable on startup:

-Djavax.net.ssl.trustStore=<storefile>