This document does not include a complete summary of the SOAP API of Taverna Server 2.5; some operations are missing from this document and some messages have been altered from previous versions of Taverna Server to promote improved interoperability. The complete list of operations and exact descriptions of the messages sent and received by those operations is given in the WSDL description published by the service.
API of the SOAP Interface
Taverna 2 Server supports a SOAP interface to the majority of its user-facing functionality. The operations that it supports are divided into a few groups:
- Global Settings
- Basic Workflow Operations
- Input and Output Control
- File Operations
- Event Listeners
- Security Configuration
The connection itself is done (under recommended deployment patterns) by HTTPS, and is authenticated via Basic HTTP username and password at the connection level. All information reported is only necessarily true for a particular user; no guarantee is made that it will be the same for any other user.
Note that the information below is just a summary. The WSDL document for the server should be consulted for the full definition of the messages used with each operation.
These operations describe things that are across all the workflow runs owned by the connecting user on the server.
This obtains the description of the abstract capabilities (and their versions) of the execution engine that is hosted inside the service.
This obtains the names of the protocols supported for registration for active notification. Note that the Atom feed support is always enabled as it is built into the service itself.
This obtains the maximum number of runs that may be executed at once by the current user; note that this limit might not be reachable by any one user if it is due to a global limit on the number of runs and other users have several runs of their own.
Get a list of workflows that are permitted to be instantiated; if the list is empty, there is no restriction on what workflows may have runs created of them.
Get a list of types of listeners that may be explicitly attached to a workflow run.
Get a list of all workflow runs on the server that the user has access to. (Workflows that they do not have permission to access even for reading will be not returned by this operation.)
Basic Workflow Operations
An ID string identifies every workflow run. All operations on a workflow run take the ID as one their arguments. (Implementation note: This ID is a UUID.)
Submit a workflow to create a run, returning the ID of the run. Newly submitted workflows start in the Initializing state so that you can upload all the required support files before starting the run.
Destroy the given workflow run. This kills the workflow execution if the run was in the Operating state removes all files associated with a run.
Get the time that a workflow run will become eligible for automated destruction. The default lifespan of a workflow run is 24 hours.
Set the time that a workflow run will become eligible for automated destruction.
Get the time that a workflow run was created (by the submitWorkflow operation).
Get the time that a workflow run started executing (i.e., transitioned to the Operating state) or null if that has not yet occurred.
Get the time that a workflow run stopped executing (i.e., transitioned to the Finished state) or null if that has not yet occurred.
Get the workflow document that was used to create a workflow run.
Get the current state of a workflow run. In the current implementation, this is one of Initializing, Operating and Finished. (Technically, there's also a Stopped state but no run implementation currently supports it, and there's conceptually a Destroyed state too, but the service cannot say so as it will instead give a fault stating that the run does not exist.)
Set the current state of a workflow run, which is necessary to start it Operating. The execution can be finished early by manually moving it to Finished, though the run will automatically progress to that state once it terminates naturally. It's always legal to set a run to its current state, and it's always legal to set the state to Finished.
Get the run bundle for a workflow run. Note that this method uses a transfer format that supports the use of MTOM.
Get the standard output from the execution engine. An empty string when the execution engine has not yet started.
Get the standard error from the execution engine. An empty string when the execution engine has not yet started.
Get the detailed log contents from the execution engine. An empty string when the execution engine has not yet started.
Get the resource usage description of the execution engine, or null when the execution engine has not yet finished.
Input and Output Control
Returns a description of what inputs are expected by a particular workflow.
Returns a list of what inputs have been configured on a particular workflow, including what file they are to be taken from or what value they are to use.
Configure an input to take its value from a file in/beneath the job's working directory.
Configure an input to take its value directly from the supplied string.
Configure an input port to split its value into a list of values prior to supplying them to the workflow inside the workflow run.
Configure a run to take all its inputs from a Baclava file. The Baclava file should be uploaded to the run’s working directory prior to the state being set to Operating.
Get a description of what outputs have been provided.
Get whether a run bundle (containing provenance) will be created. For compatibility reasons, this defaults to not producing provenance.
Sets whether a run bundle (containing provenance) will be created. This is only meaningful before the run state is set to Operating.
Gets the run bundle file, which is a special ZIP conforming to the model of a Research Object and containing information about the inputs and outputs, and the provenance of those values. This is only guaranteed to be present if the workflow run has successfully finished and was asked to generate provenance. This method supports MTOM for file transfer.
Arrange for the run outputs to be written as a Baclava file. If this is not called, outputs will be written into files in the out subdirectory of the workflow run's working directory. Note that this inhibits generating a run bundle.
Get the name of the Baclava file that will have the run outputs written to it.
Every workflow run has a working directory that is private to itself. That working directory will be the current directory when the workflow run is executing.
List the contents of a directory. The workflow run's working directory is denoted by the empty filename, and only that directory or its subdirectories may be listed.
Delete a subdirectory or file.
Given a directory, return that directory plus all its contents (files, subdirectories) as a ZIP file.
Create a subdirectory of a directory. Note, you should not create the out subdirectory; that will be created by the workflow engine.
Get the contents of a file, as XML-wrapped base-64 encoded data. (Implementation note: Consider fetching large files by the REST interface, which can handle much more data by virtue of using data streaming, or via the MTOM-enabled operation.)
Get the contents of a file. (MTOM-enabled.)
Get an estimate of the content type of a file.
Get the length of the contents of a file.
Create an empty file.
Set the contents of an existing file from XML-wrapped base-64 encoded data. (Implementation note: Consider uploading large files by the REST interface, which can handle much more data by virtue of using data streaming, or via the MTOM-enabled operation.)
Set the contents of an existing file. (MTOM-enabled.)
The listener interfaces are likely to be removed entirely from a future version of Taverna Server; the structure of the functionality intended to be surfaced by them has evolved in a different way to what was originally expected.
Get a list of listeners attached to a particular run.
Attach a new listener to a particular run. The listener must be of a recognised type.
Get the configuration document of a particular listener. The configuration document can only be read, not written.
Get the list of properties supported by a particular listener.
Get and set the values of individual properties; properties are always strings.
There is one standard listener, io, which is attached by default. This listener has an empty configuration document, and provides access to a number of properties. The properties are:
The standard output stream from the workflow executor process.
The standard error stream from the workflow executor process.
The exit code of the workflow executor process. Empty if not yet exited.
The URI to push termination notifications to. If empty, no notifications are pushed (but they are always made available by the Atom stream).
If non-empty, a UR1.0-format usage record describing resources consumed during the execution of the workflow.
Per-Run Security Configuration
Note that all of the operations below are restricted to the owner of the run except for discovering the identity of the owner of the run.
Get the identity of the owner of the run. Note that the owner always has full permission to modify and read the run.
List the non-deny permissions granted by the owner.
Grant a particular permission to a user.
List the credentials given to a run to use when contacting other services.
Give a credential to a run to use when contacting other services.
Stop a run from using a particular credential when contacting other services.
List the server certificates that will be trusted when contacting other services.
Add to/update the server certificates that will be trusted when contacting other services.
Remove from the server certificates that will be trusted when contacting other services.