1 Introduction
##1.1 Purpose:
This user manual is a comprehensive guide to walk through the steps that it takes to install taverna, and the Islandora microservices. Including creating new microservices, creating a workflow in Taverna Workbench and how the Listeners receive messages from Fedora via JMS/STOMP.
The Islandora PHP Microservices can be thought of as serveral components.
- A JMS/STOMP Listener (the listener)
- Taverna Server (workflow server)
- A SOAP endpoint (the services)
The listener listens for messages from Fedora. Fedora generates these messages whenever an Object is created, deleted or modified. When a message matches specified criteria the listener will read a datastream,with an id of Trigger-Datastream, from the modified objects content model object. This datastream contains the id of another datastream in the same content model object which contains a t2flow document. The listener POSTS this document to Taverna and then polls Taverna until it receives a STATUS of Finished. When the listeners receive a status of finished it tells Taverna to delete the workflow.
- TavernaSender.php which is to sent and run t2flow on taverna sender.
- Connect.php which is to listen a single change.
- listener.php which starts connections.
- tuque which is the API that TavernaSender uses.
The JMS listener uses HTTP REST to post t2flow documents to Taverna. To use the JMS listener, a Trigger-Datastream datastream containgin xml should be added to the content model. This xml file links datastreams/methods to a t2flow datastream. One content model object can have many t2flow datastreams. When the listeners receive a message they read the Trigger-Datastream to find a matching datastream and method which will inform the listeners which t2flow to send to Taverna.
<methods> <method type="ingest"> <t2flow id="INGEST_WORKFLOW"></t2flow> </method> </methods>
The line above represents a simple example Trigger-Datastream. The example above links the ingest method to the INGEST_WORKFLOW t2flow datastream.
<methods> <method type="addDatastream"> <trigger id="TEST"> <t2flow id="T2flow-doc"></t2flow> </trigger> </method> <method type="ingest"> <t2flow id="Newspaper-test"></t2flow> </method> </methods>
The example above includes both and ingest workflow and a workflow that will be invoked everytime an object has a datastream with an ID of TEST added to it.
The PHP SOAP Service defines microservices via WSDL 1.1 which users can import to Taverna Workbench to use when creating workflows. The WSDL describes all the function available at that end point.
- everything within the soap_server folder (which needs to be in a web accessible location).
- soap_serv.php which is an entry point to the services and provides a wsdl.
- config.xml which tells the soap_server where the rest of the listener code is. It is recommended that most of the listener code exist in a non web accessible directory as the config files will have sensitive information.
- the config.xml file also has the list of available services. The default services are defined in a file named RoblibServices.php. The RoblibServices.php includes the RoblibServices class which extends the IslandoraServices class. It can be used as a guide for adding new custom services.
Taverna workbanch is GUI used to design Taverna workflows and save them as t2flow documents. Users can import the Islandora PHP microservices if PHP SOAP Service is correctly installed. The micorservices should be available at http://domain/path/to_soap_server/soap_serv.php?wsdl. Users should add the t2flows they create to the appropriate content model objects so that JMS listener can post them to taverna server. Taverna workbench can be downloaded from http://www.taverna.org.uk/download/workbench/
The taverna server process REST calls from Islandora PHP listener. Taverna parses the t2flow document and executes a workflow, which would usually include calls to the Islandora microservices and possibly calls to other external services.
In addition to the Islandora Requirements, the following is needed to execute the Taverna Integrated workflows:
- A working Taverna Server (TavernaServer 2.4.1 tested.)
- Updated php_listeners code currently located here: https://github.com/roblib/php_listeners/
- use the tavera-1.x branch
- PHP PEAR SOAP Server (version 0.13.0 tested)
- Taverna Workbench for creating and editing workflows. You most likely be running the Workbench on your local computer. All other mentioned requiremenst will be running on servers.