This documentation is for WSO2 Enterprise Integrator version 6.3.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.
Working with BPMN User Substitution - Enterprise Integrator Documentation - WSO2 Documentation

All docs This doc
||
Skip to end of metadata
Go to start of metadata

This section guides you through user substitution and how to work with it. 

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, the task assignee goes on vacation. In this case, all the tasks assigned to this user will get delayed until the particular assignee is available again and nobody else will be able to work on these tasks either. To avoid this kind of unnecessary processing delay, you can use the user substitution feature. This means that when a user is not available for a certain period of time, all tasks assigned to that user will be assigned to the defined substitute instead. 

How it works

  • Users are allowed to define a substitute for themselves within the time period that they are going to be unavailable. 
  • Once this specified period (substitution period) starts, all the existing tasks of the user are transferred to the substitute (i.e.,bulk reassignment). 
  • From this point onwards, any new tasks that are going to be assigned to the user will be assigned to the substitute user instead. 
  • The substitute user will also be added as a candidate user to all the existing tasks for which the original assignee is a candidate user.

If the given substitute is also not available (i.e., the substitute also goes on vacation), you can enable transitivity. Enabling transitivity allows the engine to try and find a transitive substitute by going through available substitution records. In this way, the engine uses 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 it will be claimable.

EI Business Process provides REST APIs to add, update and lookup substitution information. Alternatively, you can also use the BPMN­-explorer to experience all the facilities provided by substitution APIs.

Enabling user substitution

  1. Run the database script <EI_HOME>/wso2/business-process/dbscripts/bps/bpmn/create/activiti.<DB_Name>.create.substitute.sql against your BPMN engine's database to add the Substitution related table.
  2. Open the activiti.xml file found in the <EI_HOME>/wso2/business-process/conf directory 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>
PropertyValueDescription
enabledtrueSet to true to enable the substitution feature.
enableTransitivitytrueSet to true to enable substitution to transitive substitutes if the provided substitute is not available, as explained above.
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.

Permission Scheme

Each valid 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. Viewing and changing substitution records of other users requires the 'substitution' permission. The substitution permission path is as follows.

A dmin Permissions/Manage/BPMN/Manage BPMN Substitutions

See Managing Role Permissions for more information on adding permissions.

Adding and managing user substitution

This section guides you through using the interface on the BPMN explorer to perform user substitution. 

Alternatively, you can use the substitution APIs to do this. For more information, see BPMN REST API

Prerequisite - Enabling user substitution

  1. Run the database script <EI_HOME>/wso2/business-process/dbscripts/bps/bpmn/create/activiti.<DB_Name>.create.substitute.sql against your BPMN engine's database to add the Substitution related table.
  2. Open the activiti.xml file found in the <EI_HOME>/wso2/business-process/conf directory 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>

Adding a substitute

  1. Login to the BPMN explorer and select the Substitutions tab. 
  2. Click on Add Substitute and fill in the following fields.
  3. You can now see the substitution record you just added listed under the My Substitutions Information section. The Substituted Assignees section lists the substitution records where you (the logged in user) is a substitute for another user. 

    • To deactivate the substitution, click the Deactivate button next to Substitution Status.This will deactivate the substitution regardless of the time period.
    • To update the existing substitution, click on the Update button.

Updating a substitute

  1. Login to the BPMN Explorer and select the Substitutions tab.
  2. The existing substitute and substitution details will appear under the My Substitutions Information section. 
  3. Click on the Update button to update this substitution record. 
  4. Change the details you wish to change and click Update. 

Deactivating a substitute

  1. Login to the BPMN Explorer and select the Substitutions tab.
  2. The existing substitute and substitution details will appear under the My Substitutions Information section. 
  3. Click on the Deactivate button. This will deactivate the substitution regardless of the specified time period. 
  4. The substitution status will change to "Inactive". You can re-activate this substitution by clicking on the Activate button again. 

Substituting the Admin view

  1. Login to the BPMN Explorer and select the Substitutions tab.
  2. Click on the Go to Substitutions Admin View button. You will see all substitution records of all users (i.e, not just the currently logged in user) listed under the Substituted Assignees section. 

    • Click on the relevant row to update an existing substitution record. 
    • Click on Deactivate for the relevant substitution to deactivate it. 
    • Click on the Add Substitute button to add a new substitution for any user. 

    Note: This button and view is only visible when the user has substitution permissions.

Trying it out

To try out this sample scenario, you can use the UserTaskCreatorProcess.bar sample. The sample requests a username for the assignee and will create a user task that is assigned to a given user. To deploy the sample and run through the sample scenario, see User Substitution

  • No labels