Requirements

For the client and the server:

  • Java: Standard (Oracle) Java SE v 6 or higher

For the server:

  • OS: Linux or Mac OS X
  • Sun Grid Engine / Open Grid Scheduler (contact us for support of job schedulers)
  • bash shell interpreter
  • SSH server with public key authentication and port forwarding enabled

For the client:

  • OS: Either Windows, Mac OS X, or Linux (with GTK)
  • SSH client, and a user's authentiation should be 'silent' (ex: public key authentication)

Download and Run

How to Run

The following instructions to run Workflow Commander use the Lite Edition filenames, but they work similarly for the Standard Edition.

  • Mac OS X:
    • Download: wfcommander-lite-macosx.jar
    • Run client: java -XstartOnFirstThread -jar wfcommander-lite-macosx.jar
    • Run server: java -jar wfcommander-lite-macosx.jar -S
  • Linux (GTK):
    • Download: wfcommander-lite-linux.jar
    • Run client: java -jar wfcommander-lite-linux.jar
    • Run server: java -jar wfcommander-lite-linux.jar -S
  • Windows :
    • Download: wfcommander-lite-windows.jar
    • Run client: java -jar wfcommander-lite-windows.jar
    • Run server: java -jar wfcommander-lite-windows.jar -S

Notes

  • Both the server and client processes will create a directory in the home directory of the user running the process. The directory is named .wfcommander
    • This directory will store information about the execution state for each job
    • On the server, the server process will also use this directory to store the standard output and standard error streams of each job, as given by Sun Grid Engine, if no locations are given in the user's workflow file
    • Workflow Commander does not create any installation files, and keeps its all of all of its internal files here in plain text (some in JSON format)
    • Deleting the files in this folder is all it takes to 'reset' or 'uninstall' the program from your computer.
  • After running a workflow, save the updated workflow with run status information to disk before loading another workflow or closing the program

File Format

The following table explains how the workflow XML file format is structured. The format is designed to be as flexible and minimal as possible.

The table also has 3 columns which explains when an element of the format must be present:

Required
This tag is required in any workflow file
Required if parent exists
This tag must exist if its parent tag exists
Optional
This tag is always optional

Structure and description of the workflow XML file format

XML tag Required Req'd if parent exists Optional Description
workflow The root - contains the entire rest of the document
meta Contains properties of the workflow not related to execution
wf-name A name for the workflow
wf-ver Version of this workflow
wf-format-ver Version of the workflow format (where workflow format is what is described by what you're reading)
parent Contains information of the workflow from which this workflow is derived (Note: not currently used)
parent-ver Version of the parent workflow
parent-file File name/file path of the parent workflow
parent-hash Hash value signature of the parent workflow file
jobs Contains all of the jobs in the workflow
job Contains properties of a job
id Job id number as given by the server's grid engine
name A unique name to describe the job
desc A description of the job
prog-name The name of the program that the job runs
prog-ver Version of the program that the job runs
prog-exec-loc The full path/location of the executable that the job's program needs to launch (ex: for a Java-based program called "JavaSwingApp", the path might be /usr/bin/java)
prog-exec-ver The version of the executable that the job's program needs to launch (ex: for a Java-based program called "javaSwingApp", the version might be "1.6.0")
prog-args Represents command-line arguments needed by the program executable. No args means the tag is empty, that is, <prog-args />
arg A command-line argument
prog-opts Represents command-line options supported by the program executable. No options means the tag is empty, that is, <prog-opts />
opt Represents a command-line option supported / understood by the program executable. For command-line options that are merely a flag (ex: --debug), the val tag should be left empty (ex: <opt><flag>--debug</flag><val /></opt>)
flag Also called elsewhere as a switch, this part of the option signifies what type of action should be taken by the program
val Also called elsewhere as a switch argument or option argument, this passes additional information related to the option
std-out-file The full path on the server of the file to which the standard output stream of the program should be saved
std-err-file The full path on the server of the file to which the standard error stream of the program should be saved
deps Contains the dependencies of this job
dep Name of a job in this workflow that must finish executing before this job can begin
task-statuses Contains the execution status(es) of this job. This information is filled automatically by the workflow editor, not meant to be modified manually.
task For job arrays, this represents the execution status for a task. For non-array jobs, no more than one task element can exist.
task-id Known as a task id, array id, or job index, this is the unique identifier within an array job to represent this task. The value contained in this tag for non-array jobs is selected out of the valid range for array jobs (ex: -1).
status The status of this job array task (or of the entire job for non-array jobs)
array Properties to describe how the grid engine should run this job as an array
start The start of the range for the task id numbers
end The end of the range for the task id numbers
step The increment value for the range of the task id numbers (ex: start=1,end=7,step=2 -> 1,3,5,7)
index-var The name of the variable used by the grid engine to indicate the task id number within the command (ex: $SGE_TASK_ID)