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, these messages contain the PID of the modified object, the method used to modify the object and in some cases the dsid (data stream id) of the modified datastream. When the listener receives a message it will attempt to read a datastream with a dsid of Trigger-Datastreams from the modified objects content model object. The listener will try to match the incoming method and the dsid. If it finds a match it will load the corresponding datastream in the same content model object which contains a t2flow document. The listener then POSTS this t2flow document to Taverna, the listeners also send the required inputs to Taverna and then polls Taverna until it receives a STATUS of Finished. When the listener receive a status of finished it sends a delete request Taverna and Taverna will delete the workflow.
For objects to be able to trigger workflows their content model object must have a data stream with a dsid of Trigger-Datastreams, this data stream is a simple xml document that links datastreams/methods to a t2flow datastream. One content model object can have many t2flow datastreams.
<methods>
<method type="ingest">
<t2flow id="INGEST_WORKFLOW"></t2flow>
</method>
</methods>
The line above represents a simple example Trigger-Datastreams. 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 wraps the microservices with a WSDL version 1.1. Users can import these services into Taverna Workbench by choosing to import a new wsdl service and entering the appropriate URL. Once the WSDL is imported Workbench users can use the functions defined in that WSDL when designing their workflows.
- 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 outputs the 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 workbench is GUI used to design Taverna workflows and save them as t2flow documents. Once you have imported the Microservices you can start using the functions defined in the WSDL in your workflows.
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 taverna-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 requirements will be running on servers.