Using Actions by Email Through an Email Template

1 Introduction
2 How to Use Actions By Email on Any Task
- 2.1 Create a Plugin
- 2.2 Create PHP File
- 2.3 Create the Email Template
- 2.4 Use the ‘Approved’ Variable to Route the Case

Introduction

IFS Workflow offers an Actions By Email event, where users can receive emails and send information to IFS Workflow cases and route those cases to the next task in the process. Out of the box, this feature has the following restrictions:

Actions by Email does not work with tasks that have self-service and self-service value based assignment routing rules, because these tasks need to be routed to a specific user in ProcessMaker.
The configuration of the Actions By Email feature must be done only from the second task of the process.
As a best practice, do not configure the current task to use Actions by Email, and then route cases of this task from the email to tasks that require manual assignment . This will cause errors in case run time because there is no way in the email to manually select a user in which to assign the task.
As a best practice, do not configure a task to use manual timing control if that task requires Action by Email. If you do so, process users cannot change the task duration time during run time.

How to Use Actions By Email on Any Task

Create a Plugin

First, a “dummy” plugin must be created to hold the php file that will be created later.

3.0 - 3.3 - Plugin Development

Create PHP File

The following PHP file will be used to send the response from the email back to the IFS Workflow case. The following sections will need to be replaced:

{server_name}
{workspace_name}
{password}

Response.php:

<?php
ini_set("soap.wsdl_cache_enabled", "0");
//ini_set('error_reporting', E_ALL); //uncomment to debug
//ini_set('display_errors', True);  //uncomment to debug
 
$client 
= new SoapClient('http://{server_name}/sys{workspace_name}/en/ifstheme/services/wsdl2');
$pass = 'md5:' . md5(‘{password}’);
$params = array(array('userid'=>'admin', 'password'=>$pass));
$result = $client->__SoapCall('login', $params);
 
if ($result->status_code == 0)
    $sessionId = $result->message;
else
    die("<html><body><pre> Unable to connect to ProcessMaker.\n" .
       "Error Message: $result->message </pre></body></html>");
 
class variableStruct {
   public $name;
   public $value;
}
 
$var = new variableStruct();
$var->name = "approved";
$var->value = $_GET['approved'];
 
$variables = array($var);
$params = 
array(array('sessionId'=>$sessionId, 'caseId'=>$_GET['case'], 'variables'=>$variables));
$result = $client->__SoapCall('sendVariables', $params);
if ($result->status_code != 0)
    die("<html><body><pre> Error: $result->message </pre></body></html>";

Now, navigate to the plugins public_html directory that is on the IFS Workflow server (default is /opt/plugins/{plugin_name}/{plugin_name}/public_html) and place the Response.php file there.

Make sure the file has the proper permissions and owner.

-rwxrwxrwx 1 apache apache 1120 Oct 18 14:40 response.php

The following commands were used to do this:

 chmod +777 response.php
 chown apache:apache response.php

Create the Email Template

To create a new email template, go to the designer screen of the specific workflow and click “Templates” in the Process Objects list. On the pop-up window, click the green “Create” button and name it. Then paste the following HTML code in the content section:

<html>
    <body>

      **Insert any text or HTML elements to be displayed in the email here**

        <p>Click to 
<a href="http://ddevwf2/sysworkflow/en/ifstheme/help/public_html/response.php?approved=true&case=@#APPLICATION">approve</a> or
<a href="http://ddevwf2/sysworkflow/en/ifstheme/help/public_html/response.php?approved=false&case=@#APPLICATION">disapprove</a> this action.</p>

    </body>
</html>

This will generate two clickable links in the email that looks like:

Click to approve or disapprove this action.

When the user clicks “approve” it will send the value of true to the variable specified in the link (in this case it is called approved). We also utilize the @#APPLICATION system variable to send the approved value to the proper case.

Use the ‘Approved’ Variable to Route the Case

The following gateway is used after the actions by email task:

The first gateway is a “converging” gateway and is required when multiple lines go into one gateway; no properties need to be set up here. The second gateway annotated with Approved? will be routing the case back or forwards depending on the status of the approved variable. The intermediate timer event is used to ‘wait’ for the user’s response from the email, if the variable has not been set (or is empty) then it will go to the timer event and check again after X amount of time. Once the user clicks the approved/disapproved link in the email, the value will be sent to the case variable and the case will be routed accordingly.