Eazflow

{{>toc}}

h1. [[/|Eazflow]] - Developer reference documentation

h2. Overview

h3. Introduction

The workflow is represented by a *_Process_*. During the lifetime of a _Process_, different *_Activities_* are performed on it. When an _Activity_ requests user input, a form is presented to the user. The user enters required data into the form-fields. Form-field values are stored in *_Variables_* of the _Process_. When a particular _Activity_ gets *_finished_*, a *_Transition_* to another _Activity_ is made and the next _Activity_ is *_started_*. 

Availability of _Processes_, _Activities, _Variables_ and _Transitions_ to a *_User_* is controlled by *_Access-rights_* with *_Role_*-based rules. There are two types of user _Roles_: *_Global roles_* and *_Instance roles_*. _Users_ authenticate themselves to the system (username/password). Each _User_ has a set of _Global roles_ assigned. In adition to these _Global roles_, a specific local _Instance role_ set can be supplied on each instance of _Process_. This mechanism represents situations where a user has a special position within *some* processes, e.g. the initiator, assigned solver etc.

h3. Definitions and Instances

Main types of entities (process, activity, transition, etc.) occur in definitions and instances.

*_Definition_* entities *describe* the *model* of the given workflow process, all of its possible activities, transitions, variables with their types, validation rules etc. 

Typically, the administrators will instantiate new definition entities when adding a new process definition, or introducing an activity step to an already defined process. The developers may implement new definition entity classes to provide new variable types like e.g. a PDF report.

*_Instance_* entities *represent* individual process instances, performed activities and transitions and actual variable values as they are carried out. 

Typically, the users will (mostly without realizing it) instantiate new instance entities when starting a new process, or following a transition to enter a new activity.

h2. Internals

h3. Main entities (domain classes)

h4. Process-definition classes

* "DefProcess":/embedded/eazflow/grails-app/domain/DefProcess.html - main process-definition entity class

* "DefActivity":/embedded/eazflow/grails-app/domain/DefActivity.html - base class for all activity-definition classes

** "DefAStart":/embedded/eazflow/grails-app/domain/DefAStart.html - first activity type of the process, this type of activity is started by the system when a new process is created

** "DefAUserAction":/embedded/eazflow/grails-app/domain/DefAUserAction.html  - activity type for user interaction - in this type of activity, users are filling in variable-fields and then choosing transition to the next activity

** "DefAFinish":/embedded/eazflow/grails-app/domain/DefAFinish.html - last activity type of the process, process is finished when it reaches this type of activity

* "DefTransition":/embedded/eazflow/grails-app/domain/DefTransition.html - defines a possible transition from an activity definition into another

h4. Variable (type) definition classes

* "TypeCompositeDef":/embedded/eazflow/grails-app/domain/TypeCompositeDef.html - defines a composite structure consisting of member fields (which may, recursively, also be composite, see below)

** "TypeProcessDef":/embedded/eazflow/grails-app/domain/TypeProcessDef.html - subclass of !TypeCompositeDef, defines a root for the structure of process variables (each !DefProcess has a !TypeProcessDef assigned)

* "TypeMember":/embedded/eazflow/grails-app/domain/TypeMember.html - base composite-member class - defines a member field of a composite type (!TypeCompositeDef)

** "TypeString":/embedded/eazflow/grails-app/domain/TypeString.html, "TypeText":/embedded/eazflow/grails-app/domain/TypeText.html, "TypeInteger":/embedded/eazflow/grails-app/domain/TypeInteger.html, "TypeSysuser":/embedded/eazflow/grails-app/domain/TypeSysuser.html, "TypeFormula":/embedded/eazflow/grails-app/domain/TypeFormula.html, ... - classes for definition of composite-member fields of simple type, all type-specific functionality is handled here

** "TypeComposite":/embedded/eazflow/grails-app/domain/TypeComposite.html - defines a composite-member of another composite type (nested structure)

h4. Process-instance classes

* "RunProcess":/embedded/eazflow/grails-app/domain/RunProcess.html - main process-instance entity class

* "RunActivity":/embedded/eazflow/grails-app/domain/RunActivity.html, "RunAStart":/embedded/eazflow/grails-app/domain/RunAStart.html, "RunAUserAction":/embedded/eazflow/grails-app/domain/RunAUserAction.html, "RunAFinish":/embedded/eazflow/grails-app/domain/RunAFinish.html - classes representing instances of activities, corresponding to DefA... classes

* "RunTransition":/embedded/eazflow/grails-app/domain/RunTransition.html - represents a transition made between activities (RunA... instances) according to a DefTransition

h4. Variable-instance classes

* "Variable":/embedded/eazflow/src/groovy/Variable.html - acts as an interface for accessing all data-fields

* "ValueStorage":/embedded/eazflow/grails-app/domain/ValueStorage.html  - stores values of variables

h4. Authentication & authorization (users, roles, access rights)

* "User":/embedded/eazflow/grails-app/domain/User.html - represents a user which can log-in to the system; a user may have roles (!RoleGlobal) assigned

* "RoleGlobal":/embedded/eazflow/grails-app/domain/RoleGlobal.html  - global roles are assigned to users in the system globally (e.g. _system.administrator_, _company.director_), typically by the administrator

* "RoleInstance":/embedded/eazflow/grails-app/domain/RoleInstance.html - instance roles are assigned per process-instance (e.g. _process.author_, _process.supervisor_), typically automatically by the system based on some process variable values

* "ProcessRoleUser":/embedded/eazflow/grails-app/domain/ProcessRoleUser.html - a materialized relation which assigns (for a particular process) an instance role directly to a user (e.g. for some process instance, user _u1_ has the instance role _process.author_)

* "ProcessRoleGlobal":/embedded/eazflow/grails-app/domain/ProcessRoleGlobal.html - a materialized relation which assigns (for a particular process) an instance role to a global role (e.g. all users having the global role _company.director_ have for some process the instance role _process.supervisor_)

* "AccessRightDefProcess":/embedded/eazflow/grails-app/domain/AccessRight.html - access to process-definitions (NONE/EXECUTE)- who can start which processes

* "AccessRightProcess":/embedded/eazflow/grails-app/domain/AccessRightProcess.html - access to process-instances (NONE/READONLY/WRITABLE)

* "AccessRightActivity":/embedded/eazflow/grails-app/domain/AccessRightActivity.html - access to process per activity (NONE/READONLY/WRITABLE/DELETE)

* "AccessRightTransition":/embedded/eazflow/grails-app/domain/AccessRightActivity.html - access to transitions (NONE/EXECUTE)

* "AccessRightVariable":/embedded/eazflow/grails-app/domain/AccessRightVariable.html - access to process variables (NONE/READONLY/WRITABLE/MANDATORY)

 Access in each category is defined by a list of rules consisting of weight, patterns for matching role-code, process-code, activity-code, transition-code, variable-code (the set of codes depends on the category) and the access right (operation allowed). For a particular test, the rule matching all code-patterns and having the greatest weight defines the access right granted.

* "RenderConfigVariable":/embedded/eazflow/grails-app/domain/RenderConfigVariable.html - in a way similar to the access-right definitions, rendering of process-variables is configured by rules of code-patterns; each rule defines whether the corresponding variable is rendered in the _main_ section (or in the details section only) and whether composite type containing the variable is rendered folded or unfolded

h3. Services

* "AuthenticationService":/embedded/eazflow/grails-app/services/AuthenticationService.html - authenticates a user by username and password

* "AuthorizationService":/embedded/eazflow/grails-app/services/AuthorizationService.html - access rights-related functionality

* "ProcessService":/embedded/eazflow/grails-app/services/ProcessService.html - process creation/deletion, activity creation/startup/finish, etc.

* "ValidationService":/embedded/eazflow/grails-app/services/ValidationService.html - validation of process-variables and other validation rules

* "RunQueueService":/embedded/eazflow/grails-app/services/RunQueueService.html - processing of queued transitions

h3. Controllers

* "WorklistController":/embedded/eazflow/grails-app/controllers/WorklistController.html -  all main process-related functionality (list all, list TODO, search, view, edit, etc.)

* "UserController":/embedded/eazflow/grails-app/controllers/UserController.html - user login/logout, welcome screen, user preferences setup

h3. Rendering of variables

The most important part of a process display is the pane with process-variables. The rendering of the variables (i.e. their labels, values, edit-boxes etc.) is performed in the _show_ action of _WorklistController_. Actually, all variables of a process are contained within one structure (tree) defined by TypeProcessDef assigned to the process and all variables are rendered as part of rendering this process-variable-structure. 

Rendering of variables is handled by <eazf:renderNode> and related tags (of the "EazflowTaglib tag library":/embedded/eazflow/grails-app/taglib/EazflowTagLib.html) with the help of templates named _views/Type/_Type....gsp_. 

h4. Variable and rendering logic

Basically, for a _<some_typename>_ type, there is a _Type<some_typename>_ class inheriting from _TypeMember_, which defines the special functionality of the type (type conversion for storage, validation, saving from the submitted form, etc.). Furthermore, there are _views/Type/_Type<some_typename>.gsp_, _views/Type/_Type<some_typename>Label.gsp_ and _views/Type/_Type<some_typename>Body.gsp_ templates, which define the rendering. When a particular template doesn't exist, a template for the superclass is used, so in most cases only the _views/Type/_Type<some_typename>Body.gsp_ template (if any at all) has to be overridden when implementing a new variable type.

Templates present in the main grails-app views directory take precedence over plugin templates, so rendering of plugin-defined types can also be easily customized.

Look into _TypeInteger_ (_grails-app/domain/TypeInteger.groovy_, _views/Type/_TypeIntegerBody.gsp_) and _TypeSysuser_ (_grails-app/domain/TypeSysuser.groovy_, _views/Type/_TypeSysuserBody.gsp_) for examples of how new types should be defined.