View · Index
No registered users in community xowf-doc
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)
References to this Page: en:xowf