com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Configuring Human Task Coordination

Human Task coordination

This section explains the Human Task Coordination protocol implementation of the Business Process profile. Human Task Coordination Protocol is used to coordinate between the task process and Task Parent. The following diagram from the WS-Human Task specification shows how the coordination context is used alone with the task parents protocol handler and task processor protocol handler for coordination.

Human task coordination is useful for the following scenarios:

  • A BPEL process (task parent) has created some tasks in the task processor. If the BPEL process instance is terminated due to some condition, it is necessary to exit all the task instances within the human task engine since, the task parent is no longer active. This activity can be performed using the coordination protocol by keeping track of all the tasks that are associated with a given task parent.
  • Additionally, when a task is skipped or when a fault happens from the task engine side, this information needs to be sent to the task creating BPEL process.

Components

The following are the various components involved in the process of human task coordination.

Components

Details

Configuration

B4P component (org.wso2.carbon.bpel.b4p)

Acts as a task parent and undertakes coordination between the task engine and itself.

Publishes ws-coordination registration service.

Configured using the b4p-coordination-config.xml file located at <EI_HOME>/wso2/business-process/conf/b4p-coordination-config.xml

Human task engine (org.wso2.carbon.humantask)

Task Processor. Publishes protocol handler service per tenant.

Configured using the humantask.xml file located at <EI_HOME>/wso2/business-process/conf/humantask.xml


 

Human task coordination module (org.wso2.carbon.humantask.coordination.module)

An Axis2 module that intercepts the coordination message to do the initial coordination with the Task Parent.

Configured using the humantask.xml file located at <EI_HOME>/wso2/business-process/conf/humantask.xml

Compliance with WS-Humantask-1.1, BPEL4People-1.1 and WS-Coordination-1.2

Human task protocol messages

The following protocol messages are supported by task engine and task parent.


Protocol Message

Receiver

Exit

Task Engine

Skip

B4P module ( Task Parent )

Fault

B4P module ( Task Parent )

Human task context support

The following optional override attributes are accepted by the Task Engine:

  • Priority
  • isSkipable

Other human task context attributes are not supported with the current implementation.

Protocol handlers
Task Engine

Task Engine creates a protocol handler (HumanTaskProtocolHandler admin service) per tenant. These services are secured with HTTP basic authentication and hence only available as HTTPS transport.

Task Parent

The B4P module does not create a separate protocol handler service, but it re-uses a task's CallBack service as it’s Protocol Handler. This service does not support protocol messages defined in Human Task spec 1.1 section 8.2.1, However, it supports corresponding functionalities using custom soap headers.

Registration service (ws-coordination)

Registration service is used to coordinate task parent and task engine during task creation phase. This service is secured as an admin service and each tenant has its own registration service.

Note:- This service can be skipped using configuration XML file and it is not compliant with ws-coordination 1.2 and ws-humantask 1.1. In this case Task parent predicts Task Engine's Protocol Handler URL by using Task's service URL. By default this configuration is enabled since within a Business Process profile cluster, coordination function is achievable without the registration service and reduces the additional overhead introduced by the registration service.

Enabling human task coordination

For the human task coordination to function properly, you need to enable task coordination at both the Task Parent and Task Processor. In the Business Process profile of WSO2 EI, you can enable this feature in both Task Parent (B4P module) and Task Processor using the following configuration options. The following steps address human task processor configuration.

  1. Navigate to the <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the humantask.xml configuration file.
  2. Set the TaskCoordinationEnabled entry to true.

    <HumanTaskCoordination>
    	<TaskCoordinationEnabled>true</TaskCoordinationEnabled>
    </HumanTaskCoordination>

Use the following steps to enable HumanTask Coordination in the B4P module (Task Parent).

  1. Navigate to the <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the b4p-coordination-config.xml file. 
  2. Set the TaskCoordinationEnabled entry to true.

    <HumanTaskCoordinationConfiguration>
    	<TaskCoordinationEnabled>true</TaskCoordinationEnabled>
    </HumanTaskCoordinationConfiguration>

Coordination Protocol Services and Registration service are implemented as WSO2 Carbon admin services. In order to access these services, a user needs to be authenticated to the system. In the Business Process profile task coordination, these services are authenticated using a user created in the Business Process profile and configured within the config files. You can either create an individual user for authentication, or create an entire tenant where all users within it can authenticate task coordination. See the sections below:

Creating a predefined user for authentication

Use the following instructions to create a role and a user.

Step 1: Create a role
  1. Start the Business Process profile If it is not started already.
  2. Go to the Configure menu in the management console and navigate to Users and Roles > Role.
  3. Click "Add New Role".
  4. Enter a name for the role (e.g.: htcoordinatorRole) and click Next.
  5. Select the following permissions for the newly created role.

    These are minimum permission requirements.

    • All Permissions \ Admin Permissions \ Login
    • All Permissions \ Admin Permissions \ Manage \ HumanTask \ View Task List
  6. Click Finish.
Step 2: Create a user for the above created role
  1. Go to the Configure menu in the management console and navigate to Users and Roles > Users.
  2. Click "Add New User".
  3. Enter relevant values in the username and password fields.
  4. Click Next.
  5. Select the rolename defined above for the role
  6. Click Finish.
Step 3: Configure the above created user in b4p-coordination-config.xml
  1. Navigate to the <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the b4p-coordination-config.xml file.
  2. Set the username and password in the TaskProtocolHandlerAuthentication entry as follows.

    <TaskProtocolHandlerAuthentication>
    	<Username>htcoor</Username>
    	<Password>htcooradmin</Password>
    </TaskProtocolHandlerAuthentication>
Step 4: Configure the above created user in humantask.xml
  1. Navigate to the  <EI_HOME>/wso2/business-process/conf/ directory and open the humantask.xml configuration file
  2. Set the username and password in the RegistrationServiceAuthentication entry as follows. 

    <RegistrationServiceAuthentication>
    	<Username>htcoor</Username>
    	<Password>htcooradmin</Password>
    </RegistrationServiceAuthentication>
  • You can configure two users for Humantask engine and B4P module.
  • You can secure (encrypt) the plain text entries for the username and password in the configuration files using the WSO2 Secure vault tool. See advanced configuration section for this configuration. 

Creating a tenant for authentication

Step 1: Create a registry resource in the tenant's configuration registry
  1. Start the Business Process profile If it is not started already.
  2. Navigate to Registry>Browse in the Main menu of the management console and click on /_system/config.
  3. Click on Entries>Add Resource and fill the form using the values listed below for guidance. 
    • Method: Create Text Content
    • Name: TaskCoordination
    • Media type: text/plain
  4. Click Add to finish adding the resource.
Step 2: Create username and password registry properties and define credentials
  1.  Click on the registry resource you created (Task Coordination) found under the Entries section. 


  2. Add two new registry properties for the resource called "Username" and "Password", and define the tenant coordination user credentials. To do this, click Properties>Add New Property and enter the following values. 

    • Username Property
      Name:
       username
      Value: (username value)
    • Password Property
      Name:
       password
      Value: (password value)
  3. Click Add to finish adding the property.

The following are advanced configurations which can be made for human task coordination:

Securing username/password with secure vault

You can secure (encrypt) username/password fields in the b4p-coordination-config.xml and humantask.xml config files using WSO2 secure vault tool. 

Step 1: Add secret aliases to configurations files

  1. Navigate to the <EI_HOME>/wso2/business-process/ conf/ directory in your local machine and open the b4p-coordination-config.xml file.
  2. Add humantask secret aliases to TaskProtocolHandlerAuthentication as shown below.

    <TaskProtocolHandlerAuthentication>
    	<Username svns:secretAlias="HumanTask.ProtocolHandler.Username">user</Username>
    	<Password svns:secretAlias="HumanTask.ProtocolHandler.Password">password</Password>
    </TaskProtocolHandlerAuthentication>
  3. Navigate to the <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the humantask.xml configuration file.
  4. Add B4P secret aliases to RegistrationServiceAuthentication as shown below.

    <RegistrationServiceAuthentication>
    	<Username svns:secretAlias="B4P.RegistrationService.Username">user</Username>
    	<Password svns:secretAlias="B4P.RegistrationService.Password">password</Password>
    </RegistrationServiceAuthentication>

Step 2: Modify "cipher-text.properties" file

  1. Add the above secret aliases with plain text username/password values enclosed by square brackets to the cipher-text.properties file located at <EI_HOME>/wso2/business-process/conf/security.

    B4P.RegistrationService.Username=[admin.username]
    B4P.RegistrationService.Password=[admin.password]
    HumanTask.ProtocolHandler.Username=[admin2.username]
    HumanTask.ProtocolHandler.Password=[admin2.username]

    An example configuration for user "admin" with password "admin123" is as follows:

    B4P.RegistrationService.Username=[admin]
    B4P.RegistrationService.Password=[admin123]
    HumanTask.ProtocolHandler.Username=[admin]
    HumanTask.ProtocolHandler.Password=[admin123]
  2. Update other secret aliases values (username/password) if not updated yet.

Step 3: Modify "cipher-tool.properties" file

Add the following entries to cipher-tool.properties file located at <EI_HOME>/wso2/business-process/conf/security.

HumanTask.ProtocolHandler.Username=b4p-coordination-config.xml//HumanTaskCoordinationConfiguration/TaskProtocolHandlerAuthentication/Username,true
HumanTask.ProtocolHandler.Password=b4p-coordination-config.xml//HumanTaskCoordinationConfiguration/TaskProtocolHandlerAuthentication/Password,true
B4P.RegistrationService.Username=humantask.xml//HumanTaskServerConfig/HumanTaskCoordination/RegistrationServiceAuthentication/Username,true
B4P.RegistrationService.Password=humantask.xml//HumanTaskServerConfig/HumanTaskCoordination/RegistrationServiceAuthentication/Password,true

Step 4: Run the Cipher tool

Go to <EI_HOME>/wso2/business-process/bin directory and run the Cipher tool using the following command:

sh ciphertool.sh -Dconfigure

This will create encrypted values for given plain text values. If this was successfully completed, Cipher tool will replace values in configuration file with dummy values and the human task coordination feature will read those configurations using Secure Vault.

If you want to change encrypted values, run the Cipher tool again with the -Dchange parameter.

sh ciphertool.sh -Dchange

Enabling registration service and task registration

The registration service is used by the task engine to register a task with the Task Parent (B4P module). This service is compliant with HumanTask 1.1 Specification. However, Task Registration introduces an overhead as additional Web service invocations are required. Hence, if it is within the same Business Process profile cluster and in the super tenant mode (default deployment), skipping the registration service improves performance in the system. The registration service is disabled by default. You can enable the registration service as shown in the following steps:

  1. Navigate to the <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the b4p-coordination-config.xml file.
  2. Set the RegistrationServiceEnabled entry to true.

    <RegistrationServiceEnabled>true</RegistrationServiceEnabled>
  3. Navigate to the <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the humantask.xml configuration file.
  4. Set the TaskRegistrationEnabled entry to true.

    <TaskRegistrationEnabled>true</TaskRegistrationEnabled>

Configuring load balancer for human task coordination

If task processors are clustered, use the following configuration to enter the URL for the load balancer.

  1. Navigate to the  <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the b4p-coordination-config.xml file.
  2. Uncomment the ClusteredTaskEngines entry and set LoadBalancerURL as follow.

    <ClusteredTaskEngines>
    	<LoadBalancerURL>http://bps.loadblancer-url.com</LoadBalancerURL>
    </ClusteredTaskEngines>
  3. Navigate to the  <EI_HOME>/wso2/business-process/conf/ directory in your local machine and open the humantask.xml configuration file.
  4. Uncomment the ClusteredTaskEngines entry and set LoadBalancerURL as follow.

    <ClusteredTaskEngines>
    	<LoadBalancerURL>http://bps.loadblancer-url.com</LoadBalancerURL>
    </ClusteredTaskEngines>

Fault Protocol Messages are not generated by the Task Engine as the Task engine does not generate faults during the execution of a task.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.