Introduction

This document describes the basic structures of the workflow document format.

Definition

Workflows are expressed as XML documents, conforming to the schema http://www.astrogrid.org/schema/AGWorkflow/v1 (and included schema)

formatted html
http://www.astrogrid.org/maven/docs/HEAD/astrogrid-workflow-objects/schema/Workflow.html
schema definitions
http://www.astrogrid.org/viewcvs/astrogrid/workflow-objects/schema/

Schematic View

Top Level

The root of the workflow document is a <workflow> element. It has a required name attribute, and an optional description element.

Most importantly, a workflow contains a <sequence> element, which contains the list of activities to perform in this workflow.

During execution of a workflow, progress messages are added to the workflow document. These are stored in the <job-execution-record> child element of workflow. This is described in more detail in a later section.

There's also a Credentials element tree, which describes the identity and authentication of the account to run the workflow under. We'll ignore this at the moment.

Finally, there's a id attribute that occurs on many of the workflow constructs. This is used within the implementation, and should not be set when writing a workflow.

Example

In the examples in this document, I've omitted namespace declarations and prefixes for clarity. You'll need these (sadly) if writing real workflow documents by hand.. 

<?xml version="1.0" ?>
<workflow name="a workflow">
  <description>description of the workflow</description>
  <sequence>
   <!-- omitted-->
  </sequence>
  <Credentials>
   <!-- omitted -->
  </Credentials>
  <job-execution-record>
   <!-- omitted -->
  </job-execution-record>
</workflow>

Sequencing

Sequence

The <sequence> element composes a set of activities into a linear structure - they will be executed sequentially in order.

Flow

The <flow> element composes a set of activities into a parallel structure - the activities in the flow may be executed in any order, or even concurrently

Examples

<!-- execute some activities sequentially -->
<sequence>
   <step name="a">
      <-- omitted -->
   </step>
   <step name="b">
      <!-- omitted -->
   </step>
</sequence>

<!-- execute same activites concurrently -->
<flow>
   <step name="a">
      <!-- omitted -->
   </step>
   <step name="b">
      <!-- omitted -->
   </step>
</flow>

Step

The <step> element is an activity that performs a call to a CEA application. (link to cea) . This element has a required name attribute, and an optional description child element.

When a step is executed, the progress of the execution is recorded as a <step-execution-record> child element. This is covered in a later section

Tool

The step element contains a <tool> element, which specifies: the name of the CEA application to execute; which interface of the application to call; and the input and output parameter values to the tool call.

Parameter

Input and Output Parameters to a call are defined by <parameter> elements. The name attribute defines the name of the parameter, while the content of the <value> child element defines the value for this parameter. The parameter value may contain script expressions delimited by ${..} - these are evaluated into strings before the parameters are passed to CEA.

Finally the indirect attribute alters how the value of the parameter is interpreted by CEA. If set to true, the parameter value is expected to be a URI that points to a resource that contains the actual value for this parameter. If set to false (the default), then the parameter value is expected inline.

For output parameters, if the indirect attribute is set to true then the value of the parameter specifies the location to store this result. However, if the indirect attribute is set to false, then this result value will be returned direct to the JES server

Accessing Results of the Tool Execution

Sometimes the results of a CEA Tool execution are required further on in the workflow - for example, so that they can be passed to another CEA Tool, or to select branches of the workflow to execute.

The step element has an optional attribute result-var. If set, this attribute defines the name of a workflow variable in which the results computed by the CEA Application will be stored after the application finishes executing.

Once exection completes, the variable named will contain an instance of java.util.Map. The map will have entries for all output parameters that were configured to return direct. The keys in the map are are the output parameter names, while the values are the results returned from the CEA application.

Example

<step name="exampleStep" result-var="exampleStepResults">
   <description>an example</description>
   <tool name="anAuthority/aCeaApplication" interface="simpleInterface">
      <input>
          <!-- constant parameter value-->
         <parameter name="RA"><value>21</value></parameter>
          <!-- script expression referring to previously defined workflow variable -->
         <parameter name="DEC"><value>${dec}</value></parameter>
          <!-- indirect parameter value -->
                 <parameter name="Radius" indirect="true"><value>ivo://aCommunity/user#user/root/parameters.txt</value></parameter>
      </input>
      <output>
         <!-- write results to handy ftp server, uses script expression to generate timestamped output filename -->
         <parameter name="results" indirect="true"><value>ftp://aServer/myResults/results-${new java.util.Date()}.votable</value></parameter>
      </output>
   </tool>
</step>