Workflow Form Integration
Add workflow to a new or existing form
Step1: add workflow properties to the form (optional)
Step 2: add workflow completion (required)
See also: Ebase Security
Important note: it is a prerequisite of Ebase Workflow that all users of the workflow system are authenticated i.e. they have signed on. The only exception to this rule is that a workflow job can be created by a non-authenticated user and the first task of such a job can be executed by non-authenticated user.
Workflow FPL commands
Interaction between a workflow’ed form and the workflow system is mostly achieved using the FPL workflow script command, which has the possible syntaxes shown below.
Process commands
workflow open job PROCESS_NAME [jobowner OWNER] [process_attr1=value1, process_attr2=value2] [reason REASON]
workflow start job PROCES_NAME FIRST_TASK_NAME [COMPLETION_STATE] [jobowner OWNER] [reason REASON]
workflow activate process PROCESS_NAME [reason REASON]
workflow quiesce process PROCESS_NAME [reason REASON]
workflow reinstate process PROCESS_NAME [reason REASON]
Job level commands
workflow cancel job JOB_ID [reason REASON]
workflow set outparam FIELD = expression [reason REASON]
Task level commands
workflow assign task TASK_ID [USER_ID] [onlyIfUnassigned] [reason REASON]
workflow cancel task TASK_ID [reason REASON]
workflow complete [COMPLETION_STATE] [reason REASON]
workflow forceassign task TASK_ID USER_ID [reason REASON]
workflow open task TASK_ID [reason REASON]
workflow pause task TASK_ID [reason REASON]
workflow reassign task TASK_ID USER_ID [reason REASON]
workflow reexecute task TASK_ID [reason REASON]
workflow reopen task TASK_ID
workflow set task TASK_ID priority = expression [reason REASON]
workflow unassign task TASK_ID [reason REASON]
workflow unpause task TASK_ID [reason REASON]
The workflow command requires that the Ebase_Workflow_Client licence feature is installed (this can be checked in the Ebase Designer using Help -> Licence). If this feature is not installed, the command will return with status NOT_EXECUTED. If a logical error occurs during execution of the command, it will return with status consisting of “Error: “ plus a detailed error message. This can be displayed to the end user if required. E.g.
workflow complete;
if [ $COMMAND_STATUS != ‘OK’ ]
if [ $COMMAND_STATUS = ‘NOT EXECUTED’ ]
……
else
message E, $COMMAND_STATUS;
endif
endif
Note: a reason message is optionally supplied for all workflow FPL commands. This will be recorded in the audit log against the execution of this command.
Process level commands
workflow open job PROCESS_NAME [jobowner OWNER] [process_attr1=value1, process_attr2=value2] [reason REASON]
where PROCESS_NAME, OWNER, REASON, value1, value2 etc can be either form fields containing the appropriate value or absolute values (quoted for character strings, unquoted for numerics).
Used to open a new job for a workflow process. The job id of the created job is available in system variable $WF_JOB_ID. This command would be typically be issued by a user application, for example, a loan application form. Process attribute values can be passed into the new job. e.g.
workflow open job ‘CUSTOMER_COMPLAINT’ COMPLAINT_ID=REF_NO;
where:
CUSTOMER_COMPLAINT is the name of the workflow process,
COMPLAINT_ID is the name of a process attribute,
and REF_NO is the form variable whose value is to be assigned to process attribute COMPLAINT_ID
set PROCNAME = ‘CUSTOMER_COMPLAINT’;
set OPENJOB_REASON = ‘Create a new customer complaint’
set OWNER = ‘Margaret’
workflow open job PROCNAME jobowner OWNER reason OPENJOB_REASON;
workflow start job PROCESS_NAME FIRST_TASK_NAME [COMPLETION_STATE] [jobowner OWNER] [reason REASON]
where PROCESS_NAME, FIRST_TASK_NAME, OWNER, REASON can be either form fields containing the appropriate value or a quoted string.
Opens a new job (similar to open job) but also opens and completes the first task, passing any mapped OUT parameters from the form into the new job . The job id of the created job is available in system variable $WF_JOB_ID. This command is useful when it is necessary to include the opening form as the first task in the process e.g. when we need to assign a subsequent task to the person who submitted an initial request, or there is a need to branch back to the initial task within the process logic. When start job is used, the first task must have an assignment of either Public or Job Opener.
workflow start job 'HOUSING_BENEFIT' 'Application';
workflow start job 'HOUSING_BENEFIT' 'Application' 'COMPLETED' jobowner HOUSING_SUPERVISOR reason ‘New application’;
workflow activate process PROCESS_NAME [reason REASON]
where PROCESS_NAME and REASON can be form fields containing the appropriate value or a quoted string.
Changes the state of the named process to active. This will typically be issued from a workflow administration application by someone with authorization to activate a quiesced process.
workflow quiesce process PROCESS_NAME [reason REASON]
where PROCESS_NAME and REASON can be form fields containing the appropriate value or a quoted string.
Changes the state of the named process to quiesced. This will typically be issued from a workflow administration application by someone with authorization to Quiesce a process.
workflow reinstate process PROCESS_NAME [reason REASON]
where PROCESS_NAME and REASON can be form fields containing the appropriate value or a quoted string.
Used to un-delete a deleted process. This will typically be issued from a workflow administration application by someone with authorization to re-instate a deleted process.
Job level commands
workflow cancel job JOB_ID [reason REASON]
where JOB_ID and REASON can be form fields containing the appropriate value or a quoted string.
Cancels the given job.This will typically be issued from a workflow administration application by someone with authorization to cancel jobs.
workflow set outparam PARAM_NAME = expression [reason REASON]
where PARAM_NAME and REASON can be form fields containing the appropriate value or a quoted string.
Sets the value of the named output parameter for the current activity. This command is typically issued by an interactive activity application.
Task level commands
workflow open task TASK_ID [reason REASON]
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to open a new task for the first time. This command can only be issued against a workflow task that is in state Waiting and will then transition the task to state Active. It can only be issued from a form logged into by the user to which the task is assigned. The new task is started and all designated IN parameters are passed to it. This command is usually issued by a task list application.
workflow pause task TASK_ID [reason REASON]
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to pause an active task. This will typically be issued from a task list application.
workflow reassign task TASK_ID USER_ID [reason REASON]
Used to explicitly reassign a task which is already in the assigned state. This will typically be issued from a workflow administration application by someone with authorization to reassign task enactments.
workflow reexecute task TASK_ID [reason REASON]
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to re-execute a task in the Failed state. This will typically be issued from a workflow administration application by someone with authorization to reexecute task enactments.
workflow reopen task TASK_ID
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to open a task that has been previously opened by the same user with workflow open task. This command can only be issued against a workflow task that is in state Active. The task is started and all designated IN parameters are passed to it. This command is usually issued by a task list application to re-fetch task execution descriptor information.
workflow set task TASK_ID priority = expression [reason REASON]
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to set the priority of a task to the given value. This could be done from within a system activity, for example, to escalate a task, or from a task list or administration application to manually change a task’s priority.
workflow unassign task TASK_ID [reason REASON]
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to clear an assignment on an active task. This would typically be issued from the workflow administration application when a resource is no longer available to execute the task.
workflow unpause task TASK_ID [reason REASON]
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to release a paused task back to the active state. This would typically be issued from a task list application.
workflow assign task TASK_ID [USER_ID] [onlyIfUnassigned] [reason REASON]
where TASK_ID, USER_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to assign a group task to an individual. Method isAssignableToActor() in the assignment handler is called to check whether the assignment is allowed. If the assignment is allowed, the task is then transitioned to state Waiting, when it can be opened using workflow open task. If onlyIfUnassigned is included in the command, this will return an error if the task has already been assigned once. This command is usually issued by a task list application.
workflow forceassign task TASK_ID USER_ID [reason REASON]
where TASK_ID, USER_ID and REASON can be form fields containing the appropriate value or a quoted string.
Unconditionally assigns a task to the named user. This command differs from workflow assign in that the assignment handler is not invoked to check whether the assignment is allowed. This command will transition the task to state Waiting when it can be opened using workflow open task.
workflow cancel task TASK_ID [reason REASON]
where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.
Used to cancel a task. This command can currently only be issued against a workflow task that is in state Active. Please note that a task can only be cancelled if it has been defined as cancellable in the workflow process editor. This command is usually issued by a task list application.
workflow complete [COMPLETION_STATE] [reason REASON]
where COMPLETION_STATE and REASON can be form fields containing the appropriate value or a quoted string. Used to signal completion from a workflow’ed form and update the workflow system with any OUT parameters for the form. It can only be issued from a form logged into by the user to which the task is assigned.
Operands of the workflow command are as follows:
PROCESS_NAME – the name of the process used to create a new job
TASK_NAME – the name of a the first task in a process (used in the workflow start job command)
OWNER – the resource (usually a userid) to be assigned as owner of a new job
TASK_ID – the unique workflow task id (provided as $WF_TASK_ID to workflow’ed forms or in the table provided to a tasklist application)
JOB_ID - unique workflow job id (provided in the table provided to the process administration application
REASON – optional text to be added to the audit trail record associated with the command
COMPLETION_STATE – the completion state for a workflow task
Workflow system variables
$WF_TASK_ID contains the unique task id that identifies a workflow’ed task to the workflow system. This system variable is set automatically when a task is started using either the workflow open or workflow reopen commands.
$WF_JOB_ID contains the unique job id, and is set when a new job is created using either the workflow open job or workflow start job commands.
Workflow How To
Start a new job from a form
This can be achieved using either a workflow open job of a workflow start job FPL command:
workflow open job PROCESS_NAME;
Opens a new job for workflow process PROCESS_NAME. The job id of the created job is available in system variable $WF_JOB_ID.
workflow start job PROCESS_NAME TASK_NAME [COMPLETION_STATE];
This is a variation on workflow open job that starts a job and completes the first task within the job. This command can only be used with processes where the first task is an interactive task that has an assignment of Public or Job Opener. TASK_NAME is the name of the first task in the process. COMPLETION_STATE is optional (see signalling completion).
For the full syntax on these commands, please see the description above.
Add workflow to a new or existing form
Step1: add workflow properties to the form (optional)
This step is recommended as it enables the workflow activity editor to obtain a form’s workflow properties directly from the form. Alternatively, these properties can be entered directly into the workflow activity editor, however this approach is more prone to error. To edit the workflow properties for a form, select form properties then the Workflow tag from the properties dialog.
Workflow in parameters are form fields that are passed into the form when it is started by a tasklist application.
Workflow out parameters are form fields that are passed back to the workflow system when the form signals completion of the task.
Completion states contains a list of possible completions for this form. If absent, the system will use the default completion state COMPLETED.
Please note that the Workflow aware form checkbox is currently not used.
Step 2: add workflow completion (required)
When the task has been completed, the form must signal completion to the workflow system using the FPL script command:
workflow complete [COMPLETION_STATE];
COMPLETION_STATE is required if the form has more than one possible
completion state.
If the form is not workflowed i.e. it was not started from a tasklist application, or the system does not have a licence for the Ebase_Workflow_Client module, this command will end with status NOT_EXECUTED.
This command signals completion of the interactive task designated by control field $WF_TASK_ID to the workflow system. It also updates the workflow system with all the forms workflow out parameters. The workflow system will then continue execution of the workflow job of which this task forms a part.
Completion states are intended to assist in the design of logical and clear business processes. They are not required and, if not used, will default to state COMPLETED. If specified, the completion state of each task is added to the audit log for the job and additionally can be used to control the execution path for subsequent tasks in the workflow process.
Sample tasklist application
An Ebase form WF_TASKLIST is provided in project WORKFLOW_SAMPLES. This can be used to:
- Display a list of all tasks for a user
- From the list, allow the user to:
- assign a group task to the user
- open a task already assigned to the user
- reopen a task previously opened
- cancel an active task
This form is provided as a sample and it is anticipated that organizations will create their own tasklist using this as a model. The sample obtains a tasklist table from the workflow system using the WF_TASKLIST custom resource which is implemented by Java class com.ebasetech.ufs.workflow.form.customresources.WorkflowTaskList. This custom resource will return a table of all tasks explicitly assigned to the user plus all tasks for which the user is a candidate in response to a fetchtable command e.g. the user is a member of the group/team/role to which the task is assigned. The following is a list of fields returned by the custom resource:
- TASK_ID the unique id of the task. This id must be used in all subsequent calls to the workflow system relating to the task.
- TASK_DESCRIPTION is the task description as entered in the process designer with any variable substitutions performed
- STATE is the current state of the task
- PROCESS_NAME is the name of the process of which this task forms a part
- PROCESS_VERSION is the version of the process being executed
- JOB_SEQUENCE the unique number of the job being executed
- TASK_NAME the name of the task
- TASK_PRIORITY the priority of the task
- CREATION_DATE the date the task was created
- MODIFICATION_DATE the date of the last action relating to this task
- ACTOR the name of the user to whom this task is currently assigned
- POOLED_ACTORS the name(s) of teams, groups, roles, candidate actors etc which will be used to select a single ACTOR.
From the displayed table, the user can request actions against individual tasks. The possible actions are constrained by the status of a task as follows:
- UNASSIGNED – only possible action is assign
- WAITING - only possible action is open
- ACTIVE – possible actions are reopen and cancel
Note that it is only possible to cancel tasks designated as cancellable in the process editor. This information is not currently available to a tasklist application