Workflow and REST How-to

---

 
Front Matter

Copyright (c) 2003 Dave Kuhlman

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Abstract:

Contents

• Front Matter
  • 1 Introduction
  • 2 fluxappgen
  • 3 fsmappgen
  • 4 How to Write Your Own Application Generator
  • 5 How to Generate a Client GUI
    • 5.1 What it does; how it works
    • 5.2 How to use it
• End Matter
  • Acknowledgements and Thanks
• About this document ...

1 Introduction

Our goal is to expose BP (business processes) or WFs (workflows) across the Web in a REST style. This document describes facilities for generating the skeleton of Web applications that run on top of the Quixote application server. We can perform this process in two steps:

1. Translate the specification of a BP/WF to an XML document that describes the process as an FSM (finite state machine).

2. Generate the skeleton of a Quixote application from the FSM XML document.

This document describes support for the second stage of this process (i.e. generating an application skeleton).

A few implications:

• By breaking the task into these two phases can implement smaller, simpler tools for tasks such as the following: (1) analyze the BP/WF; (2) translate the specification of the BP/WF into an FSM/XML document usable by fluxappgen or fsmappgen (see below); (3) produce documentation on the FSM or its implementation; etc.

• By producing an XML document that describes the BP/WF as an FSM, we provide a way to share the description of the BP/WF and the FSM that implements it with other applications.

• The application generators are actually quite simple. What's more, their implementation in Python makes them especially easy to read and modify. Therefore, user/developers will be able to modify and extend the application generators so that they produce special purpose stubs, comments, functions, etc.

Samples and example code are available in workflow_examples.zip.

Note that portions of this code were taken from flux. You can find flux at http://sourceforge.net/projects/lleu. You should consult the flux license, and I hope you will respect it.

2 fluxappgen

Here is a brief description of fluxappgen:

• fluxappgen implements classes that represent workflows. A workflow is (roughly) a FSM (finite state machine), and can be used to represent business processes.

• fluxappgen is based on the classes defined in flux. See http://sourceforge.net/projects/lleu.

• fluxappgen generates the skeleton of a Quixote application. See REST and FSM and BP for Quixote How-to for more information on this style of Web application.

• fluxappgen can save Workflows to and read them from an XML document.

Here is the help message produced by typing "python fluxappgen.py -h":

python fluxappgen.py -h

Usage: python fluxappgen.py [ options ] <infilename> [ <outname> ]

Options:
    -s, --state <module>    Module implementing parser and data structures
                                for XML doc.
    -m, --mode <mode>       Modes -- See below.

Modes:
    package_class           Generate Quixote/REST app.
                                Container: package  State: module/class
    module_class            Generate Quixote/FSM/REST app.
                                Container: module  State: class
    module_function         Generate Quixote/FSM/REST app.
                                Container: module  State: function
    test1                   Generate some classes and XML output.
    test2                   Read an XML file, create classes, and re-generate
                                XML output.

Examples:
    python fluxappgen.py -m package_class workflow1.xml WorkflowAppDir
    python fluxappgen.py -m module_class workflow1.xml workflow1.py
    python fluxappgen.py -m module_function workflow1.xml workflow1.py
    python fluxappgen.py -m test1
    python fluxappgen.py -m test1 > workflow1.xml
    python fluxappgen.py -m test2 workflow1.xml

And here is some explanation for the different modes or operations:

• test1 -- Create instances of the workflow classes (Workflow, State, and Transition), then export these instances to an XML document that describes the workflow. Use this mode to produce a sample of the XML document which represents a workflow. You can modify and extend this document to describe your own workflow. The implementation of test1 will help you learn how to create workflow objects with Python code.

• test2 -- Read an XML document that describes a workflow (e.g. one generated by using test1), create the instances of workflow classes that it represents, then re-generate the XML document. You can look at the implementation of test2 to learn how to read the XML workflow document and how to export the workflow classes to XML.

• package_class -- Read an XML workflow document and generate the skeleton of a Quixote application (in the REST FSM style). The generated application is contained in a Python package (i.e. a directory); each state (of the FSM) is implemented in a Python class in its own separate python module.

• module_class -- Read an XML workflow document and generate the skeleton of a Quixote application (in the REST FSM style). The generated application is contained in a single Python module; each state (of the FSM) is implemented in a separate Python class.

• module_function -- Read an XML workflow document and generate the skeleton of a Quixote application (in the REST FSM style). The application is contained in a single Python module; each state (of the FSM) is implemented in a separate Python function.

3 fsmappgen

fsmappgen also generates skeletons of REST/FSM applications that run on top of Quixote. It produces applications very similar to those produced by fluxappgen. The input FSM/XML document is different, but similar. The classes that represent the elements in the FSM/XML document were initially generated by generateDS.py (http://www.rexx.com/~dkuhlman/#generateDS), and then extended, e.g., with the capability to generate the Quixote/FSM/REST application.

Here is the help message produced by typing "python fsmappgen.py -h":

Usage: python fsmappgen.py [ options ] <infilename> <outname>

Options:
    -s, --state <module>    Module implementing parser and data structures
                                for XML doc.
    -m, --mode <mode>       See below.

Modes:
    package_class           Generate Quixote/REST app.
                                Container: package  State: module/class
    module_class            Generate Quixote/REST app.
                                Container: module  State: class
    module_function         Generate Quixote/REST app.
                                Container: module  State: function
    wxg                     Generate .wxg file for wxGlade

Examples:
    python fsmappgen.py -m package_class workflow1.xml WorkflowAppDir
    python fsmappgen.py -m module_class fsm1.xml app1.py
    python fsmappgen.py -m module_function fsm1.xml app1.py
    python fsmappgen.py -m wxg fsm1.xml test.wxg

And here is some explanation for the different modes or operations:

• package_class -- Read an XML workflow document and generate the skeleton of a Quixote application (in the REST FSM style). The application is contained in a single Python package (i.e. a directory); each state (of the FSM) is implemented in a Python class in its own separate Python module.

• module_class -- Read an XML workflow document and generate the skeleton of a Quixote application (in the REST FSM style). The application is contained in a single Python module; each state (of the FSM) is implemented in a Python class.

• module_function -- Read an XML workflow document and generate the skeleton of a Quixote application (in the REST FSM style). The application is contained in a single Python module; each state (of the FSM) is implemented in a Python function.

• wxg -- Generate a .wxg client user interface file for wxGlade and wxPython. More details are below.

4 How to Write Your Own Application Generator

This section makes the following assumptions: First, you are dissatisfied with the two application generators described above (fluxappgen and fsmappgen). Second, your application can be described by an FSM (or an FSM digraph). And, third, that you have a representation of your application in an FSM/XML document.

The first option you should consider is to begin with the source code for either fluxappgen or fsmappgen and then to extend and modify that implementation. If you choose this strategy, I'll assume that you can figure out the source code for yourself. The remainder of this section, therefore, discusses implementation an application generator from scratch. However, since that strategy is the same one used to implement fluxappgen and fsmappgen, the following discussion may of use in learning how to modify and rework either fluxappgen or fsmappgen.

Implementing an application generator is easier than you might think. Some of the infrastructure and tools are available. And, the rest follows a very orderly process. There are also examples in workflow_examples.zip. Here, briefly, are the steps in that process:

1. Use generateDS.py to generate a Python subclass file. You can find at generateDS.py http://www.rexx.com/~dkuhlman/#generateDS. Something like the following will generate (1) mysups.py containing super-classes that implement the FSM/XML element classes and (2) mysubs.py containing sub-classes that you can extend:

   python generateDS.py -o mysups.py fsm.xsd
   python generateDS.py -s mysubs.py fsm.xsd
   

   Or, combining the above into one operation:

   python generateDS.py -o mysups.py -s mysubs.py fsm.xsd
   

   An alternative is to use the flux FSM document definition. For example:

   python generateDS.py -o mysups.py -s mysubs.py flux.xsd
   

2. Design the structure of your application. Several models are described in REST and FSM and BP for Quixote How-to.

3. Add a "generator" function to the module. This method should (1) parse the FSM/XML document to produce a document object (i.e. an instance of class fsm/fsmSub) and (2) use that document object to call the generator method in class fsmSub.

4. Add a method to each of the classes fsmSub, stateSub, transitionSub, etc. fluxappgen and, more closely, fsmappgen can serve as models. Here is a bit of simple-minded guidance for these methods, which I'll discuss in terms of fsmappgen, but which are also loosely applicable to fluxappgen:
   • To class fsmSub (class workflowSub for flux), add a method that (1) creates the container for the application (e.g. a Python module), (2) inserts some header code and (later) some footer code, and (3) calls a method in each instance of class stateSub.

   • To class stateSub, add a method that (1) generates the container for a state (e.g. a Python module or class or function) and (2) calls a method in each instance of class transitionSub.

   • To class transitionSub, add a method that generates code which (1) checks a condition (to select the transition), (2) performs an action, and (3) transfers to (or sets the name of) the next current state.

5 How to Generate a Client GUI

While it is relatively easy to implement client applications that interact with the FSM REST server-side applications that we've seen generated above, creating a graphical user interface (GUI) to accept input information from a human user so that it can be fed to the server application is a more problematic and laborious task. This section describes a feature of fsmappgen that can save a great deal of the labor involved in completing that task.

5.1 What it does; how it works

The FSM XML document that describes an FSM (the same document type from which we generated application skeletons (above) contains specifications of input items. This capability enables you to generate a Python module containing a wxPython frame for each state in your FSM. This frame contains a wxPython input control for each input item specified in the FSM XML document.

This capability works are follows:

1. Use the wxg mode of fsmappgen to generate a .wxg file. The XML document that is generated is of the type used by wxGlade to save and load the definition of a GUI application.

2. Use wxGlade to load the .wxg file, and then to generate Python code that implements the application.

In order to use this, you will need to install wxPython and wxGlade.

5.2 How to use it

1. Run fsmappgen, for example, as follows:

   python fsmappgen -m wxg fsm_plants.xml test.wxg
   

   This will produce a file test.wxg, which is an XML file that contains the GUI definition.

2. Start up wxGlade. Load the .wxg file with the Open item in the File menu. Then generate the Python code for the application by selecting the Generate Code item from the File menu.

   Note that the Python code will be generated into the directory and file that is stored in the .wxg file (in the path attribute of the application element). fsmappgen sets this to the same directory and file name as the .wxg file with ``wxg'' replaced with ``py''. You can change this in wxGlade in the application property dialog.

 
End Matter

Acknowledgements and Thanks

Thanks to the implementors of Quixote for producing an exceptionally usable application server that is so suitable for REST.

Thanks to Juan David Ibáñez Palomar <[email protected]> for flux.

Thanks to Alberto Griggio <[email protected]> for wxGlade.

About this document ...

This document was generated using the LaTeX2HTML translator.

LaTeX2HTML is Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The application of LaTeX2HTML to the Python documentation has been heavily tailored by Fred L. Drake, Jr. Original navigation icons were contributed by Christopher Petrilli.

---

Workflow and REST How-to

---

Release 1.01, documentation updated on Feb 20, 2003.