Taverna 2 Server Interaction Gem

Authors

Robert Haines

Contact

rhaines@manchester.ac.uk

URL

www.taverna.org.uk/

Licence

BSD (See LICENCE or www.opensource.org/licenses/bsd-license.php)

Copyright

© 2010-2012 The University of Manchester, UK

Synopsis

This is a Ruby library to interface with the Taverna 2 Server REST API.

Installation

Ensure that gem itself is up to date:

[sudo] gem update --system

Then simply install as you would any other gem:

[sudo] gem install t2-server

In case of problems with the above the gem is available for download here: rubygems.org/gems/t2-server

You can also download the source code from here: github.com/myGrid/t2-server-gem

Compatibility with Taverna Server versions

From version 0.9.0 this library is compatible with Taverna Server 2.3 onwards. It is not compatible with any earlier version of Taverna Server due to breaking changes in its REST interface. We strongly encourage all users to upgrade to the current version of Taverna Server, but if that is not possible right now then please continue to use version 0.6.1 of this library for the time being.

This version of the library should be compatible with any Ruby code that you may have already written against earlier versions but you may see some warnings about API deprecations. These are clearly marked [DEPRECATION] and will appear on your console output. Anything marked as deprecated will be removed in version 1.0.0 so you are advised to update your code at your earliest convenience.

Usage

There are two entry points for the T2Server API:

In both cases the gem should be initialized by requiring the top level ruby file:

require 't2-server.rb'

Configuring a Server connection

Setting up a connection to a secure server can be quite tricky and a secure Taverna Server is no different. To make things slightly easier this library provides some short cuts to providing various parameters for different types of connection.

Connection configuration settings are passed in to various methods using the ConnectionParameters class. Parameters that can be set are:

And can be set like this for a standard https connection:

conn_params = ConnectionParameters.new
conn_params[:verify_peer] = true
conn_params[:ca_path] = "/etc/ssl/certs"

This will ensure that the identity of the Taverna Server you are connecting to will be verified using the set of certificates in /etc/ssl/certs.

For convenience a number of standard sets of parameters have been defined. The above example is available as DefaultConnectionParameters. Others available are:

See the rdoc for more details on these classes.

Authenticating to a Taverna Server

Some calls to a server require that a set of user credentials are provided. These are simple to set up:

credentials = T2Server::HttpBasic.new("username", "password")

Server API example

The Server constructor can yield the newly created object. Simple supply a URI and a set of connection parameters to connect to a server:

T2Server::Server.new(uri, conn_params) do |server|
  ...
end

Note that credentials are not required by default to simply connect to a Taverna Server. Further operations (such as creating and starting runs) may require authorization depending on how your server has been set up.

Run API example

You can bypass the Server API if you know you are only going to be dealing with a couple of runs directly:

T2Server::Run.create(uri, workflow, credentials, conn_params) do |run|
  ...
end

Setting an input port to a run is very easy:

run.input_port("port_name").value = 1
run.input_port("port_name").value = "Hello!"
run.input_port("port_name").value = ["list", "of", "values"]

Or you can use a local file as input:

run.input_port("port_name").file = filename

Once all the inputs have been set the run can be started:

run.start

And monitored to see if it has finished:

run.finished?
run.running?

Or just wait until the run has finished:

run.wait

Then the outputs can be collected:

result = run.output_port("port_name").value

If you have a lot of output you can grab the whole lot as a zip file:

zip_data = run.zip_output

Using baclava documents for setting inputs and collecting outputs is also supported:

run.baclava_input = filename

But make sure you request baclava output before starting the run:

run.request_baclava_output
run.start
run.wait
output = run.baclava_output

See the rdoc for more information. Many methods and classes have much more functionality than the defaults described above. Please note that anything which does not appear in the documentation is not intended to be part of the public API. Use of undocumented classes and methods is entirely at your own risk! Such things might not have consistent behaviour and might be removed at any time.

Example scripts

As well as rdoc there are also a couple of example scripts which demonstrate good use of the T2Server API. These are available in the bin directory but are also installed with the library code when the gem is installed:

Running any of these scripts with a -h or --help switch will show how to use them, e.g.:

t2-run-workflow --help

Interacting with secure Web Services

This library can be used to run workflows that contain secure services. Such services may be secured in a number of ways depending on how the credentials are passed and whether they are REST, SOAP or Rshell services.

Running workflows that contain secure services requires that you pass your credentials to Taverna Server so that it can authenticate itself as you on your behalf.

It is essential that you trust the Taverna Server that you are using!

Ideally, you should only pass sensitive information, such as passwords, via https so that you can be sure that it is not being read in transit.

Username and password credentials

REST

REST services are commonly secured via HTTP Basic or HTTP Digest authentication and Taverna treats these two schemes in the same way. Simply pass in your username and password with the host name of the server on which the service is running:

run.add_password_credential("https://example.com:8443/", "username", "password")

The above example shows a https server running on port 8443. If the service is on port 80 for http or port 443 for https then you don’t need to specify the port.

If there are services on the same host that require different credentials then you will need to specify the realm for which each set of credentials applies. This is done by adding the name of the realm to the end of the host name with a # separating them:

run.add_password_credential("https://example.com:8443/#realm", "username", "password")

SOAP

SOAP services are commonly secured via WS-Security. Simply pass in the WSDL address of the service with your username and password:

run.add_password_credential("https://example.com:8443/services/MyService?wsdl", "username", "password")

R Servers (via Rshells)

You can authenticate to R Servers in almost exactly the same as for REST services - only the protocol scheme is different. So instead of http or https it is rserve:

run.add_password_credential("rserve://example.com:6311", "username", "password")

Keypair (certificate-based) credentials

Some https servers authenticate clients using certificates. If you have services that require this type of authentication you can upload a keypair:

run.add_keypair_credential("https://example.com:8443/", "certificate.p12", "password")

Trusts (peer verification)

If the services in your workflows are on a https server then Taverna requires that it can verify that the server is the one you expect it to be. This is done by peer verification. In most cases this happens automatically and transparently but if the remote server has a non-standard or “self-signed” certificate then you will need to provide Taverna with the corresponding public key for verification to take place:

run.add_trust("public-key.pem")

Interacting with other Taverna Server users

Taverna Server is a multi-user system and as such insulates users from one another as much as possible. Each run that a user creates can only be accessed by that user by default. If you want to give another user permission to perform certain actions on a run then you can do so:

run.grant_permission("username", :permission)

Available permissions are:

Permissions are accumulative so giving a user the :destroy permission also allows that user to read and set the run’s state. Note that there is no way for any user other than the owner of a run to perform any security related actions on it. This means that only the owner may grant, query and revoke permissions and only the owner may add, query and delete trusts and credentials.

You can revoke a user’s permission:

run.revoke_permission("username")

You can get a list of the permissions you have granted for a run:

run.permissions

And also see what permission you have granted a particular user:

run.permission("username")

Support

Please email support@mygrid.org.uk for any questions relating to this Ruby gem.

References

Taverna 2 Server

www.taverna.org.uk/documentation/taverna-2-x/server/

REST API Documentation

www.taverna.org.uk/documentation/taverna-2-x/server/rest-api/