Sending Human Task Notifications via Email and SMS

EI Business Process can send email and SMS notifications to users when a human task notification occurs. This document provides instructions on enabling the email and SMS notification support for the human task notifications.

The BPEL specification defines human tasks for the business processes that need human interactions in order to make decisions. These human tasks can generate notifications to inform the users of the various decisions that need to be made. Certain users were able to view the notifications from their account. However, with the email and SMS notification support, users can configure EI Business Process to send messages to the specified email addresses and phone numbers when a notification is created.

Configuring email notifications

Follow the steps below to configure email notifications for human tasks.

Open the <EI_HOME>/wso2/business-process/conf/output-event-adapters.xml file.

Edit the following configurations under email <adapterConfig type> element according to your required settings.

 <adapterConfig type="email">
        <!-- Comment mail.smtp.user and mail.smtp.password properties to support connecting SMTP servers which use trust
        based authentication rather username/password authentication -->
        <property key="mail.smtp.from">bpsuser@gmail.com</property>
        <property key="mail.smtp.user">bpsuser</property>
        <property key="mail.smtp.password">bpsuserpassword</property>
        <property key="mail.smtp.host">smtp.gmail.com</property>
        <property key="mail.smtp.port">587</property>
        <property key="mail.smtp.starttls.enable">true</property>
        <property key="mail.smtp.auth">true</property>

        <!-- Thread Pool Related Properties -->
        <property key="minThread">8</property>
        <property key="maxThread">100</property>
        <property key="keepAliveTimeInMillis">20000</property>
        <property key="jobQueueSize">10000</property>
    </adapterConfig>

Note: The first three configuration parameters in the above XML code snippet must be modified to match your own parameter values.

Open the <EI_HOME>/wso2/business-process/conf/humantask.xml file.
Add the following configuration within the <HumanTaskServerConfig> tag.
```
<EnableEMailNotification>true</EnableEMailNotification>
```

To configure the email message, define the email message settings inside the .ht file. The .ht file can be found in the .zip file in <EI_HOME>/samples/business-process/humantask directory.

Tip: Use the rendering type “email”. This should be a child element of htd:notification.

$firstname$ is a UI parameter that will be replaced with values.

Add the following configurations.

<htd:renderings>
	<htd:rendering type="wso2:email">
		<wso2:to name="to" type="xsd:string">bpsuser@gmail.com</wso2:to>
		<wso2:subject name="subject" type="xsd:string">Email Subject</wso2:subject>
		<wso2:body name="body" type="xsd:string">Hello $firstname$ $lastname$!</wso2:body>
          <!-- Supported Content Types text/plain, text/html -->
        <wso2:contentType name="contentType" type="xsd:string">text/html</wso2:contentType>
	</htd:rendering>
</htd:renderings>

The following are the common tags used to define rendering.

Tag name	Description
htd:renderings	This is a main tag that includes different kinds of rendering sub tags that must be configured for notifications.
htd:rendering	This defines which kind of a rendering should be performed for the parameters inside this tag. You can use the type of attribute for defining the rendering type. In this case we use email.

The following are tags specific to email rendering.

Tag name	Description
htd:to	This tag is where you define the destination email address of the notification.
htd:subject	This tag contains the subject line of the email that must be sent when the notification is created.
htd:body	This tag contains the body of the email that must be sent when the notification is created. The body can consist a user specified format, e.g., "Hello $lastname$, $firstname$".

Make sure following namespace is included at the top of the .ht file.
```
xmlns:wso2="http://wso2.org/ht/schema/renderings/"
```
Save your changes.

Configuring SMS notifications

Do the following steps to configure SMS notifications for human tasks.

Open the <EI_HOME>/wso2/business-process/conf/axis2/axis2-client.xml file.

Add the following configuration in the file.

<transportSender class="org.apache.axis2.transport.sms.SMSSender" name="sms">
        <parameter name="systemType"></parameter>
        <parameter name="systemId">bps1</parameter>
        <parameter name="password">bps123</parameter>
        <parameter name="host">localhost</parameter>
        <parameter name="port">2775</parameter>
        <parameter name="phoneNumber">BPS1</parameter>
</transportSender>

Note: The first four configuration parameters in the above XML code snippet must be modified to match your own parameter values. The systemId and password parameters are provided by the SMS center or simulator that you use.

Add the following .jar files to the <EI_HOME>/lib directory.
- jsmpp-2.1.0.jar
- axis2-transport-sms-1.0.0.jar
Open the <EI_HOME>/wso2/business-process/conf/humantask.xml file.
Add the following configuration within the <HumanTaskServerConfig> tag. Set this value to false if you want to turn these notifications off.
```
<EnableSMSNotification>true</EnableSMSNotification>
```

To configure the SMS message, define the SMS message settings inside the .ht file. The .ht file can be found in the .zip file in <EI_HOME>/samples/business-process/humantask directory.

Tip: Use the rendering type “SMS”. This should be a child element of htd:notification.

$firstname$ is a UI parameter that will be replaced with values.

Add the following configurations.

<htd:renderings>
	<htd:rendering type="wso2:sms">
		<wso2:receiver name="receiver" type="xsd:string">94777123456</wso2:receiver>
		<wso2:body name="body" type="xsd:string">Hi $firstname$</wso2:body>
	</htd:rendering>
</htd:renderings>

The following are the common tags used to define rendering.

Tag name	Description
htd:renderings	This is a main tag that includes different kinds of rendering sub tags that must be configured for notifications.
htd:rendering	This defines which kind of a rendering should be performed for the parameters inside this tag. You can use the type of attribute for defining the rendering type. In this case we use sms.

The following are tags specific to SMS rendering.

Tag name	Description
htd:receiver	This tag is where you define the number of the notification's receiver.
htd:body	This tag contains the content of the SMS that must be sent when the notification is created. The body can consist a user specified format, e.g., "Hello $lastname$, $firstname$".

Make sure following namespace is included at the top of the .ht file.
```
xmlns:wso2="http://wso2.org/ht/schema/renderings/"
```
Save your changes.

Customizing notifications

The notifications can be customized further using parameter. Variable values can be added to the htd:body tag (for both email and SMS notifications) using a $ sign or XPath. For example, a value in a presentation parameter can be added to the message body in the format ${parameter name}$ . Those variables are evaluated and replaced with relevant presentation parameters.

Another way of adding a variable value to the body is by using an XPath expression. These XPath expressions are evaluated and the values of these expressions are added to the body instead of the expressions. Note that when the XPath expressions are used, they should be separated by spaces.

Configuring an SMS simulator

You can configure an SMS simulator to try out the SMS notifications. In this example, we use the Logica SMS simulator.

Following are the configurations required to set up Logica SMS Simulator.

Download Logica SMS Simulator as a .zip file.
Unzip the folder and open the user.txt file.
Add following configurations to it. Here you must use the values you specified for systemId and password in step 2 of the Configuring SMS notifications section of this topic.
- name=bps1
- password=bps123
- timeout=unlimited
  
  Tip: Make sure there are no spaces between name value pairs, as spaces will not be removed. For instance, name= bps1 and name=bps1 will be considered as two users.
Save the file and run the start.sh script from the terminal.
Select option 1 to start the simulator. When the simulator requests the port number, provide the port value you configured in step 2 of the Configuring SMS notifications section of this topic.