Xi Assignment Handler
Configure
workflow designer properties
Configure
workflow server properties
Create
the Workflow Assignment System Service.
Running
the Process Tester Dialog
Description
The Xi Assignment Handler is the default workflow assignment handler supplied with the Ebase Xi system and it provides an easy-to-use and flexible technique for implementing workflow assignment. This assignment handler uses standard scripts to perform the assignment and this provides the ability to do programmable assignment e.g. it’s possible to check the value of process attributes within a workflow job, read data from a database or a web service etc. Use of this assignment handler is recommended.
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 – this is just a string value
· At runtime, when the interactive task is started:
o The assignment handler invokes the Workflow Assignment System Service configured for the workflow process, passing the assignment key
o The System Service sets the assignment criteria
o The assignment handler performs the assignment
Implementation
The steps to implement the Xi Assignment Handler are:
- Configure workflow designer properties
- Configure workflow server properties
- Create the Workflow Assignment System Service, or modify the default service provided
Then, for each assignment key…
- Write and test the Workflow Assignment System Service script logic
Configure workflow designer properties
The Workflow Assignment Handler class name in the Workflow tab of Designer Preferences should be set to com.ebasetech.ufs.xi.workflow.XIAssignmentHandler. This must match the same property on the server (next section).
Configure workflow server properties
The following workflow properties can be configured using the Server Administration Application:
- Assignment Handler: specify the assignment handler class name com.ebasetech.ufs.xi.workflow.XIAssignmentHandler. This must match the corresponding property configured for the designer (pervious section).
- Default Xi Assignment Service Web Service Name: the web service name of the default Workflow Assignment System Service. If not specified this defaults to ebaseAssignmentService which is the web service name of the supplied service WORKFLOW_ASSIGNMENT_SERVICE in project System Services.
- Assignment Default Type: the default assignment type. This is used when there is an error calling the workflow assignment system 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, tasks with failing assignments are assigned to the role specified in property Assignment Default Value. When User is specified, tasks with failing assignments are assigned to the single user specified in property Assignment Default Value. See also Error handling.
- Assignment Default Value: see previous property. The default is WFADMIN if not specified.
Create the Workflow Assignment System Service
This is an optional step. You can create a new Workflow Assignment System Service in the designer: right click in the tree and select New > System Service > Workflow Assignment Service. This will create both a new service and also a new Workflow Assignment Service Resource, and import all the fields and tables from the resource into the service. The resource contains the request and response documents required by the service; the format of these documents is fixed so you can’t make any changes to the resource – it is read only. All you need to do to use this service is add a script and any additional fields and tables required by the script.
Each System Service must be configured with
a unique web service name (this is configured in the System Service Editor
panel). To use the new Workflow Assignment System Service within a workflow
process, click the process properties icon 
in the Workflow Process Editor then enter the
web service name of the Workflow Assignment System Service in the Assignment Service box.
Alternatively you can use the default Workflow Assignment System Service in the System Services project.
Write and test the script
When the Workflow Assignment System Service is called from the Xi Assignment Handler, it runs any scripts configured on the integration event – usually only one script is configured. This script should be customized as required.
The format of the request and response documents is defined in the Workflow Assignment Service Resource linked to the assignment service (System Resources can be viewed, but cannot be changed).
The Request XML document is shown below and this is populated automatically 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 Xi 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 that 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 configured in XI Assignment Handler Properties in server workflow properties. 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 i.e. no assignment has been specified, an error condition is raised.
Testing
The Workflow Assignment System 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.
Sample scripts
Javascript
importPackage(com.ebasetech.xi.api);
importPackage(com.ebasetech.xi.services);
switch (fields.WFKEY.value)
{
// CreditController
- role loanAdmin
case "CreditController":
tables.ROLES.insertRow();
tables.ROLES.ROLEID
= "loanAdmin";
tables.ROLES.updateTable();
break;
// Dispatcher - role Dispatcher or member
of the Dispatch Department (user credential)
case
"Dispatcher":
tables.ROLES.insertRow();
tables.ROLES.ROLEID.value
= "Dispatcher";
tables.ROLES.updateTable();
tables.CREDENTIALS.insertRow();
tables.CREDENTIALS.ID.value
= "Department";
tables.CREDENTIALS.VALUE.value
= "Dispatch";
tables.CREDENTIALS.updateTable();
break;
// Director - named users or role Director
case "Director":
tables.USERS.insertRow();
tables.USERS.USERID.value
= "Userid1";
tables.USERS.insertRow();
tables.USERS.USERID.value
= "Userid2";
tables.USERS.updateTable();
tables.ROLES.insertRow();
tables.ROLES.ROLEID.value
= "Director";
tables.ROLES.updateTable();
break;
}
FPL
// CreditController - role 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 using the XI Assignment Handler Properties in server workflow properties, and these are automatically applied if there is any error invoking the Workflow Assignment System 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 therefore it is possible that assignment errors are not noticed – which in practice will mean a hanging workflow job. The administrator can then manually re-assign any failed tasks using the workflow 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 System Service is not available
- A Soap fault is returned (script failure)
- An error code other than 00000 is returned
- Workflow Assignment System 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 System 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 System 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
A Workflow Assignment System Service is supplied with the system: DefaultWorkflowAssignmentService at path System_Services/DefaultWorkflowAssignmentService in project ebaseSamples and has a web service name of ebaseAssignmentService.
The associated script WORKFLOW_ASSIGNMENT_SERVICE_LOGIC_JS interprets the assignment key as a role name. This works together with the supplied implementation of the Xi Logon Service.
The WORKFLOW_ASSIGNMENT_SERVICE_LOGIC_JS script contains the following:
tables.ROLES.insertRow();
tables.ROLES.ROLEID.value = fields.WFKEY.value;
tables.ROLES.updateTable();