Workflow Form Integration

Workflow Programming with API language. 2

Process level programming. 3

Job level processing. 6

Task level processing. 7

Workflow system variables 13

Workflow How To. 14

Start a new job from a form. 14

Add workflow to a new or existing form. 14

Step1: add workflow properties to the form (optional) 14

Step 2: add workflow completion (required) 15

Sample tasklist application. 16

Workflow Programming with FPL

Interaction between a form and the workflow system is mostly achieved using the workflow script command, which has the possible syntaxes shown below.

Process/job 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 cancel job JOB_ID [reason REASON]

workflow set outparam FIELD = expression [reason REASON]

workflow post job JOB_ID EVENT_ID [reason REASON]

workflow post process PROCESS_NAME EVENT_ID process_attr1=value1 [, process_attr2=value2] [reason REASON]

Task 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 skip task TASK_ID [reason REASON]

workflow unassign task TASK_ID [reason REASON]

workflow unpause task TASK_ID [reason REASON]

Operands of the workflow command are as follows:

PROCESS_NAME – the name of the process used to create a new job

PROCESS_NAME – the name of the process

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

The workflow command requires that the Ebase_Workflow_Client licence feature is installed (this can be checked in the Server Administration Application). 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

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.

Workflow Programming with API language

When an API based programming language is used, all functionality of the workflow system is available via the workflow API. This is accessed as follows:

var api = system.workflow.api;

In addition to the full API, a number of additional methods are provided on the system.workflow object:

system.workflow.openTaskAndGotoToForm(taskId);

system.workflow.openTaskAndGotoToForm(taskId, reason);

system.workflow.reOpenTaskAndGotoToForm(taskId);

system.workflow.openJob(processName, parameters);

system.workflow.openJob(processName, parameters, owner, reason);

system.workflow.openJobAndCompleteFirstTask(processName, firstTaskId);

system.workflow.openJobAndCompleteFirstTask(processName, firstTaskId, completionState, owner, reason);

system.workflow.completeTask();

system.workflow.completeTask(completionState, reason);

Process/job level programming

Open job

Used to open a new job for a workflow process. Process attribute values can be passed into the new job. The job id of the created job is available in system variable $WF_JOB_ID

FPL:

API based language (Javascript):

Syntax: workflow open job PROCESS_NAME [jobowner OWNER] [process_attr1=value1, process_attrn=valuen] [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).

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

· 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;

var parms = {};

parms.COMPLAINT_ID = fields.REF_NO.value;

var jobId = system.workflow.openJob("CUSTOMER_COMPLAINT", parms);

where:

· CUSTOMER_COMPLAINT is the name of the workflow process

· COMPLAINT_ID is the name of a process attribute

· REF_NO is the form variable whose value is to be assigned to process attribute COMPLAINT_ID

Start job

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.

FPL:

API based language (Javascript):

Syntax: 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.

workflow start job 'HOUSING_BENEFIT' 'Application';

workflow start job 'HOUSING_BENEFIT' 'Application' 'COMPLETED' jobowner HOUSING_SUPERVISOR reason 'New application';

// The stringValue field property should be used to pass the field to a job

var parms = {};

parms.REQUEST_ID = fields.REQUEST_ID.stringValue;

var jobId = system.workflow.openJobAndCompleteFirstTask ("HOUSING_BENEFIT", "Application");

Cancel job

Cancels the given job.This will typically be issued from a workflow administration application by someone with authorization to cancel jobs.

FPL:

API based language (Javascript):

Syntax: workflow cancel job JOB_ID [reason REASON]

where JOB_ID and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.cancelJob(fields.JOB_ID.value, "reason", user);

Set output parameter

Sets the value of the named output parameter for the current activity. This command is typically issued by an interactive activity application.

FPL:

API based language (Javascript):

Syntax: workflow setoutparam PARAM_NAME = expression [reason REASON]

where PARAM_NAME and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.setOuputParameter(fields.JOB_ID.value, "PARM1", "Test", "reason", user);

Post a pause node

Posts the Pause Node associated with the specified EVENT_ID. There are two variants which represent different ways to identify the target job: the first by JOB_ID, the second using one or more process attributes. When using the process attribute variant, the attributes and values must uniquely identify a single active job.

FPL:

API based language (Javascript):

Syntax 1: workflow post job JOB_ID EVENT_ID [reason REASON]

Syntax 2: workflow post process PROCESS_NAME EVENT_ID process_attr1=value1 [, process_attrn=valuen] [reason REASON]

where JOB_ID can be a form field containing the appropriate value or a quoted string.

EVENT_ID is the name of the event id – this cannot be a form field and should not be a quoted string.

When the post process form of the command is used, at least one process attribute must be specified.

$COMMAND_STATUS is set to 'OK' to indicate that the Pause Node has been posted. When unsuccessful, $COMMAND_STATUS contains the failure reason.

Note that when a process attribute of type INTEGER is used, it should first be converted to string format as shown in the example below:

set REQUEST_STR = tostring(REQUEST_ID);

workflow post process PROCESS_NAME POST10 REQUEST_ID=REQUEST_STR;

// post using job id and event id

system.workflow.api.post(fields.JOB_ID.value, fields.EVENT_ID.value, "reason", user);

// post using process attributes

var attrs = {};

attrs.REFNO = fields.REFNO.value;

system.workflow.api.post("HOUSING_BENEFIT", attrs, "EVENT1", "reason", user);

If process attributes are passed, at least one process attribute must be specified.

Task level processing

Open task

This is usually issued by a task list application, and is used to open a new task for the first time. Terminates execution of the current form and starts the Ebase Xi form associated with the task passing in any designated IN parameters. This command can only be issued against a workflow task that is in state Waiting and already assigned to the user – the task is then transitioned to state Active.

FPL:

API based language (Javascript):

Syntax: workflow open task TASK_ID [reason REASON]

where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.

system.workflow.openTaskAndGotoForm(fields.TASK_ID.value);

Re-open task

This is the same as open task except that it is used when a task has been previously opened, but for some reason has not been completed. Can only be issued against a workflow task that is in state Active.

FPL:

API based language (Javascript):

Syntax: workflow reopen task TASK_ID

where TASK_ID can be a form field containing the appropriate value or a quoted string.

system.workflow.reOpenTaskAndGotoForm(fields.TASK_ID.value);

Assign task

Used to assign a group task to an individual. The assignment handler’s isAssignableToActor() method is called to check whether the assignment is allowed. If the assignment is allowed, the task is then transitioned to state Waiting, and can then be opened. This is usually issued by a task list application.

FPL:

API based language (Javascript):

Syntax: 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.

If onlyIfUnassigned is included in the command, this will return an error if the task has already been assigned once.

var user = system.securityManager.userName;

// Allows reassignment

system.workflow.api.assign(fields.TASK_ID.value, fields.USER_ID.value, false, "reason", user);

// Doesn’t allow reassignment

system.workflow.api.assign(fields.TASK_ID.value, fields.USER_ID.value, true, "reason", user);

Reassign task

Used to explicitly reassign a task which is already in the assigned state. The assignment handler’s isAssignableToActor() method is called to check whether the assignment is allowed. This will typically be issued from a workflow administration application by someone with authorization to reassign task enactments.

FPL:

API based language (Javascript):

Syntax: workflow reassign 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.

var user = system.securityManager.userName;

system.workflow.api.assign(fields.TASK_ID.value, fields.NEW_USER_ID.value, false, "reason", user);

Force assign task

Unconditionally assigns a task to the named user. This command differs from normal assignment in that the assignment handler is not invoked to check whether the assignment is allowed, so it is possible to assign the task to any user. This command will transition the task to state Waiting, and it can then be opened.

FPL:

API based language (Javascript):

Syntax: 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.

var user = system.securityManager.userName;

system.workflow.api.forceassign(fields.TASK_ID.value, fields.USER_ID.value, "reason", user);

Unassign task

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.

FPL:

API based language (Javascript):

Syntax: workflow unassign task TASK_ID [reason REASON]

where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.unassign(fields.TASK_ID.value, "reason", user);

Cancel task

Used to cancel a task. Can 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 is usually issued by a task list application.

FPL:

API based language (Javascript):

Syntax: workflow cancel task TASK_ID [reason REASON]

where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.cancel(fields.TASK_ID.value, "reason", user);

Pause task

Used to pause an active interactive task. This will typically be issued from a task list application.

FPL:

API based language (Javascript):

Syntax: workflow pause task TASK_ID [reason REASON]

where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.pause(fields.TASK_ID.value, "reason", user);

Unpause task

Used to release a paused task back to the active state. This would typically be issued from a task list application.

FPL:

API based language (Javascript):

Syntax: workflow unpause task TASK_ID [reason REASON]

where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.unpause(fields.TASK_ID.value, "reason", user);

Re-execute task

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.

FPL:

API based language (Javascript):

Syntax: workflow reexecute task TASK_ID [reason REASON]

where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.reexecute(fields.TASK_ID.value, "reason", user);

Change task priority

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.

FPL:

API based language (Javascript):

Syntax: 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.

var user = system.securityManager.userName;

system.workflow.api.setPriority(fields.TASK_ID.value, 1, "reason", user);

Skip task

Used to skip a task. This is similar to cancel task and can be used to skip scripted nodes such as decisions and system tasks.

FPL:

API based language (Javascript):

Syntax: workflow skip task TASK_ID [reason REASON]

where TASK_ID and REASON can be form fields containing the appropriate value or a quoted string.

var user = system.securityManager.userName;

system.workflow.api.forceCompletion(fields.TASK_ID.value, "reason", user);

Complete task

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.

FPL:

API based language (Javascript):

Syntax: workflow complete [COMPLETION_STATE] [reason REASON]

where COMPLETION_STATE and REASON can be form fields containing the appropriate value or a quoted string.

Default completion state is ‘COMPLETED’ if not specified.

// Default completion state is ‘COMPLETED’ if not specified

system.workflow.completeTask();

// Use specific completion state

system.workflow.completeTask("Rejected");

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 opened.

$WF_JOB_ID contains the unique job id, and is set when a new job is created.

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 commands or corresponding API methods Workflow.openJob() and Workflow.openJobAndCompleteFirstTask():

Open Job

Opens a new job for workflow process PROCESS_NAME. See above.

Start Job

This is a variation on 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. See 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.

Step 2: add workflow completion (required)

When the task has been completed, the form must signal completion to the workflow system:

FPL:

API based language (Javascript):

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.

// Completion state is not required if there is only one possibility

system.workflow.completeTask();

// Completion state is required if more than one completion state exists

system.workflow.completeTask("Completed");

These statements signal completion of the interactive task associated with the current form (designated by system variable $WF_TASK_ID) to the workflow system. Any form fields specified as workflow out parameters are also passed to the workflow system. 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 optional and if not specified 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 WORKFLOW_TASKLIST is provided in project SAMPLES and this can be used to display a list of all tasks for a user. This form is provided as a sample and can be used as provided or as a model. Please do not change the supplied version as this may be re-imported with future Ebase upgrades without notification. Instead, create a new project and copy the sample form and associated scripts to this.

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