book_openwfe.txt

日常的办公系统 应用工作流框架等增加员工的基本信息、培训信息、奖罚信息、薪资信息

   can build / edit workflows with your web browser and then save
   their XML process definition. OpenWFE uses its own proces
   definition language, which is very powerful, flexible and
   which is extensible.

Chapter 3. Running OpenWFE

   Table of Contents

   Start scripts

        troubleshooting
        Starting the engine and the other components

   First web login

   This chapter focuses on getting your freshly downloaded
   OpenWFE release running. Customization and extensions will be
   described in further chapters.

Start scripts

   OpenWFE's components are server side components

troubleshooting

   Some problem resolutions.

AccessControlException for the worklist

   I experienced this with the JDK 1.4.1_03 on GNU/Linux : upon
   logging in as 'alice' or any other user, the system replied
   with 'User hasn't any rights on any store'.

   (same problem with JDK 1.4.1_04 on GNU/Linux...)

   I looked at the logs/worklist.log and remarked that the system
   threw a AccessControlException when trying to access 2 system
   properties.

   The solution is to edit the file
   $JAVA_HOME/jre/lib/security/java.policy and to add two lines :
    permission java.util.PropertyPermission "entityExpansionLimit", "re
ad";
    permission java.util.PropertyPermission "disallowDoctypeDecl", "rea
d";


   before the final line :
};


Starting the engine and the other components

   The best alternative is ./bin/owfe-suite.sh, it silently
   starts the OpenWFE suite. If you are a pyya user (you use
   python client to access OpenWFE), you can start a REST OpenWFE
   suite with ./bin/owfe-suite.sh =rest

   You can run owfe-suite.sh from anywhere, it will detect its
   position. You can override this position by setting the
   environment variable $OPENWFE_HOME

XML encoding

   By default, OpenWFE uses the ISO-8859-1 encoding when
   generating XML documents (for storing expressions and
   workitems in the filesystem or for dispatching a workitem to a
   participant.

   The start scripts of a freshly unpacked OpenWFE release
   include a commented out line for setting the encoding. This
   line can be found at the beginning of owfe-suite.sh,
   owfe-suite.bat, ...

   If you are using Xlob (for persistence to database), do not
   forget that the encoding choice has to be compatible with the
   encoding used by the database.

   Make sure that all those scripts are runnable (chmod a+x *.sh)
   On the windows platform, of course, you have to run the .bat
   files by double-clicking on them.

   When the output of each script has stabilized, you can point
   your browser towards http://localhost:7080 (I'm thinking about
   a script that would launch the 5 components at once, stay
   tuned...)

First web login

   When you're sure that the server has started, head your
   browser to http://localhost:7080. There, you may log in as
   'alice', her password is 'alice'.

   You will be presented with the workitem stores that the user
   alice has access to. As packaged, alice only has access to the
   'alpha' store.

Chapter 4. Configuration

   Table of Contents

   An overview OpenWFE's architecture

        Services and applications
        The participant map
        Listeners and dispatchers

   Worklist user management

        Roles, participants and users
        Launch permissions
        Query stores
        Modifying etc/worklist/passwd.xml directly
        SqlPasswdCodec
        User management web interface

   Putting a relational database behind OpenWFE

        XlobEpressionStore
        XlobWorkItemStore
        The relational database
        'swis', the SqlWorkItemStore
        SqlPasswdCodec
        Implementing and using a data source

   Dispatchers and listeners

        Dispatching over a socket
        Dispatching over a smtp
        Securing the dispatch
        How should the workitem get encoded

   OpenWFE as a service

        OpenWFE as a linux service
        OpenWFE as a windows service

An overview OpenWFE's architecture

   An OpenWFE workflow management system is a set of components,
   usually an engine, a worklist and an apre, plus a client
   system (most certainly a web client system).

   A component is a set of tightly integrated services. A
   component is usually figured into an OpenWFE application.

Services and applications

   In OpenWFE terminology, an application is a set of services.

   An application finds its configuration in an XML file usually
   under etc/something. For example, the workflow engine itself
   is started by the script bin/owfe.sh engine (or bin/owfe.bat
   engine) and finds its configuration under
   etc/engine/engine-configuration.xml

   This configuration file enumerates a list of services that are
   started. Working together, these services constitue an
   application.

   To continue with our engine description, the engine
   application is made of the following services :
     * An ExpressionPool, recently used expressions are cached
       here
     * An ExpressionStore, where expressions are stored on disk.
       A workflow instance is a set of expressions.
     * An ExpressionMap, a configuration service that tells what
       hides behind an expression name in a workflow definition.
       (the 'what' being a java implementation). For example,
       with this ExpressionMap, the whole engine knows that an
       'If' is implemented as a
       'openwfe.org.engine.expression.IfExpression'.
     * A WorkflowInstanceBuilder, which turns XML workflow
       definitions into workflow templates and then into workflow
       instances.
     * A WorkflowDefinitionServer. If you let Apache or IIS serve
       your wokrflow definition files, you could comment this
       service out of your engine. It's just an encapsulation of
       Jetty (http://mortbay.org/jetty) a small but powerful java
       web server.
     * A ParticipantMap, this service is very important : it's a
       mapping between participant names and what is behind them.
       Next section is dedicated to this service.
     * A History service, a small service that logs engine
       history (what the engine does with the workflow instances)
       to a file. A future implementation of this service could
       log this info into a database table.
     * A WorkItemCoderLoader, this service is used to determine
       how to encode outgoing workitems.
     * A socket Listener, the ear of the engine, workitems that
       come back from participants all come here. (But you could
       have other listeners, that would, for example, poll
       directories regularly, for incoming workitems in the form
       of XML files...)
     * A Consumer, a listener is a generic service for receiving
       stuff, what to do with it is determined by the consumer
       that the listener is linked to. In the case of an engine,
       the consumer simply hands the workitem back to the
       participant expression that ordered its dispatch.
     * A status service, which tells on a given port what is the
       status of the application (usually on port 7078). So if
       there is a running engine on your machine, you can point
       your browser to http://localhost:7078 to look at the
       engine's status.

   Each service has a unique name, known to each other service.
   They all share an 'ApplicationContext' so that they can
   retrieve each other per name and call each other methods.

The participant map

   OpenWFE separates flow definitions from who take part to them
   through the participant map. The engine doesn't care about
   participant, it just asks the participant map : please give me
   a dispatcher for this participant.

Listeners and dispatchers

   Dispatchers are available through the participant map service
   in order to transmit a workitem to a another set of
   components. A set of components may be an engine, a worklist,
   an apre, with a listener, listening for incoming workitems.

   The participant map also lists a dispatcher for any engine in
   the system : workitems have to get back to their engine for
   the flows to resume. So one might say that an engine is a
   participant.

Worklist user management

   This section details how users of the worklist are managed.
   You have to understand that users are not necessarily mapped
   one to one on workflow participants :

Roles, participants and users

   OpenWFE's workflow engine just cares about participants,
   wether they are mapped to roles or directly to users doesn't
   involve the engine level, it's tuned at worklist level.

   Out of the box, a packaged version of OpenWFE is set up to
   have 4 participants (3 roles and an engine).

Launch permissions

   If you use OpenWFE out of the box (as downloaded), you
   probably use it through its web interface.

   In order to let a user of the WUI (Web User Interface) launch
   a flow, you have to grant him the right on it.

   To do this, you have two options, either you do it through the
   WUI dedicated to user management (http://localhost:7081 login
   as admin) or you directly add an entry to
   etc/worklist/passwd.xml

Important change as of 0.6.0

   Since OpenWFE 0.6.0, launch permissions can point to lists of
   flows like this one :

<?xml version="1.0" encoding="UTF-8"?>
<flows>
    <flow>
        http://localhost:7079/flow__1.0.xml
    </flow>
    <flow>
        http://localhost:7079/launchitems/li_1.xml
    </flow>
    <flow>
        http://localhost:7079/flow__1.4.xml
    </flow>
    <flow>
        http://localhost:7079/launchitems/li_2.xml
    </flow>
</flows>



   Such lists may also contain references (URLs) to other lists.
   Beware not to create circular references, the LaunchPermission
   would then be unusable.

   The directory process-definitions/ contains a JSP named
   flow-index.jsp that lists all the flows in its directory and
   in the sub-directories. This JSP allows you to simply drop a
   flow definition into the directory and any user that has a
   launch permission pointing to flow-index.jsp will directly
   have the right to launch you flow. As released, the grant
   'launch.more' is configured with this launch permission
   (pointing to http://localhost:7079/flow-index.jsp).

   This new system has considerably reduced the size of the
   etc/worklist/passwd.xml file. New tricks are now possible :
   you could implement in whatever CGI language an equivalent of
   flow-index.jsp that takes its list out of a database or
   whatever.

Adding a launch permission through the WUI for user management

   Scroll till the the '--Grants--' section and locate the grant
   named 'launch.default'. This grant is attributed to every
   standard user (alice, bob and charly). Therefore by adding to
   it a launch permission for your flow, each of these users will
   be entitled the right to launch 'myflow 1.0'.

   In the combobox, select
   'openwfe.org.worklist.auth.LaunchPermission' and then click on
   the [+] box beneath your selection. You'll then have to enter
   the URL to your flow, for instance
   "mainEngine::http://localhost:7099/myflow__1.0.xml" and click
   on submit.

   'mainEngine' is the engineId, i.e. the participant name of the
   engine you want to run the instances of the flow. This id thus
   corresponds to an entry in etc/engine/participant-map.xml

   Once you have added the launch permission, you can click
   'commit' on the top right of the main page to let your changes
   be committed (behind the scene, the file
   etc/worklist/passwd.xml is overwritten by a new version).

   By committing, your changes are also inserted into the system
   policy service and thus your entitled users may immediately
   launch the new flow (well, its workflow definition must be
   well-formed and contain expressions known to the engine else a
   launch error will occur of course)

   While working with this web interface, you should note that
   the account 'admin' that you used to enter it is entitled an
   'openwfe.org.uman.UmanPermission'. This right belongs to the
   'user-management' grant and goes along with a read-write right
   on etc/worklist/passwd.xml

Adding a launch permission by directly editing
etc/worklist/passwd.xml

   Some people / administrators like to have a direct feeling
   with a system and thus they prefer to tweak text configuration
   files.

   Following this philosophy, you could directly modify
   etc/worklist/passwd.xml

   Thus changing :

     <grant
         name="launch.default"
         codebase="file:jars/openwfe-worklist-actions.jar"
     >
         <permission
             name="mainEngine::http://localhost:7079/flow__1.1.xml"
             class="openwfe.org.worklist.auth.LaunchPermission"
         />
   (...)
         <permission
             name="mainEngine::http://localhost:7079/flow__1.9.xml"
             class="openwfe.org.worklist.auth.LaunchPermission"
         />
     </grant>

   to :

     <grant
         name="launch.default"
         codebase="file:jars/openwfe-worklist-actions.jar"
     >
         <permission
             name="mainEngine::http://localhost:7079/flow__1.1.xml"
             class="openwfe.org.worklist.auth.LaunchPermission"
         />
   (...)
         <permission
             name="mainEngine::http://localhost:7079/flow__1.9.xml"
             class="openwfe.org.worklist.auth.LaunchPermission"
         />
         <permission
             name="mainEngine::http://localhost:7079/myflow__1.0.xml"
             class="openwfe.org.worklist.auth.LaunchPermission"
         />
     </grant>

   The web method might also scramble a bit the pretty pretting
   of passwd.xml

   If you set the parameter 'refreshEachTime' to 'true' in
   etc/worklist/worklist-configuration.xml for the service named
   'policyService', each time credentials information are
   requested (each time a user logs in), the file
   etc/worklist/passwd.xml is reloaded and reparsed. This allows
   a maximum of flexibility.

   Future implementations may include LDAP connectors for this
   'policyService' and even for the participant map itself.

   For those of you interested in knowing the mechanic of it all,
   this policy service is configured in
   etc/worklist/worklist-configuration.xml (it is named