(Quick Reference)

3 User's Guide - Reference Documentation

Authors: Stephan Albers, July Antonicheva

Version: 1.7-SNAPSHOT

3 User's Guide

3.1 Introduction

Grailsflow allows you to manage processes, their definitions and activities related to a process. This user's guide describes some of the basic features of Grailsflow and how you can use them.

There are two major stages in Grailsflow:

  • Process Definition
  • Execute Process

Process Definition

In Process Definition stage, you can create a process, add process variables, nodes, transition, and actions. The functionality of these steps will be explained in later sections. Once you create a process, you can execute it any number of times. This in turn, allows reusing of process and reduces the process creation time.

Execute Process

In the Execute Process stage, you can make use of the processes created in the Process Definition stage. Here it is possible to start a process, view the currently executing processes, view worklist, and execute the worklist item.

3.2 Analyse Response Time

In this section, you can analyze response time based on process types and sort nodes by fields. It also allows you to analyze the response time of the executed processes. GrailsFlow searches all process nodes for a process type, determines the time used for each node, checks for min., max., and average time and then displays them on screen. The process type nodes can be sorted by minimum, maximum, average execution time, interactive, and non-interactive node.

Click on the Analyse Response Time menu from the left corner of the screen to view the Analyse Response Time screen.

To find the response time of a particular process node, follow the steps below:

  • Select Process Type from the drop down menu.
  • Select the criteria by which the process nodes have to be sorted, from the Sort Node By field.
  • Click the "Search" button to display response time of the process

With respect to process nodes - these are sorted with respect to the average time.

Protocolling Nodes Execution section allows to analyze execution time of protocol groups (consisting of one or several process nodes) for processes of the same type. See Protocoling Nodes Execution for ProtocolingTest Process:

To find the response time of a particular process node, follow the steps below:

  • Select Process Type from the drop down menu.
  • Select the criteria by which the process nodes has to be sorted, from Sort Node By field.
  • Click "Search" button to display response time of the process, with respect to process nodes. Here, the process

nodes are sorted with respect to the average time.

3.3 View Scheduler Details

The View Scheduler Details menu is used to schedule the execution of a process at a later date/time.

For example, the HR of a company has to track the leave taken by an employee, very frequently. The scheduler option will help to create a process to track the leave and schedule process execution frequently, at specific intervals.

Click the View Scheduler details menu from the left corner of the screen to open the Scheduler Details screen.

The Scheduler Details screen displays the currently running jobs and the scheduled jobs. 'Scheduler details' is used to monitor the Quartz jobs and the configuration of the Quartz library. It shows the Quartz configuration parameters and allows you to view all currently running jobs, to pause, delete and edit jobs. It displays the scheduler information with jobs and triggers.

Edit jobs allows you to modify the repeat interval, which is useful e.g. to tune the NodeActivatorJob.

The Pause Scheduler button is used to pause all scheduled jobs listed under the Scheduled Jobs option.

Running Jobs displays the job names which are running currently and also displays job names triggered at a specific time interval.

The Schedule Process button is used to schedule the process. To schedule a process, follow the steps below:

  • Click Shedule Process button. The Schedule Process screen appears.

  • Select the Process Type from the drop down.
  • Enter values for Process Variables.
  • Select the repeating sequence:
    • Once
    • Minutely
    • Daily
    • Weekly
    • Specify custom value – To specify the customized repeating value other than the above mentioned sequences.
  • Enter the date in Day field.
  • Enter time in Time field
  • Click Add Job button.

The job is added under the Scheduled Jobs option, in Scheduler Details screen.

Specify Custom Value

The Specify Custom Value is used to enter the repeating sequences other than the available sequences.

Select Specify Custom Value from Repeating field.

3.4 Show Documents

The Show Documents menu displays directories which contain files (which has Document type variable) uploaded for the process.

Documents are a special type of process variables that allows storing arbitrary files in a process. You declare a process variable in your process class through the process designer with the type Documents. When you enter variables, GrailsFlow presents a “Browser†button to upload documents. The file is uploaded and stored in a directory.

A directory is created for each day. The file name is cleaned up and extended by the process id and a counter. The link to the file is stored in the DB.

If the variable can be changed in a later step, the file can be downloaded and a new version can be uploaded. The new version is stored the same way, so GrailsFlow provides a full version history for documents.

'Show Documents' lists the documents that are attached to processes. Documents are stored as simple files in the file system.

3.5 Use Processes

3.5.1 Start Process

The Start Process menu enables you to execute the process.

To start a process, click Start option from Operation column on Show Types page:

The Node Details screen appears, if the start node is interactive (i.e., Wait type).

Enter the variable value and click Ok button. If the next node is non-interactive (i.e., nodes other than Wait type) the Process Details screen appears, else the Node Details screen appears.

If the start node is non-interactive (i.e., other than Wait type) the Process Details screen appears.

The 'Show Graphical Process' button provides a graphical representation of the process.

A process can be scheduled to start execution at a later point in time. Refer View Scheduler Details for more details.

3.5.2 Show Worklist

The Worklist screen displays the nodes that are waiting for user input. These nodes are visible to user whose User ID or Role or group is assigned to the respective nodes.

To open Worklist screen click Show Worklist menu from left side of the screen. The Worklist screen appears.

The screen displays all the nodes which are of Wait type. The Filter by variable drop down is used to filter the nodes depending on the following criteria:

  • Product ID
  • Name
  • RequesterName

Once any of these criteria are selected, the value drop down displays the values of the selected criteria respective to the process nodes.

For example, in the above figure the Node ID "CheckValues" has Product ID as "101570" and Product ID is selected as a filter variable, the value drop down displays "101507" in the drop down. Click the Filter button - the screen will display only the filtered node.

Important! - The filtering can slow down your worklist loading, if you have a lot of processes in the list. If there are more then 500 processes in the worklist we get variables by splitting the parameter list into smaller chunks and then combining the results. But such functionality requires time for execution and can slow down performance. So, by default, the filtering works well if there are no more entries than then maxRestrictedProcesses size. The behaviour can be changed by reconfiguring some available Spring beans or even to disable filtering functionality at all.

isWorklistFilterAvailable - this bean defines if we need the filtering functionality, the default value is configured to TRUE maxRestrictedProcesses - this bean contains the Integer value for common quantity of restricted processes used in SQL 'in' clause (default value is '2000' entries)

Imagine you are a manager and you want to review all requests from your employees.

In the demo workflow, the admin user acts as an employee, manager and - HR person at the same time, so that you don't have to login and logout for this demo.

  • Go to the 'Show Worklist' menu item to view the request for holidays from an employee.
  • Click on the request to view the form that contains the employee name, request message, area for your resolution

notes and two buttons 'Approve' and 'Reject'.

Then, as a manager, you have to approve this request. Click the Approve button to approve the holiday request or click Reject to reject it. A note can be included (in the resolution field), if you reject the request.

A letter about the successful holiday approval would be sent to the employee.

As a HR-person, you need to record how many holidays each employee has taken so far and if it is payable or not. Go to the 'Show Worklist' menu item. Here you have a list of approved holidays that you should take note of.

HR sees that the manager has approved the holidays Click on the request link and to view form with the employee name, manager's decision, manager notes and an input area for a log message.

You could enter a log, something like "approved; no critical projects at that time"

Then click the Save Log Info button to save the log message and complete the workflow.

3.5.3 Show Embedded Worklist

The functionality of the Show Embedded Worklist is the same as Show Worklist with the only difference being that the Worklist displays in a pop-up window, without any headers.

The Embedded worklist helps you to view the nodes simultaneously, while working on other screen

Refer Show Worklist section for more details.

3.5.4 Forward Node

It is possible to forward Node to another assignee. The forwarding is available on automatically generated manual forms or can be added to custom form using Grailsflow template, e.g.
<gf:customizingTemplate template="/manualForms/eventForwarding"
        model="[currentAssignees: nodeDetails.assignees]"/>

The node can be forwarded to another Users, Roles or Groups. To define assignment correctly, the special prefixes are used. For Users it is 'USER_', for Roles - 'ROLE_', for Group - 'GROUP_'

The assignment for Nodes can be done in process definition, e.g.

ManagerApproveHolidaysWait(dueDate: 432300000, editorType: ConstantUtils.EDITOR_MANUAL) {
        variable( message: ConstantUtils.READ_ONLY, requesterName: ConstantUtils.READ_ONLY, holidaysEnd: ConstantUtils.READ_ONLY, resolution: ConstantUtils.WRITE_READ, holidaysStart: ConstantUtils.READ_ONLY)
        assignees( roles: [ "MANAGER", "ADMIN" ] )
        action {
            Log(logMessage: 'Manager makes decision...')
        }
        on("approve").to([ "ApprovedOperation" ])
        on("reject").to([ "RejectNotification" ])
      }

The forwarding is available through Grailsflow service and can be called directly using the following method

processManagerService.forwardProcessNode(node, newAssignees, loggedUser)

where the method parameters are

  1. node - is a ProcessNode instance to be forwarded
  2. newAssignees - is a collection Collection<String> forwardedTo of new assignees with special prefixes (for Users it is 'USER_', for Roles - 'ROLE_', for Group - 'GROUP_')
  3. loggedUser - is a name of user who forwards node

The method doesn't check node for available assignees, so pay attention that if you use method from your own code, you should check firstly if the node is available for loggedUser.

3.5.5 List Processes

List Processes displays all the Processes with status, create date, modified date and finished date.

You can click on the Process (ID) to view details about the process.

To kill a currently running process click on the link Kill.

To view the graphical representation of a Process click on the link Graphic.

The Graphical representation shows all nodes of the selected process (visited nodes, untouched nodes, interactive nodes which are currently waiting for user actions, etc.) with their statuses (color coded).

3.5.6 Kill Process

A process can be killed - this means that all process activities should be stopped and all active nodes and process should be set to status 'KILLED'.

When the process starts the killing procedure from UI, first of all we interrupt the process invocation thread, then update process status (and all active nodes) to 'KILLING'.

In the next step - we check actions thread - the thread where we execute actions code. If there is no alive actions thread, then we update process status (and its active nodes) to "KILLED". If we have an actions thread, then try to interrupt it. This thread will check the interrupted flag for process. In case of interrupted flag, we set the process status (and its active nodes) to "KILLED".

During process execution we can have exceptions in the node execution. In case of exceptions, the process can be killed too.

3.5.7 Remove Process

A process can be removed - this operation is available only for finished processes, e.g. "COMPLETED" and "KILLED". The process will be deleted with all nodes, variables, graphical positions and log file.

The operation can be done for the separate process or for the list of filtered processes.

There is a property maxLoadedProcesses in configuration. This property gives possibility to configure the max number of processes to be loaded from DB during process removing (the quantity for one iteration). By default, it is configured to 200 items ( Integer value).

// default configuration for quantity of loaded processes in removing service
 maxLoadedProcesses(java.lang.Integer, "200")

3.6 Process Definition

3.6.1 Actions Of Node

Actions define the operations to be performed in each node, internally. Basically action defines the operation of a node. You can develop code for the operation of each node using plain Groovy code.

Create Action

For example, we need to send a Notification if Holiday Request is rejected.

  1. To open the Process Action Editor screen, click the following buttons:

Administration -> Edit Process Types -> Edit button for Request Holiday Process -> Edit button for RejectNotification node -> Edit Node Actions button.

The Process Action Editor screen will open:

To create a SendNotificationMail action you can either write the plain code (using Variables and Actions from the drop-down list as a hint) or you can use 'plus' button to add Variables and Actions automatically.

Select SendNotificationMail from the drop-down list and click 'plus' button.

Action Call Parameters editor will open in a new window. Fill in the necessary fields and click Apply button.

Manually adjust the code and then click the Apply button.

if (requesterMail) {
SendMail(mailFrom:managerMail,mailTo: requesterMail,subject:'Rejected Notification',message: 'Your request was rejected.')
}
return "finish"

According to the node type you should pay attention to the actions. If the node is manual (type is 'Wait') then you don't need to trigger any transition and specify 'return' statement. The body of 'Wait' node is executed after transition definition (defined manually by the user). If the 'return' statement is specified in manual node it is ignored by process execution engine.

If node type is automatic (one from 'Activity', 'Fork', 'AndJoin', 'OrJoin') then you need to specify 'return' statement that triggers the next transition.

Return statement has the following syntax:

If there is no 'return' statement for automatic node then the next node(nodes) cannot be activated.

From the version of Grailsflow-1.0.x when 'action' closure contains plain Groovy code then return statement can hold functions, expressions, etc. The evaluated value is transfered to String type and used for transition definition.

4. Click "Apply" button to save action of the node.

The Up and Down navigation icons are used to move statements up and down.

The 'Delete' icon is used to delete the statement.

The Edit Node Action button is used both for create and edit actions.

Once you create process, add process variables, create process nodes, add transitions, and create actions for nodes, click Save Process Type button to save the process. The process definition is saved on the server to file <processID>Process.groovy.

You can view the process definition file saved on server, using Show Source Code button.

You can reload definition that you currently edit from file <processID>Process.groovy by pressing Reload Process from File.

To view the process in pictorial or graphical representation, click Show Graphical Process button.

Export as HTML button will create HTML that describes the process. It's something like a report; you can view this HTML to get the common information about the process. Click Export as HTML button. A File Download window appears. Click “Open” or “Save”. A zipped folder appears. Open the zipped folder and open the html file.

3.6.2 Add Process Variables

A process requires variables to manipulate the process data. To add variables to a process follow the steps below:
  • Click Add button, which is under Process Variable or click the corresponding Edit option under Operations

column, in Edit Process Type screen. The Process Variables screen appears.

  • Enter variable name in Name field - field is mandatory and name should be a unique name
  • Check the Is Process Identifier check box - used to make the variable as an identifier of the process - e.g. if

there is a process "My Process" has a variable "name" marked as process identifier. So, if you start that process with name="John" - while that process is running you cannot start another "MyProcess" with name="John". But you can start "MyProcess" with any other name.

  • Check Required check box - defines the variable as mandatory. The application cannot perform the operation without

the variable value.

  • Select the variable type from the Type drop down - by default, it displays String type.

Currently, Grailsflow supports the following variable types:

Boolean Double String Long Integer Date Document Link Object

  • Enter default variable value in Value field - it is the default value for the variable. The value will be set by

default when the process gets started.

  • Select the type of variable view from the View drop down - view specifies the way the variable will be displayed on the UIs of the interactive nodes ('Wait' nodes). Refer Varible View section for more details.
  • Click the Apply button to save the process variable.

Similarly, multiple variables can be created for a process.

Variable View

Values for select box are selected from the database.

  • Property to display property of the domain is used as label for the select box option.
  • Restriction is 'where' condition (without 'where' word) that will be used for selecting list of objects from the

database

The Variable View type consists of the following views:

  • Simple View
    • Style Class - Defines CSS class for the input.
    • Size is the size of the input. Default size is 20.

  • Select Box View – It displays values in a drop down. It consists of one value per line.

  • Text Area View - Displays variable value in text area. Its size is defined with Rows and Columns property values.

Default rows count is 10, for column default value is 50.

  • Date View
    • Date Format – Defines the format of dates.
    • Style Class - Defines CSS class for the input.
    • Size - Size of the date input. Default size is 20.

  • Check Box View - Displays checkbox for the Boolean values.

  • Link View - Link view displays {{input}}s for editing the Link values.

  • Document View - Document view allows to upload files as Document values.

  • List Objects View - List Object view displays select box to choose value for domain object variable.

Values for select box are selected form database.

    • Property to display property of the domain is used as label for the select box option.
    • Restriction is 'where' condition (without 'where' word) that will be used for selecting list of objects

from the database.

  • External Search Object View - Uses pop-up window for selecting value for domain object variable.
    • Property to display is the name of the domain property that will be displayed.
    • Search URL is the URL for opening pop-up search window.
    • Additional Fields are comma-separated property names, whoes value will be additionally shown.

To edit or delete process variable, click the corresponding Edit or Delete option of variables, under Operations column, in Process Editor screen.

3.6.3 Create Process

To create a process, follow the steps below:
  • Click Add button. The Process Editor window appears.

  • Enter Process ID.

Enter a unique Process ID. Process ID is mandatory. The screen displays error message if you do not enter Process ID.

  • Enter process description in Description field.

The description is for current browser language (i.e. request language). Descriptions for other languages can be added/modified using Manage Translations option. Refer Manage Translation section for more details.

  • Click Create button. The Process Editor screen displays the following options:
    • define Valid from/Valid to values to specify the valid range for process script definition,
    • add assignees,
    • add variables,
    • add nodes.

3.6.4 Edit Process

To edit a process, click Edit option under Operations column, in Edit Process Types screen.

3.6.5 Delete Process

To delete a process, click Delete option under Operations column, in Edit Process Types screen.

3.6.6 Fix Buggy Process Code

In case any process is invalid ( has buggy script ), its description field contains the following notification:

To fix process script code, follow the steps below:

  • Select Edit option from Operation column to open Process Script page.
  • Notification message points to lines and columns containing errors. Fix errors right in the textarea.
  • Before saving the fixed code, check whether it can be compiled by clicking the Check button.
  • If the message The code of process script can be compiled appears , click Save button - and you will be redirected

to Edit Process Types page. Now the process is valid and available for editing.

3.6.7 Manage Translation

The feature Manage Translation is used for translations of process, process variables, and process nodes description in different languages. Currently, descriptions are possible in two languages, i.e., English and German. The idea behind it is to localize the process definition to any desired language.

The Manage Translation option is available in the Process Editor, Process Variables, and Process Node screens.

  • Click the Manage Translation option, to open the Process Translations screen

  • Select the language from the drop down.
  • Enter data in text area.
  • Click Add option.
  • Click Apply button.

3.6.8 Process Nodes

Nodes are steps in a process. They define the steps to be performed, while executing a process. For example: If an employee has to request leave, following are the steps to be performed:
  • Employee sends leave request to the manager
  • Manager approves or rejects
  • HR tracks the leave

Therefore, the nodes of a Leave request process is as follows:

  • Send Leave request
  • Manager Approval
  • Manager Rejection
  • HR Notification.

Node can have different types:

  • Wait - Nodes wait for input, so they are visible in the worklist of the user assigned to that node. You can define

actions and forms for this node type.

  • Activity - Nodes execute actions without waiting for user input. You can define actions for this node type.
  • Fork - From this node you can execute several new nodes simultaneously (several nodes will be activated not only one

as for 'Activity' node type).

  • AndJoin - Node should wait for all its incoming transitions (e.g. until all managers do not approve, the payment is

not done).

  • OrJoin - Node should wait for at least one incoming transition and then can be activated/executed (e.g. if the

'letter about payment' was rejected or approved by manager -then go to the 'Final' node and finish the process flow).

Add Nodes

  • Click the Edit Process Types menu. Select its corresponding Edit option and click the Add button under Process

Nodes to open the Process Nodes screen.

  • Enter Node ID (mandatory), select Type from the drop down list, fill in Due Date and Expected Duration fields

and enter Protocol Group.

  • Click the Apply button to be redirected to the Process Editor page where there are links.

Add Assignee(s)

You can assign the nodes to any user, role or group and define the visibility of variables - e.g. In the Request Leave process, a manager can only approve or reject leave. The Assignees column allows you to assign the nodes Manager Approval and Manager Rejection to manager role or user.

Use the following steps to add assignees:

  • Select Users, Roles or Groups using radio buttons.
  • Click the plus icon/button to select Process Assignees and a window opens displaying Users, Roles or Groups.

  • Select User, Role or Group and click Close button.
  • Click Add button. The selected user or role is added to Assignees.

You can click Delete option to delete an assignee.

Once you add assignee the next step is to define visibility of process variables.

Visibility of Variables

Visibility of variables is used to define whether the process variables are invisible, read only, or write and read variables. Available visibilities are listed below:

INVISIBLE READ_ONLY WRITE_READ REQUIRED

Select the visibilities for each of the process variables in the Visibility column of the *Visibility for Variables : Variable List*.

The "Preview Generated Form" button is used to preview the form generated for the nodes of “Wait” type. Refer Manual Form section for more details.

Manual Form

The Manual Form has the following options:

  • External URL
  • Use Automatic Form
  • Use Customer Form
  • Use Custom Controller and Form (for development mode only)

External URL

If you do not want to customize the form or use automatically generated form, but use external editor/view/page instead, you can specify the URL for the external page. When you try to open 'Manual Step page' the control is redirected to the specified External URL.

Use Automatic Form

The Use Automatic Form option will automatically generate a form for the node type "Wait".

Use Custom Form

The Use Custom Form option is used to create a customized form for the node type "Wait". The user can write the code in the Manual Form text area and click a button to generate the form. The Preview Generated Form button is used to preview the generated form as shown below:

Now, click "Preview Generated Form" button to display the preview of HolidayRequestForm as shown below:

Use Custom Controller and Form (for development mode only)

The Use Custom Controller and Form option is used to modify or add more features to the user customized form or to create a more complex user customized form. Similar to Use Custom Form, create write code in the Manual Form text area and click the Generate button. To preview the form, click the "Preview Generated Form" button.

Custom Page and Controller Rules

It displays a pop-up with some code rules and information for the user who wants to specify custom controller/page. The page contains a list of variables that are available on the page (variables, transitions etc.).

3.6.9 Transitions

Transition defines the order in which the process nodes have to be executed - e.g. if the manager approves the leave request the approval has to be sent to the employee and to HR. In order to move from Approve Notification node to Approve Finish node, a transition is required. While in transition, it passes some information to the next node.

Add Transition

To add transition to a node, follow the steps below:

  • Click the Edit option in the Operations column of the Edit Process Types screen to open the Process Editor

screen

  • Go to the Process Nodes section, select the node and click the Plus button to open the Process Transitions

screen

  • Enter event in the Event field which is the message to the next transition node
  • Select the next transition node from the list of nodes
  • Click the Apply button to add transition, else click the Back button

  • To delete a transition, select the Delete icon/button.
  • To edit the transition, click on the transition (e.g. - okay). The Process Transition opens. Edit the transition and

click the Apply button.

If the node is a Fork type, the transition is to multiple nodes, as mentioned below:

Here the transition of ApprovedOperation is to HRNotification and ApproveNotification.

To delete transition click Delete button. A message window appears. Click "OK" button to delete the transition.