Xi Assignment Handler
1. Configure
the XIassignment properties file
2. Configure
the Xi assignment Handler
Running
the Process Tester Dialog
Description
Xi Assignment Handler is a supplied workflow assignment handler that provides an easy to use technique for implementing workflow assignment using standard scripts. The job of the assignment handler is to control how users are assigned to workflow interactive tasks; these tasks are then typically displayed to the user in a task list. The Xi Assignment Handler supports assignment based on a number of different criteria:
· A single user or a list of users
· Role based assignment
· Credential based assignment
· Combinations of the above
The Xi Assignment Handler has been designed to work in partnership with the Logon Service which implements the user logon process and is responsible for adding roles and credentials to users.
The assignment handler works as follows:
· At design time, an interactive task is given an assignment key
· At runtime, when the interactive task is first created:
o The assignment handler invokes the system service WORKFLOW_ASSIGNMENT_SERVICE passing the assignment key
o WORKFLOW_ASSIGNMENT_SERVICE returns the assignment criteria
o The assignment handler performs the assignment
Implementation
The steps to implement the Xi Assignment Handler are:
- Configure the XIassignment.properties file
- Configure the Xi assignment handler
Then, for each assignment key…
- Write and test the script logic in system service WORKFLOW_ASSIGNMENT_SERVICE
1. Configure the XIassignment properties file
The XIassignment.properties file is located in directory WEB-INF/classes of the web application. It contains the following properties:
Assignment.Handler
The URL of the system web service WORKFLOW_ASSIGNMENT_SERVICE. If not specified, this defaults to an internal URL to access the service on the same server. When specified, this parameter should have the format http://domain[:port]/webapp/integration/ebaseAssignmentService where domain, port and webapp are substitutable.
Assignment.defaultType
The default assignment type. This is used when there is an error calling the WORKFLOW_ASSIGNMENT_SERVICE service or if the service fails to return valid assignment criteria. Supported values are Role and User (the default is Role). When Role is specified, failing tasks are assigned to the role specified in Assignment.defaultValue. When User is specified, failing tasks are assigned to the single user specified in Assignment.defaultValue. See also Error handling.
Assignment.defaultValue
See Assignment.defaultType. The default is WFADMIN if not specified.
2. Configure the Xi assignment Handler
In UFSSetup.properties in directory WEB-INF/classes of the web application, configure the Xi assignment handler as follows:
Workflow.AssignmentHandler=com.ebasetech.ufs.xi.workflow.XIAssignmentHandler
And restart the ebase server.
3. Write and test the script
When the system web service WORKFLOW_ASSIGNMENT_SERVICE is called from the Xi Assignment Handler, it runs any scripts configured on the integration event. These scripts should be customized as required.
System Services can be located from the designer tree System --> Internal Web Services --> System Services. Access from the designer is controlled by security authorisation:
Type: Project
Name: System Services
System Services can be edited, but they cannot be deleted or renamed.
The message for the WORKFLOW_ASSIGNMENT_SERVICE service is defined in System Resource WORKFLOW_ASSIGNMENT_REQUEST (System Resources can be viewed, but cannot be changed).
This message consists of a Request XML document which is populated by the assignment handler.
Where:
WFKEY: the assignment key value as entered in the Resources tab of the task node configuration dialog in the Ebase Designer
MODE: this will have the value Task or Job
- Task indicates the system service has been called to resolve interactive task assignment
- Job indicates the system service has been called to resolve job owner assignment (See Job Owner Assignment)
TEST: this will have the value Y or N, where Y indicates that the assignment is from the Workflow Process Tester dialog in the Ebase Designer (See Running Process Tester)
ATTRIBUTES: this is a table containing the current values of all process attributes for the job. Process attributes can be useful for performing assignments when the single value provided by the assignment key is not sufficient e.g. a process attribute could be set by the workflow process with contextual information and then checked by this script. Please note that process attributes are only present for Task Mode.
The Response XML document must be populated with the assignment criteria by the script.
Where:
USERS: is a list of users who can be assigned.
ROLES: is a list of roles (Ebase roles or custom roles). Any users with these roles can be assigned.
ROLE_CONDITION: can contain the value ANY or ALL (default is ANY if not specified)
- ANY indicates that the user can be associated with any role in the list
- ALL indicates that the user must be associated with all roles in the list
CREDENTIALS: is a list of credential names and values. Any users with these credential values can be assigned.
CREDENTIAL_CONDITION: can contain the value ANY or ALL(default is ANY if not specified)
- ANY indicates that the user can match any credential in the list
- ALL indicates that the user must match all credentials in the list
ERRORCODE: set this to a value other than 00000 to indicate that the assignment has failed and the task should be assigned as per the default settings in the XIassignment.properties file. See Error handling.
ERRORDESCRIPTION: set this in conjunction with ERRORCODE to indicate the reason why the assignment has failed. See Error handling.
ROLE_CREDENTIAL_JOIN_CONDITION: can contain the value ANY or ALL(default is ANY if not specified)
- ANY indicates that a user can match either the role or the credential criteria
- ALL indicates that the user must match both the role and the credential criteria
Task assignment is done according to the following rules. These rules are applied when a task list for a user is requested.
- If a match is found to a user in the USERS table, the task can be assigned to the user. The remaining criteria (roles and credentials) are not checked.
- If no match is found in the USERS table or the USERS table is empty, the roles and credentials criteria are evaluated.
- If ROLE_CREDENTIAL_JOIN_CONDITION is set to ANY (the default) and there is match with either the role or the credential criteria, the task can be assigned to the user.
- If ROLE_CREDENTIAL_JOIN_CONDITION is set to ALL the task can be assigned to the user if there is match with both the role and the credential criteria.
Therefore, it is possible to mix different assignment criteria e.g. a list of users plus a list of roles.
Note that if the USERS, ROLES and CREDENTIALS tables are all empty, an error condition is raised.
Testing
The WORKFLOW_ASSIGNMENT_SERVICE service can be tested by
clicking the test icon 
on the toolbar of the System Service Editor.
The test dialog shown below is then displayed. Fill in test values in the
request document and click the Submit
button.
A sample FPL script
// CreditController
- roles loanAdmin or loanAudit
if [ wfkey = 'CreditController' ]
insertrow roles;
set role-roleid =
'loanAdmin';
insertrow roles;
set role-roleid =
'loanAudit';
updatetable roles;
return;
endif
// Dispatcher - role
Dispatcher or member of the Dispatch Department (user credential)
if [ wfkey = 'Dispatcher' ]
insertrow roles;
set role-roleid =
'Dispatcher';
updatetable roles;
insertrow
credentials;
set credential-id =
'Department';
set credential-value
= 'Dispatch';
insertrow
credentials;
updatetable
credentials;
return;
endif
// Director - named
users or role Director
if [ wfkey = 'Director' ]
insertrow users;
set user-userid =
'Userid1';
insertrow users;
set user-userid = 'Userid2';
updatetable users;
insertrow roles;
set role-roleid =
'Director';
updatetable roles;
return;
endif
Error Handling
Default assignment properties are specified in the XIassignment.properties file, and these are automatically applied if there is any error invoking the WORKFLOW_ASSIGNMENT_SERVICE service. These default values should normally be configured so that any failed assignments are assigned to a workflow administrator. It is quite important that a check is made regularly for assignment errors as workflow runs as a background task and otherwise, it is easy to lose errors – which in practice will mean a hanging workflow job. The administrator can then manually re-assign any failed tasks using the process administrator application.
If a script failure occurs, a Soap fault message is returned. If necessary, such failures can be caught with an On Error event.
An error is recognised in any of these circumstances:
- The WORKFLOW_ASSIGNMENT_SERVICE is not available
- A Soap fault is returned (script failure)
- An error code other than 00000 is returned
- The WORKFLOW_ASSIGNMENT_SERVICE returns a null assignment (tables USERS, ROLES and CREDENTIALS are all empty)
All errors are logged to the server log.
In addition, if the workflow process contains process attributes named ERRORCODE or ERRORDESCRIPTION, these will be set with any error details returned from the system service.
Job Owner Assignment
The WORKFLOW_ASSIGNMENT_SERVICE can be invoked to resolve dynamic job owner assignment. This applies when the dynamic option is checked in the Job Owner tab of process properties.
Dynamic job owner assignment makes it possible to assign job owner dynamically at the point where the information has been requested.
When this option is enabled:
MODE in the request document is set to Job
The ATTRIBUTES table in the request document is empty
For job owner assignment, the system service must return a
single user (all forms of multiple assignment are disallowed). If the system service returns anything other
than a single user, an error is recognised and the job owner will be assigned
to the value specified in property Assignment.defaultValue and default
assignment type is set to User.
Running the Process Tester Dialog
When the WORKFLOW_ASSIGNMENT_SERVICE is called from the process tester dialog, field TEST in the request document is set to Y. If necessary, the scripting logic can test for this and return appropriate values. However, this is not required and assignments can be made in test mode in the same way as when running a live workflow job. Assignments to roles and credentials are shown in the example below. This makes it possible to test the assignment process as part of the normal process testing.
Supplied Implementation
In the shipped product, the WORKFLOW_ASSIGNMENT_SERVICE interprets the assignment key as a role name. This works together with the supplied implementation of the Xi Logon Service, both of which are based on the supplied Ebase security system. Users and roles are created from the Ebase Designer Tools --> Maintain Security; users can be added to groups which can also have roles.
The WORKFLOW_ASSIGNMENT_SERVICE_LOGIC FPL script contains the following:
// Supplied example logic works with the supplied Ebase
internal security system
// WFKEY is assumed
to be the name of a security role (see Ebase security system - Tools -->
Maintain security)
insertrow roles;
set role-roleid = WFKEY;
updatetable roles;