Weblog

This is a short introduction how to start with xowf.

xowf (short form for XoWiki Content Flow) is a workflow package for XoWiki. See below for some more information about xowf:

• Gustaf Neumann: XoWiki Content Flow -- From a Wiki to a Simple Workflow System, in: Proceedings of 7th OpenACS / DotLRN Conference, Valencia, Spain, November, 2008 [pdf]
  Slides: http://nm.wu-wien.ac.at/research/publications/b766.pdf

• Gustaf Neumann and Selim Erol: From a social wiki to a social workflow system, in: D. Ardegna and M. Mecella and J. Yang (ed) , Business Process Management Workshops 2008 LNBIP 17, 698-708, Milan, Italy, September, 2008 [pdf]
   
• Monika Andergassen, Victor Guerra, Karl Ledermüller, Gustaf Neumann: Browser-Based Mobile Clickers: Implementation and Challenges, in: IADIS International Conference - Mobile Learning 2012, Berlin, Germany, March, 2012 [pdf]

Installation:

Starting with OpenACS 5.9.0, xowf can be installed via repository via http://YOURSITE/acs-admin/install/.

For earlier versions, xowf can be obtained from git://alice.wu.ac.at/xowf

   cd OPENACS/packages/
   git clone git://alice.wu.ac.at/xowf 

Copy the folder under .../packages and install the package as ususal:

• browse to http://YOURSITE/acs-admin/apm/
• click on "Install packages", select "xowf", click on "Next -->", ... and restart the server.

First Steps:

At this point, we expect the admin to have an instance of xowf created (e.g. with the name /xowf), and the user is on the index page and sees the usual xowiki start page.

1. Create a Parameter.form for flexible configuration:

   Go to the admin page (e.g. xowf/admin) and add an xowiki::Form with the following content. Enter the content of the field Form not in WYSIWIG mode, but switch to HTML source code before entering the content. The Form content has to have an outer HTML form element.

   Name	en:Parameter.form
   Title	XoWiki Parameter Form
   Template
   Form	<form> @MenuBar@ @production_mode@ @with_delicious@ @with_digg@ @with_general_comments@ @with_notifications@ @with_tags@ @with_user_tracking@ @_description@ @_nls_language@ </form>
   Form Constraints	MenuBar:boolean,horizontal=true production_mode:boolean,horizontal=true,default=t with_delicious:boolean,horizontal=true,default=f with_digg:boolean,horizontal=true,default=f with_general_comments:boolean,horizontal=true,default=f with_notifications:boolean,horizontal=true,default=f with_tags:boolean,horizontal=true,default=f with_user_tracking:boolean,horizontal=true _page_order:omit _description:omit

   Save the form (press OK button)

   In case you get an error from OpenACS saying that you are not allowed to enter a FORM tag, add to the Kernel parameter "AllowedTag" a "*" (under /acs-admin), saying that every tag will be allowed in this instance of OpenACS.

2. Now view the en:Parameter.form (i.e. on the index page, click on XoWiki Parameter Form. When you view en:Parameter.form, you will see the fill-out link. Press on this to create a set of parameters (a so called parameter page), and save these, e.g. under the name en:parameters
    
3. Go the the admin page (e.g. xowf/admin) and click on the button "Parameters" which brings you to the package instance parameter configuration. Enter en:parameters as parameter_page and save these settings.
    
4. Now go to the start page of the package (e.g. /xowf). Now, you should see a menu bar on the start page.

   In the next step, we provide the means to create workflows. This happens similar as before: we create another form. On the menu par, click New->Form to create an xowiki::Form similar as before and enter the following fields:

   Name	en:Workflow.form
   Title	Workflow Form
   Template	@_text@ @workflow_definition@ Form Constraints: @form_constraints@
   Form	<form> @workflow_definition@ @form_constraints@ @_text@ </form>
   Form Constraints	workflow_definition:workflow_definition form_constraints:form_constraints {_title:label=Workflow Title}

   Save this form as well. This form defines two fields, which are for the workflow definition essential: the workflow_definition and the form_constraints. The workflow_definition is the place, where one defines the semantics of the workflow, and the form_constraints are the default form constraints for all forms in this workflow.

5. In order to create a workflow application, view the newly created en:Workflow.form (page with the title Workflow Form) and enter some workflow definitions by clicking on the fill-out link (exactly the same as before, when we created the page en:parameters as instance of en:Parameter.form):

   Name	en:simple.wf
   Title	My first workflow
   Workflow definition	my set debug 1 my set autoname 1 Action save Action publish -next_state published -proc activate {obj} { $obj set_publish_status ready } Action unpublish -next_state initial -proc activate {obj} { $obj set_publish_status production } State initial -actions {save publish} State published -actions {save unpublish}
   Form Constraints	_name:label,help_text= _page_order:omit @table_properties:publish_status=all @table:_name,_title,_publish_status,_last_modified

   Save this page. Note that this definition of the workflow application is an instance of the en:Workflow.form. In order to see all workflow definitions of this xowf instance, one can visit the en:Workflow.form and press view-instances there. As naming conventions, we use the ending .form for forms and .wf for workflows. In general, one could use arbitrary names here, but using following these naming conventions helps to keep the overview when many workflow definitions exist in one instance.
   
   The workflow definition en:simple.wf manages the live-cycle of a page which might be published and unpublished. The workflow has two states, namely initial and published. This workflow definition provides means to configure additional actions and to execute code, when the actions are activated. In our definition, we have the actions save, publish and unpublish. The action publish is valid in  state initial, the action unpublish in state published, an the action save is valid in both states.
   
   When a page is created first, it has a value of production in the OpenACS content repository (we have defined publish_status production in the parameter page above). Changing the publish status means for the OpenACS content repository to switch the value of the attribute publish_status, which is performed in the methods activate of the actions publish and unpublish.
   
   In this example, the workflow definition is just here to switch the publish status of the entry. In general, the workflows typically have additional attributes, they require different forms for different user-roles in different states, and they will be assigned to different users (assignees) that have to perform actions, some actions will be triggered by different programs etc. All mentioned functionalities are supported by xowf.

6. In order to create a workflow instance, we perform the same kind of actions as before: View the workflow definition, where one can create instances or list instances as mentioned above. The view page creates automatically from the definition above a state diagram, when the program dot is installed (on eg. Ubuntu systems, you might install dot by installing graphviz with "sudo apt-get install graphviz"). dot is part of the graphviz package.
   

7. The example above created the form automatically. Typically, a workflow might show in different states different forms (and maybe showing different users different forms). Such forms can be defined as separate wiki pages of type ::xowiki::Form (New -> Form). For details about xowiki Forms, see http://alice.wu-wien.ac.at:8000/xowiki-doc/#forms. As a second example, we show a simple ticket workflow, which uses a form named en:ticket.form, which should be used all all workflow states (alternatively, the form can be define with the parameter -form on every State definition below). 

   Name	en:ticket.wf
   Title	Simple ticket
   Workflow definition	my set autoname 1 Action submit -next_state opened Action resolve -next_state resolved Action close -next_state closed Action reopen -next_state opened Action accept -next_state finished State parameter { {form en:ticket.form} {view_method edit} } State initial -actions submit -form_constraints { _title:text,required _creator:text,required _text:richtext,required,label=Problem } State opened -actions {resolve close} -form_constraints { _description:textarea,required,rows=15,label=Diagnosis } State closed -assigned_to creator State resolved -actions {reopen accept} -assigned_to creator(initial) State finished
   Form Constraints	@table:_name,wf_current_state,wf_assignee,_creator,_last_modified _title:label,label=Subject,optional _creator:label,label=Creator _text:label,label=Problem,style=,disabled=true _nls_language:hidden

   
   The form can be defined e.g. as follows (for the content for the "Form" part, you might have to switch to the HTML source code representation of the form field, as described in point 1. above)
    

   Name	en:ticket.form
   Title	Ticket Form
   Template	@_text@ State: @wf_current_state@
   Form	<form> @wf_current_state@ @_name@ @_title@ @_creator@ @_text@ @_description@ </form>
   Form Constraints	wf_current_state:current_state _page_order:hidden _name:label,help_text=

   
   When instances of the workflow are created, the already visited states of the workflow will be rendered in different colors (this is achieved via the form-field of type current_state). In general, in workflows, various types of form-fields are used, which might be predefined or user-defined. Form-field might change their types (e.g. Problem text is in the initial state editable (type richtext) and required (as defined in en:ticket.wf), and later it is non editable (type label in the default form constraints, also defined in en.ticket.wf)
    
8. A set of example workflow definition can be found here http://alice.wu-wien.ac.at:8000/xowf/ (kind of a moving target)