Chapter 2. Scripting Introduction - Hello World!

Table of Contents

Loading Script at Run Time
Executing Script
Interaction in Scripts
Automatic Scripts Loading at Startup Time

Artur Hefczyc <artur.hefczyc@tigase.net> v2.0, June 2014: Reformatted for AsciiDoc. :toc: :numbered: :website: http://tigase.net :Date: 2010-01-06 20:18

tiger3-small

This document is the first in series describing scripting support in the Tigase server. It shows how to load, install, update and call a script. It contains also an introduction to the scripting API with the first "Hello world!" like example.

Since the Tigase version 4.3.1 the server supports scripting for administrator commands.

In theory many different languages can be used to write scripts and the only requirement is that the support JSR-223 for the language. More details can be found on the Java scripting project site.

In practice some languages are better supported than others. At the moment the most recommended is Groovy, although following languages are also confirmed to be working: Scala, Python and Ruby. The Tigase SVN contains a few examples for these languages.

Please note, the default Tigase installation contains only libraries for Groovy. Adding support for a different language is as simple as copying a few JAR files to the Tigase libs/ directory.

All the examples presented in this guide are also available as ready to use scripts in the Tigase SVN repository in directory: src/main/groovy/tigase/admin.

The scripting utilises only standard XMPP extensions and is by no means specific to any particular solution. I use and prefer Psi client. The whole guide and all the screenshots are created using Psi client. You can, however, use any other client which supports these extensions as well. As the whole thing is based on the service discovery and ad-hoc commands you need an XMPP client with a good support for both features.

To follow the guide and run all the examples you need installed Tigase server in version at least 4.3.1 and you have to connect to the server as administrator.

Loading Script at Run Time

All the scripting stuff is as usually based on the service discovery and ad-hoc commands in the Tigase server.

service-disco

The first thing to do, therefore, is to browse service discovery on the running server. The result you receive depends on your installation and installed components.

The most interesting for us right now are all items with "http://jabber.org/protocol/admin" in their node part. You may have a few scripts loaded already but there are two commands used for scripting management. Their names are descriptive anouth I hope: "New command script" and "Remove command script".

The first is for adding a new script or updating existing and the second is for removing script from the server.

To add a new script you have just to execute "New command script". In Psi this is done by double clicking on the element in service discovery list.

hello1-new-script

The screenshot above shows a couple of options to set for the loaded script:

  • Description - is what shows as the script name in the service discovery window. There are no special restrictions on what to put there.
  • Command id - is a unique ID of the script (admin command). This is what shows after the "http://jabber.org/protocol/admin" in node part. This needs to be unique or existing script is overwritten.
  • Language - a drop down list of all supported scripting languages for your installation. The Tigase automatically detects all libraries for scripting languages and lists them here. So all you need is to select correct language for your script.
  • Script text - is just your script content.

When your script is ready and all fields are correctly set, simply press "Finish" button and you should receive a message confirming that the script has been loaded successfully.

loaded-ok-small

In this guide we are creating a simple script of type "Hello world". The script is written in Groovy. What it does is displaying a window (ad-hoc command result) with a message: "Hello admin, how are you?".

It uses a basic scripting API which is described line by line below:

  1. It imports basic Tigase classes.
  2. Set’s a local variable \'p' which points to a \'packet' variable with data received from the client.
  3. Creates a \'res' variable which is response sent back to the client (administrator). The response to the client is of type \'result'. Other possible types will be introduced later.
  4. We operate on ad-hoc commands here so the script uses Tigase utility class to set/retrieve command parameters. It sets the window title and a simple message displayed to the user (administrator).
  5. The last line returns new packet as a script execution result.

The first, very simple version looks like this:

import tigase.server.*
def p = (Packet)packet
def res = p.commandResult(Command.DataType.result)
Command.addTitle(res, "Hello World Script")
Command.addInstructions(res, "Hello admin, how are you?")
return res