SWAMP Index Design
* Home
* Documentation
* License
* Demo Server
* Wiki
* Screenshots
* F A Q
* Downloads
* Contact
* Credits

SWAMP is supported by:
SourceForge.net Logo

Creating a workflow resource bundle

SWAMP learns about it's workflows from workflow definition files that are read from the file system from a dedicated directory. Each workflow-type consists of a resource bundle that contains the workflow definition, configuration, mail-templates and icons.

Additionally the workflows are versioned so that the process can be changed at any time without breaking already running workflows.

All existing workflow subdirectories are scanned and parsed at the startup of SWAMP. Even while SWAMP is running, new workflow definitions or new revisions of existing workflow-types can be copied into the directory and SWAMP can be told to re-scan the directory for new workflow definitions.

Notification Templates

Notification templates are used to create the emails for users that have a new task assigned or that were created by notification-actions. On loading the workflow template, the system already checks if all needed template files are available. The path to a notification-template is relative to its workflow definition. For example when an action has configured the "notificationtemplate" attribute with the value "notifications/template.txt" the template is expected at conf/workflows/<workflowname>/<version>/notifications/template.txt. An example template looks like this:

subject=$wf.getName(): new Test-Notification
This is an example-notification of workflow: $wf.getName()

Owner of this workflow: $wf.getDatabitValue("testdataset.roles.owner")
Link to this workflow: $webswamp_link/wf/$wf.getId() 

This Message was automatically generated by the the WebSWAMP-Server at 
The first line must start with "subject=" and contains the subject of the email. The second line defines an additional x-Header line in the email. The remaining part of the template contains the text that will be sent as message body. See the example for possible velocity replacements, all velocity constructs are useable here, including if-then-else conditions and loops.

Workflow configuration files

Each workflow searches for a config file named "workflow.conf" at its resource directory. If none is found, default values will be used as a fallback.

## config file for Workflow testworkflow.
## in this file some GUI options for webSWAMP are provided


# displayed columns, should be one line.
displayedcolumns_workflowview=column_workflowid,column_workflowdescription, \
	column_nexttasks,System.start.enterDate,testdataset.roles.owner, column_state

In this file you can configure how the workflow will be presented in the GUI. The logo and icon values refer to images that get displayed in the GUI. The displayedcolumns_workflowview= line tells webswamp wich columns should be displayed when showin workflow lists. Possible values are all databit names including system databits, and some special columns:

  • column_nexttasks: Shows the next tasks.

  • column_workflowdescription: Shows the workflows description.

  • column_progress: Shows a progress bar that indicates what milestones have already been reached.

  • column_workflowid: Shows the workflow id with a link to the workflows detail page.

  • column_wficon: Shows the workflows icon.

  • column_state: Shows the workflows state (running/finished).

Please note that this just are the default values for displaying lists. Each user can change the configuration for himself to best fit his needs. The shown example workflow.conf file would result in a layout like this:

Workflow documentation and template files

Each workflow can bring its own documentation with it. The element helpcontext inside the node tags of a workflow definition contains the path to the corresponding help file. Available help contexts are displayed on the corresponding pages in webSWAMP and a complete listing of all available help pages is also available from the menu.

The documentation files are stored in the docs/ subdirectory of the workflow resource directory. Please look into the "Example" workflow for an example documentation file. The "head" file is used to display a headline on the documentation overview page.

The subdirectory templates/ of a workflow resource can contain custom Velocity template files that can be used to generate pages that are unique for that workflow. By default each workflow can provide the following templates that will replace the default ones when this workflow is displayed:

  • page_top.vm: Will replace the default page header, for example to display a custom image for each workflow.

  • menutop.vm: The navigation on the left is build from this file. This way, you can extend the navigation of a workflow with extra links to filtered views for example.

  • wflist_colours.vm: If you configured special colours for workflows in the workflow list by using the workflowlist_colour= variable in the workflow.conf file you can add an explanation to the wflist_colours.vm file which will get included at the bottom of the workflow list.

Extending elements with velocity scripting

There are several elements of a workflow definition that can be extended by embedding velocity scripts. The velocity script inside the elements is evaluated at runtime, and thus provides dynamic content at the used place. Here is a list of elements that are aware of content with included velocity scripts, and what objects are provided to be used within the scripts.

  • Every description and longdescription element from the workflow definition. (Provided references: The current workflow object as $wf and the corresponding workflow-template object as $wftemplate)

  • Notificationtemplates (Provided references: The current workflow object as $wf, the corresponding workflow-template object as $wftemplate, if called from a task, the task as $task. Links to webswamp can be generated from the varibles $app_link and $secure_app_link, see example workflow)

  • The content of a script action (Provided references: The current workflow object as $wf and a reference to the BugzillaTools object as $btools)

  • Sendevent-action (Provided references: The current workflow object as $wf for evaluating the workflow ids the event should be sent to)

Velocity scripting also provides the possibility of if-then-else conditions and loops. A velocity userguide is available at http://jakarta.apache.org/velocity/docs/user-guide.html

Valid CSS! Valid XHTML 1.0!