xotcl.wu-wien.ac.at
Begin main content
Search · Index
No registered users in community xowf-intro
in last 10 minutes

First steps when starting with xowf

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 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.
    Screen View

  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)