Skip to end of metadata
Go to start of metadata

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.

Global Settings

These operations describe things that are across all the workflow runs owned by the connecting user on the server.

getCapabilities

This obtains the description of the abstract capabilities (and their versions) of the execution engine that is hosted inside the service.

getEnabledNotificationFabrics

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.

getMaxSimultaneousRuns

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.

getPermittedWorkflows

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.

getPermittedListenerTypes

Get a list of types of listeners that may be explicitly attached to a workflow run.

listRuns

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.)

submitWorkflow

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.

destroyRun

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.

getRunExpiry

Get the time that a workflow run will become eligible for automated destruction. The default lifespan of a workflow run is 24 hours.

setRunExpiry

Set the time that a workflow run will become eligible for automated destruction.

getRunCreationTime

Get the time that a workflow run was created (by the submitWorkflow operation).

getRunStartTime

Get the time that a workflow run started executing (i.e., transitioned to the Operating state) or null if that has not yet occurred.

getRunFinishTime

Get the time that a workflow run stopped executing (i.e., transitioned to the Finished state) or null if that has not yet occurred.

getRunWorkflow

Get the workflow document that was used to create a workflow run.

getRunStatus

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.)

setRunStatus

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.

getRunBundle

Get the run bundle for a workflow run. Note that this method uses a transfer format that supports the use of MTOM.

getRunStdout

Get the standard output from the execution engine. An empty string when the execution engine has not yet started.

getRunStderr

Get the standard error from the execution engine. An empty string when the execution engine has not yet started.

getRunLog

Get the detailed log contents from the execution engine. An empty string when the execution engine has not yet started.

getRunUsageRecord

Get the resource usage description of the execution engine, or null when the execution engine has not yet finished.

Input and Output Control

getRunInputDescriptor

Returns a description of what inputs are expected by a particular workflow.

getRunInputs

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.

setRunInputPortFile

Configure an input to take its value from a file in/beneath the job's working directory.

setRunInputPortValue

Configure an input to take its value directly from the supplied string.

setRunInputPortListDelimiter

Configure an input port to split its value into a list of values prior to supplying them to the workflow inside the workflow run.

setRunInputBaclavaFile

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.

getRunOutputDescription

Get a description of what outputs have been provided.

getRunGenerateProvenance

Get whether a run bundle (containing provenance) will be created. For compatibility reasons, this defaults to not producing provenance.

setRunGenerateProvenance

Sets whether a run bundle (containing provenance) will be created. This is only meaningful before the run state is set to Operating.

getRunBundle

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.

setRunOutputBaclavaFile

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.

getRunOutputBaclavaFile

Get the name of the Baclava file that will have the run outputs written to it.

File Operations

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.

getRunDirectoryContents

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.

destroyRunDirectoryEntry

Delete a subdirectory or file.

getRunDirectoryAsZip

Given a directory, return that directory plus all its contents (files, subdirectories) as a ZIP file.

makeRunDirectory

Create a subdirectory of a directory. Note, you should not create the out subdirectory; that will be created by the workflow engine.

getRunFileContents

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.)

getRunFileContentsMTOM

Get the contents of a file. (MTOM-enabled.)

getRunFileType

Get an estimate of the content type of a file.

getRunFileLength

Get the length of the contents of a file.

makeRunFile

Create an empty file.

setRunFileContents

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.)

setRunFileContentsMTOM

Set the contents of an existing file. (MTOM-enabled.)

Event Listeners

Compatibility Note

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.

getRunListeners

Get a list of listeners attached to a particular run.

addRunListener

Attach a new listener to a particular run. The listener must be of a recognised type.

getRunListenerConfiguration

Get the configuration document of a particular listener. The configuration document can only be read, not written.

getRunListenerProperties

Get the list of properties supported by a particular listener.

getRunListenerProperty
setRunListenerProperty

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:

stdout

The standard output stream from the workflow executor process.

stderr

The standard error stream from the workflow executor process.

exitcode

The exit code of the workflow executor process. Empty if not yet exited.

notificationAddress

The URI to push termination notifications to. If empty, no notifications are pushed (but they are always made available by the Atom stream).

usageRecord

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.

getRunOwner

Get the identity of the owner of the run. Note that the owner always has full permission to modify and read the run.

listRunPermissions

List the non-deny permissions granted by the owner.

setRunPermission

Grant a particular permission to a user.

getRunCredentials

List the credentials given to a run to use when contacting other services.

setRunCredential

Give a credential to a run to use when contacting other services.

deleteRunCredential

Stop a run from using a particular credential when contacting other services.

getRunCertificates

List the server certificates that will be trusted when contacting other services.

setRunCertificates

Add to/update the server certificates that will be trusted when contacting other services.

deleteRunCertificates

Remove from the server certificates that will be trusted when contacting other services.

Labels
  • None