SCUFL2 is the new (since Taverna 3) mechanism for specifying Taverna workflows. SCUFL2 defines a model, a workflow bundle file format (.wfbundle), and a Java API for working with workflow structures. SCUFL2 is the workflow language for Taverna 3, and replaces Taverna 2's t2flow format.

Summary¶

SCUFL2 is the Taverna 3 mechanism for specifying Taverna workflows. SCUFL2 adopts Linked Data technology and preservation methodologies to create a platform-independent workflow language that can be inspected, modified, created and executed.

SCUFL2 comes with a Java API that can be used for programmatic access to read and write SCUFL2 workflow bundles. A workflow bundle is a structured ZIP file with the workflow definitions included as XML documents. Those workflow documents are described by an XML Schema and are also valid RDF/XML. The XML Schema allows tools to read and write SCUFL2 workflow definitions as regular structured XML. The RDF allows RDF-enabled tools to link workflow definitions with external resources.

The workflow structure is defined using an OWL ontology and annotated with URIs so that third parties can form semantic statements about any component of a Scufl2 workflow, for example to state that a particular service produces outputs of a certain type, or that a data link was added by a specific researcher.

Semantic annotations and a manifest for the bundle declare the purpose of, and links between the different components forming a workflow. This allows third parties to extract and append annotations about data and services used by the workflow.

Motivation¶

The t2flow serialization format suffers from being very close to the Java object model, and contains various items that are simply Java beans serialized using XMLBeans. As the t2flow format is very verbose, it can be difficult to deal with for third party software to do inspection ("Which services does this workflow use?"), modification ("Change all calls to broken.com to fixed.com") and generation ("Build a custom workflow from a button").

Developers have informed us that the old SCUFL format of Taverna 1 was significantly easier to work with. However, this format also has its caveats, like no schema, unidentified ways to extend service definitions for Taverna plugins and not supporting various new features in the Taverna 2 engine.

We have therefore decided to form a new serialisation format for workflows, called SCUFL2.

Overview¶

SCUFL2 consists of:

• SCUFL2 language
• SCUFL2 Workflow Bundle format
• SCUFL2 API for Java

Scufl2-WorkflowBundle¶

The entry point of the Taverna Workflow Bundle.

Defines the workflows and profiles of a Taverna Workflow Bundle. The main workflow is also normally defined, which would be the top-level workflow to execute. The profiles defines how these workflows can be realised and executed on different environments, one of which can be suggested as the main profile.

Bundle path and root files¶

The workflow bundle document in RDF/XML format should be in in /workflowBundle.rdf within the bundle archive.

If the archive is a workflow bundle, i.e. /mimetype is application/vnd.taverna.scufl2.workflow-bundle, then the META-INF/container.xml can define root files at alternative paths and media types. This specification requires that one of those formats is application/rdf+xml according to this specification.

Example META-INF/container.xml: (may be outdated)

<?xml version=&quot;1.0&quot;?>
<container version="1.0"
    xmlns=";urn:oasis:names:tc:opendocument:xmlns:container">
    <rootfiles>
        <rootfile full-path="workflowBundle.ttl"
         media-type="text/turtle" />  
         <rootfile full-path="workflowBundle.rdf"
         media-type="application/rdf+xml" />  
    </rootfiles>
</container>

This defines the RDF/XML root file to be /workflowBundle.rdf - with workflowBundle.ttl being an alternate representation the resource in Turtle format.

SCUFL2-compliant workflow bundle writers:

• Must set the bundle mimetype to application/vnd.taverna.scufl2.workflow-bundle
• Must add a workflow bundle document in application/rdf+xml format
• Should store the workflow bundle document in /workflowBundle.rdf
• Must not contain a resource /workflowBundle.rdf which is not the workflow bundle document
• If the application/rdf+xml representation is not in /workflowBundle.rdf, the writer must include META-INF/container.xml with the required <rootfile> entries.
• META-INF/container.xml, if present, must contain one and only one rootfile with the media-type application/rdf+xml. rootfiles of other media-types may be included, but their formats and restrictions are not defined by this specification.
• May Add additional representation of the workflow bundle document (and other documents). Alternates of the workflow bundle document should be included in the META-INF/container.xml, but only if they can be considered to fully specify the workflow bundle as in the RDF/XML format. (So for instance a text/html or image/png representation would not normally be considered a rootfile if it does not include all the structural information from the RDF/XML representation as specified here)

It is possible to include a workflow bundle document within a different kind of archive or bundle, for instance in a data bundle. In this case the bundle is not considered an application/vnd.taverna.scufl2.workflow-bundle - but producers of such archives:

• Should store the workflow bundle document in /workflowBundle.rdf, unless the workflow bundle is not to be considered to have a 'main' or 'prominent' role within the archive. (For instance if the archive is a collection of workflow bundles).
• Should have a mimetype and META-INF/container.xml resource which declares the archive's main entry point, like the data bundle document. The mime type must not be application/vnd.taverna.scufl2.workflow-bundle and the root files should not be the workflow bundle document.
• Should link to the workflow bundle document from a resource within the archive which (ultimately) is linked to from one of the rootfile documents. Such documents should be in RDF/XML format.
• Should declare the media type of the RDF/XML workflow bundle document as application/rdf+xml in its META-INF/manifest.xml

SCUFL2 compliant workflow bundle readers:

• Should assume that /workflowBundle.rdf - if present - is the root workflow bundle in the application/rdf+xml format specified here.
• Should assume that if the archive's mimetype is application/vnd.taverna.scufl2.workflow-bundle, then the rootfile in META-INF/container.xml with the media type {{application/rdf+xml}) is the root workflow bundle document.
• May assume that any alternate formats listed as a rootfile in a application/vnd.taverna.scufl2.workflow-bundle archive would fully cover the specification of the RDF/XML representation, and read such formats instead.
• May assume that any application/rdf+xml document with a xsi:type="WorkflowBundleDocument" can be parsed according to the Scufl2 XML schema

Identifiers¶

Workflow bundles and their resources must be declared with relative identifiers within the archive. In a application/vnd.taverna.scufl2.workflow-bundle archive, the workflow bundle must be identified as the root of the archive. If the Workflow Bundle document is in workflowBundle.rdf within the archive, the workflow identifier is ./.
This should be achieved by setting xml:base="./" and rdf:about="".

This means that one can mint a URI to refer to resources within the bundle archive, including the workflow bundle, workflows and representations. If http://example.com/myWfBundle.scufl2 returns a Scufl2 workflow bundle archive of the content type application/vnd.taverna.scufl2.workflow-bundle,
then (assuming default structure of the archive):

• http://example.com/myWfBundle.scufl2 identifies for the Workflow Bundle representation (the archive)
• http://example.com/myWfBundle.scufl2/ identifies the Workflow Bundle (as described here)
• http://example.com/myWfBundle.scufl2/workflowBundle.rdf identifies the Workflow Bundle representation in RDF/XML
• http://example.com/myWfBundle.scufl2/workflow/HelloWorld/ identifies the "HelloWorld" workflow within the bundle
• http://example.com/myWfBundle.scufl2/workflow/HelloWorld.rdf identifies the "HelloWorld" workflow representation in RDF/XML
• http://example.com/myWfBundle.scufl2/workflow/HelloWorld/processor/Hello/ identifies the "Hello" processor within the "HelloWorld" workflow.

Embedded workflow bundles¶

If the archive is another type of bundle which includes the workflow bundle (but is not primarily playing the role as the format for this workflow bundle), the local workflow identifier should be unique within the archive. This is easiest achieved by using the same folder technique as for the workflow representations:

• workflowBundle1.rdf can define workflowBundle1/
• exampleWorkflowBundles/hello.rdf defines exampleWorkflowBundles/hello/

Such embedded workflow bundles should include their constituent representations (such as workflow/HelloWorld.rdf) within that folder, for instance exampleWorkflowBundles/hello/workflow/HelloWorld.rdf to define exampleWorkflowBundles/hello/workflow/HelloWorld/ - but could also be shared among bundles, for instance both workflowBundle1.rdf and workflowBundle2.rdf might refer to workflow/Shared.rdf.

Global workflow bundle identifiers¶

Workflow bundles should declare a sameBaseAs reference to a globally unique non-informational URI.

Anyone can generate such a URI using the form http://ns.taverna.org.uk/2010/workflowBundle/UUID/ - for instance http://ns.taverna.org.uk/2010/workflowBundle/28f7c554-4f35-401f-b34b-516e9a0ef731/ - including the trailing slash.

The semantics of sameBaseAs is a kind of recursive version of owl:sameAs - so also resources which URI start with the same will be included.

So if:

@prefix : <;http://ns.taverna.org.uk/2010/scufl2> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema> .

<./>     a :WorkflowBundle;
     :name "HelloWorld";
     :sameBaseAs <http://ns.taverna.org.uk/2010/workflowBundle/28f7c554-4f35-401f-b34b-516e9a0ef731/>;
     :mainWorkflow <workflow/HelloWorld/>;
     :workflow <workflow/HelloWorld/>;

<workflow/HelloWorld/>     a :Workflow;
     rdfs:seeAlso <workflow/HelloWorld.ttl> .

then also:

<./>= <http://ns.taverna.org.uk/2010/workflowBundle/28f7c554-4f35-401f-b34b-516e9a0ef731/>
<workflow/HelloWorld/> = <http://ns.taverna.org.uk/2010/workflowBundle/28f7c554-4f35-401f-b34b-516e9a0ef731/workflow/HelloWorld/>
<workflow/HelloWorld.rdf> = <http://ns.taverna.org.uk/2010/workflowBundle/28f7c554-4f35-401f-b34b-516e9a0ef731/workflow/HelloWorld.rdf>

This allows anyone to make a statement about any resource within the workflow bundle, even if the URL of the workflow bundle representation itself might change, be it on a local USB disk, DropBox folder, myExperiment, etc.

Updating the UUID¶

It is up to the software editing or creating the workflow to assign a new UUID as soon as any change has been done to any workflow, profile or workflow bundle, as this is the globally unique identifier for this workflow archive, and also the base URI for all the other resources in the archive.

Not implemented by API Scufl2 API do not yet

automatically update the workflow bundle identifier. SCUFL2-41

To update the URI, use workflowBundle.setSameBaseAs(WorkflowBundle.generateIdentifier()).

Example representation in RDF/XML¶

(may be outdated)

<?xml version="1.0"?>
<rdf:RDF xmlns="http://ns.taverna.org.uk/2010/scufl2#"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://ns.taverna.org.uk/2010/scufl2# http://ns.taverna.org.uk/2010/scufl2/scufl2.xsd http://www.w3.org/1999/02/22-rdf-syntax-ns# http://ns.taverna.org.uk/2010/scufl2/rdf.xsd"
    xsi:type="WorkflowBundleDocument" xml:base="./">
    <WorkflowBundle rdf:about="">
        <name>HelloWorld</name>
        <sameBaseAs
            rdf:resource="http://ns.taverna.org.uk/2010/workflowBundle/28f7c554-4f35-401f-b34b-516e9a0ef731/" />      
        <mainWorkflow rdf:resource="workflow/HelloWorld/" />
        <workflow>
            <Workflow rdf:about="workflow/HelloWorld/">
                <rdfs:seeAlso rdf:resource="workflow/HelloWorld.rdf" />
            </Workflow>
        </workflow>
        <!--
        <workflow>
            <Workflow rdf:about="workflow/SomeNestedWorkflow/">
                <rdfs:seeAlso rdf:resource="workflow/SomeNestedWorkflow.rdf" />
            </Workflow>
        </workflow>
        -->
        <mainProfile rdf:resource="profile/tavernaWorkbench/" />
        <profile>
            <Profile rdf:about="profile/tavernaServer/">
                <rdfs:seeAlso rdf:resource="profile/tavernaServer.rdf" />
            </Profile>
        </profile>
        <profile>
            <Profile rdf:about="profile/tavernaWorkbench/">
                <rdfs:seeAlso rdf:resource="profile/tavernaWorkbench.rdf" />
            </Profile>
        </profile>
        <rdfs:seeAlso rdf:resource="annotation/workflowBundle.rdf" />
    </WorkflowBundle>
</rdf:RDF>

This example defines the workflow bundle "HelloWorld". It contains one workflow workflow/HelloWorld, which is also the main workflow. Any additional workflows are typically nested (and nested-nested, etc) workflows bound as activities in processors). Two execution profiles are provided, and profile/tavernaWorkbench is dedicated as the main profile.

Properties¶

• name (required) gives the human readable title for this workflow archive. This is a subproperty of dc:title.
• sameBaseAs (optional) gives a unique URI which is owl:sameAs with this workflow bundle and its children.
• workflow (required) All workflows included in this bundle. Each workflow must have an rdfs:seeAlso link to the bundle resource that defines the workflow, typically workflow/workflowName.rdf corresponding to the non-information resource workflow/workflowName/.
• mainWorkflow (optional) The reference to the top-level workflow of this bundle. It is valid to have a workflow bundle without a main workflow, for instance if the bundled workflows are unconnected "workflow fragments". If there is a mainProfile the workflow bundle must also have a mainWorkflow. The main workflow must always be listed under workflow.
• profile (optional) profiles specifying how to execute the bundled workflows. In particular the profile provides a set of configured activities bound to the processors for a particular run environment. If no profiles are specified this is an abstract workflow bundle.
• mainProfile (optional) the suggested main profile. Execution platforms unable to choose between the provided profiles can select this profile as a default. It is valid to have a workflow bundle without a main profile (even if it has other profiles), but any main profile must be listed under profile.
• rdfs:seeAlso (optional) link to annotations about the workflow bundle and its content. Traditionally found in annotation/workflowBundle.rdf, which should contain further links to annotations from different sources, for instance annotation/myExperiment.rdf for annotations included from myExperiment.

Bundle links¶

The workflow bundle document is the starting point for finding all workflow bundle resources within the archive. Each of the workflows and profiles must therefore have a rdfs:seeAlso link to the bundle resource that defines it.

If alternate formats other than the required RDF/XML format is included in the bundle, these formats can therefore link to resources in other formats, for instance in an additional workflowBundle.ttl (Turtle format):

@prefix : <http://ns.taverna.org.uk/2010/scufl2#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

<./>     a :WorkflowBundle;
     :mainProfile <profile/tavernaWorkbench/>;
     :mainWorkflow <workflow/HelloWorld/>;
     :name "HelloWorld";
     :profile <profile/tavernaServer/>,
            <profile/tavernaWorkbench/>;
     :sameBaseAs <http://ns.taverna.org.uk/2010/workflowBundle/28f7c554-4f35-401f-b34b-516e9a0ef731/>;
     :workflow <workflow/HelloWorld/>;
     rdfs:seeAlso <annotation/workflowBundle.ttl> .

<profile/tavernaServer/>     a :Profile;
     rdfs:seeAlso <profile/tavernaServer.ttl> .

<profile/tavernaWorkbench/>     a :Profile;
     rdfs:seeAlso <profile/tavernaWorkbench.ttl> .

<workflow/HelloWorld/>     a :Workflow;
     rdfs:seeAlso <workflow/HelloWorld.ttl> .

Parsing/writing¶

SCUFL2 compliant writers, when producing the workflow bundle document:

• Should write the workflow bundle RDF/XML document according to the SCUFL2 XML schema, use the default namespace xmlns="http://ns.taverna.org.uk/2010/scufl2#" and declare the xsi:type="WorkflowBundleDocument"
• Must ensure the workflow bundle RDF/XML document is valid RDF/XML and includes the properties deemed required by this specification. Conforming to the XML schema should ensure this.
• Should set the xml:base property to"./
• Should set rdf:about to "" (or "./"' ifxml:base` is not set))
• Should declare a mainWorkflow and mainProfile
• Mustensure that any workflow/profile has a relative rdfs:seeAlso link to a bundle resource in application/rdf+xml which defines
  that workflow / profile.

SCUFL2 compliant readers, when parsing a workflow bundle document:

May assume that a declared workflow/profile is defined in the referenced representation. For instance, if:

<workflow>
   <Workflow rdf:about="workflow/SomeNestedWorkflow/">
      <rdfs:seeAlso rdf:resource="workflow/SomeNestedWorkflow.rdf" />
   </Workflow>   
</workflow>

then workflow/SomeNestedWorkflow.rdf> must contain a workflow definition for workflow/SomeNestedWorkflow/.
May parse the /workflowBundle.rdf as RDF/XML
May parse the {/workflowBundle.rdf}} according to the XML schema if the xsi:type="WorkflowBundleDocument" is set on the rdf:RDF element.

Scufl2-Workflow¶

The definition of a workflow, its processors, inputs/outputs and links.

• Bundle path: /workflow/\$name.n3

Each nested workflow (and nested nested workflows etc.) exists in a separate file within the /workflow/ folder in the bundle. The bundle's research object defines what is the top level workflow.

Identifier¶

Each workflow must have a unique name within the bundle's workflow files. The base part of the file name (excluding extension) must match the scufl2:name of the workflow.

Workflows used in a particular research object are globally identified as <http://ns.taverna.org.uk/2010/researchObject/$uuid/workflow/$workflowName/> - for instance <http://ns.taverna.org.uk/2010/researchObject/28f7c554-4f35-401f-b34b-516e9a0ef731/workflow/Helloworld/>.

As it can be useful to identify nested workflows included in several workflow bundles, each workflow must also have a scufl2:workflowIdentifier property, which URI must be on the form <http://ns.taverna.org.uk/2010/workflow/$uuid>, for example <http://ns.taverna.org.uk/2010/workflow/efb1cdcd-1e19-408a-885a-303c6553a672/>. It is responsibility of the software creating or modifying the workflow to generate a new workflowcIdentifier as soon as the workflow has changed. (The randomly generated UUID of the workflow must not match the UUID of a research object or any other workflow.) The owning research object should then also be assigned a new UUID. (Note that editing metadata and bindings in other files don't update the workflow, but still update the research object.)

The workflow file should set the @base to the form <workflow/$name>} so that nested resources can be referenced relatively, like {{<processor/$processorName>.

Example¶

(Outdated)

@base <workflow/Helloworld/>
@prefix scufl2: <http://ns.taverna.org.uk/2010/scufl2/ontology/> .

<>
    a scufl2:Workflow ;
    scufl2:name "Helloworld" ;
    scufl2:inputWorkflowPort <in/yourName> ;
    scufl2:outputWorkflowPort <out/results> ;
    scufl2:datalink <datalink/1>, <datalink/2> ;
    scufl2:processor <processor/Hello> .
]]>

This example defines the workflow "HelloWorld". It contains one workflow input port and one workflow output port, in addition to a single processor and two datalinks.

The nested resources for this workflow, such as InputWorkflowPort , OutputWorkflowPort, DataLink, Processor and their children should be described in the same file as the workflow itself. Additional metadata should be added to an /annotations/ file.

Properties¶

• scufl2:name (required) gives the programmatic short-name for this workflow within this bundle. This must be unique among the other workflows.
• scufl2:workflowIdentifier (required) gives the globally unique URI defining this workflow. See Identifier above.
• scufl2:inputWorkflowPort (optional) All workflow input ports defined for this workflow.
• scufl2:outputWorkflowPort (optional) All workflow output ports defined for this workflow.
• scufl2:datalink (optional) All datalinks defined between workflow and processor ports in this workflow. (Note that if this is a nested workflow, its outside links are defined in the parent workflow)
• scufl2:processor (optional) All processors in this workflow.

Bundle links¶

All nested workflow resources should also be defined in the same archive file as this workflow. Their URIs must be relative to this workflow, their type and scufl2:name. So for instance <workflow/Helloworld/processor/Hello> is a scufl2:Processor in <workflow/Helloworld>, and has a scufl2:name "Hello".

Scufl2 Profile¶

Details of the Scufl2 profile still to be added.

Taverna Workflow Bundle¶

The primary SCUFL2 file format is the Taverna workflow bundle.