Substituting Users

User substitution involves defining a substitute for a particular user for a given time window. This functionality is particularly useful in BPMN User Tasks when the original task assignee becomes unavailable for a period of time. For example, in a situation if the task assignee (user1) goes on vacation, substitution will work as follows.

User1 can define a substitute user for the time period that he/she will be unavailable.
Once this substitution period starts, all the existing tasks of user1 are transferred to the substitute to user2 as a bulk reassignment.
From this point onwards, any new tasks that are going to be assigned to user1 will be assigned to user2 instead.
The substitute user (i.e., user2) will also be added as a candidate user to all the existing tasks, for which the original assignee (i.e., user1) is a candidate user.

The below sections demonstrate how to use the sample, which is shipped with WSO2 EI, to simulate this BPMN user substitution feature via the BPMN Explorer.

Alternatively, you can use the BPMN substitution APIs to add, update and look up for substitution information. For more information, see BPMN REST API.

Creating the users

Follow the steps below to create the two users.

Log in to the Management Console of the Business Process profile.
Click Configure → Users and Roles → Add → Add New User.
Enter the below details to create a user called user1 and click Next.
In the next screen, assign the user to the admin role and click Finish.
Repeat the above steps to create user2 as shown below.

You vire the users created as shown below.

Setting user substitution permissions

Normally, a user has permission to add update and view his/her own substitution records and to view the substitution records where he/she acts as a substitute. Since you added the admin role for both user1 and user2 above, all these permissions are granted on them by default. Neverthless, if you created a user with some other role, you need to grant the 'Admin Permissions → Manage → BPMN → Manage BPMN Substitutions' permission to that user, to view and change substitution records of other users as shown below.

Deploying the sample

Follow the steps below to deploy the sample.

Login to the Management Console as the admin, using admin/admin credentials.
Navigate to Processes → Add → BPMN and upload the <EI_HOME>/samples/business-process/bpmn/UserTaskCreatorProcess.bar file.

You view the process deployed as shown below.

Enabling user substitution

Follow the steps below to enable user substitution.

Point your DBMS to the database, which stores data related to the BPMN Engine, and execute the <EI_HOME>/wso2/business-process/dbscripts/bps/bpmn/create/activiti.<DB_Name>.create.substitute.sql database script, based on your Database type.

This creates the table, which stores data related to user substitution. Skip this step if you are using the standalone WSO2 EI distribution to run this sample.

Open the file in the <EI_HOME>/wso2/business-process/conf/activiti.xml and uncomment the following configuration.

<bean id="userSubstitutionConfiguration">    <property name="enabled" value="true"></property>
    <property name="enableTransitivity" value="false"></property>
    <property name="activationInterval" value="60"></property>
</bean>

User substitution properties

The below table describes the properties of the above user substitiue configuration.

Property	Value	Description
`enabled`	true	Set to true to enable the substitution feature.
`enableTransitivity`	true	Set to true to enable substitution to transitive substitutes if the provided substitute is not available. When you enabling transitivity, the engine tries and finds a transitive substitute by going through the available substitution records and picks the best available user as the substitute. However, if the system could not find a proper substitute (i.e., there is a cyclic dependency between substitutions), it will return an error, rejecting the substitution request. This rejection is possible only for the substitutions that start just after the substitute request. For a scheduled substitution, if the engine ends up without a proper substitute, the tasks of the user will be assigned to the ‘task owner’. If the task owner is not defined, the assignee will be removed from the tasks, and thereby, the tasks become claimable.
`activationInterval`	<scheduler running interval in minutes>	A scheduler is running to activate scheduled substitutions and update transitive substitutes if transitivity is enabled. Specify the time interval in minutes that the scheduler should run. The scheduler activates a given substitution in the time frame specified here.

Trying out the sample

Follow the steps below to try out how to substitute user1 with user2.

Log in to the BPMN explorer as the admin using admin/admin credentials.
Click PROCESSES in the top menu, and click the Start option of the User task Creator Process.
Start a few process instances of the User task Creator Process by giving ‘user1’ as the assignee.
Log out as admin and log in as "user1" on the BPMN explorer using the relevant credentials.
Select the My Tasks tab. You will see a few tasks listed that are assigned to user1.
Select the Substitutions tab and click Add Substitute. Enter "user2" as the substitute user and enter start and end times.

You view the substitution record you just added listed under the My Substitutions Information section.
Viewing substituted assignees
The Substituted Assignees section lists the substitution records where you (the logged in user) is a substitute for another user. For example, if you add the admin user as a substitute for user1, the record will be added as shown below.
Using the Substitutions Admin view
Click on the Go to Substitutions Admin View button, to manage user substitutions via the Admin View. You view all substitution records of all users (i.e, not just the currently logged in user) listed under the Substituted Assignees section.

This Go to Substitutions Admin View button is only visible when the role of the user is granted with the Substitution permissions when creating it.
- Click on the relevant row to update an existing substitution record.
- Click Deactivate to deactivate it a substitute.
- Click on the Add Substitute button to add a new substitution for any user.
Click the TASKS → My Tasks tab. You will see that there are no tasks for user1 anymore. All the existing tasks that were assigned to "user1" have been substituted to "user2" due to your substitution request.
Log out as "user1" and log in as "user2" and select the My Tasks tab. Now, you view the tasks with the name "User task for user1" assigned to "user2".
Log in as admin and start a few task instances for user1 again and log out.
Log in as "user2" and click TASKS → My Tasks. You view that the tasks you just assigned to "user1" are assigned to "user2" instead. This is because future tasks are also being reassigned according to the substitution record.
Log in again as "user1" and select the Substitutions tab. Click on the Deactivate button. This will disable the existing substitution record. Now the substitution view will look as follows.
Log in as admin and start a few task instances giving "user1" as the assignee again and log out.
Log in as "user1" again and click TASKS → My Tasks. You view that these tasks are now available for user1 since the substitution was disabled in the above step.