IBM Support

What you need to know about configuring Process Portal email notification

Technical Blog Post


What you need to know about configuring Process Portal email notification



Here is a sample of an IBM Business Process Manager (BPM) Process Portal email notification.


In order to get an email notification as above whenever a new task is assigned to you or your team in IBM BPM Process Portal, you need to complete the steps below.

1. Configure email elements in BPM configuration files

1) Update email properties section into the 100Custom.xml file.

The following example (on IBM BPM V8.5.7) shows the values that you set for the <email> element in the 100Custom.xml file.

<server merge="mergeChildren">

                       <email merge="mergeChildren">

                                              <!-- SMTP server that mail should be sent to -->

                                              <smtp-server merge="replace"></smtp-server>




                                              <valid-from-required merge="replace">true</valid-from-required>

                                              <default-from-address merge="replace"></default-from-address>

                                              <send-external-email merge="replace">true</send-external-email>




  1. <default-from-address> element - Ensure that the value of this element is a valid email address.
  2. <use-gadget> element - The gadget renders the task completion URL within an email. Ensure that the value of this element is set to true.
  3. <send-external-email> element - If you want notification email to be sent to an external email addresses, change the value to true.

2) Save your changes and restart the BPM servers.

2. Enable email notification for specific user in Process Portal and ensure the email address is valid.


3. Configure endpoint in the email for specific scenario

  1. By default, there are three links in the notification email. Here are the sample URLs.

Run task:


Run task in process portal


Process Information



  1. If the receiver of the notification email clicks the URL, and then the request needs to pass through a web server or load-balancing server before reaching BPM server, or you have any specific requirement on the prefix of the URL, you must configure the endpoint which is used to generate the above URLs.
  2. Here are the specific scenarios for notification email. If you don’t set endpoint for these specific scenarios, it will adopt the setting for EXTERNAL_CLIENT scenario by default.






  1. For the above scenarios, you can define a list of strategies for each endpoint. During runtime, the server will try the strategies in order until one returns the required information. Each strategy uses a different approach to determine the transport protocol, host, and port that are used to generate URLs. There are many different strategies, you can refer to this table "Strategies for identifying endpoint information" for the list and definitions.

You need to pay attention to XForwardedHeaderStrategy, which uses "X-Forwarded-Host" and "X-Forwarded-Protocol" from http request to construct URL. But in the scenario for portal notification email, there is no http request to be used. Then it will read virtualhost property of BPMURL object, if still null, read defautlVH property defined on deploymentEnvironments object, if still null, read virtual host info of the current BPM server.


Example (copied from configuration file cell_bpm.xml):

<virtualHosts xmi:id="BPMVirtualHostInfo_1421293214461" hostname="" port="443" name="test_vh"/>

     <bpmurls xmi:id="BPMURLS_1420423349493">

<bpmurl xmi:id="BPMURL_1420423349494" strategies="," scenario="EXTERNAL_CLIENT" virtualHost="BPMVirtualHostInfo_1421293214461"/>

  1. Most users select the WCCMConfigStrategy(virtual host) strategy, or set a fixed URL for the notification email scenario. Here are the sample codes for the configuration change.

For BPM V8.5.7

wsadmin.bat -conntype NONE -lang jython


  1. Virtual Host:

AdminTask.setBPMVirtualHost( ['-de', ‘JTDE’, '-name', 'JT_vh', '-transportProtocol', 'https', '-hostname', '', '-port', '443' ] )

AdminTask.setBPMEndpoint( [ '-de', ‘JTDE’, '-scenario', scenario, '-virtualHost', 'JT_vh' ] )

  1. Fixed URL:

AdminTask.setBPMEndpoint( [ '-de', ‘JTDE’, '-scenario', scenario, '-url', '; ] )

  1. Dynamic Strategies:

AdminTask.setBPMEndpoint( [ '-de', ‘JTDE’, '-scenario', scenario, '-strategies', 'WebsphereProxyHeaderStrategy, XForwardedHeaderStrategy, HttpProtocolHostStrategy' ] )


For BPM V8.5.6

wsadmin.bat -conntype NONE -lang jython




print de

  1. Check whether BPMURL object for this scenario exists



bpmurllist=AdminUtilities.convertToList(AdminConfig.list("BPMURL", bpmurlsid))


for item in bpmurllist :

  if AdminConfig.showAttribute(item,'scenario')==scenario : bpmurl=item

print bpmurl

  1. Create one new BPMURL object for this scenario if the above result is none

i. Virtual host

             JT_vh = AdminTask.setBPMVirtualHost( ['-de', ‘JTDE’, '-name', 'JT_vh', '-transportProtocol', 'https', '-hostname', '', '-port', '443' ] )

bpmurl=AdminConfig.create('BPMURL',bpmurlsid,[['scenario',scenario],['virtualHost',JT_vh], ['strategies','WCCMConfigStrategy']])

ii. Fixed URL


iii. Dynamic stratergy

bpmurl=AdminConfig.create('BPMURL',bpmurlsid,[['scenario',scenario],['strategies', ‘XForwardedHeaderStrategy, HttpProtocolHostStrategy']])        

  1. Modify existing BPMURL object for this scenario if it exists

i. Virtual host

JT_vh = AdminTask.setBPMVirtualHost( ['-de', ‘JTDE’, '-name', 'JT_vh', '-transportProtocol', 'https', '-hostname', '', '-port', '443' ] )


ii. Fixed URL


iii. Dynamic stratergy

AdminConfig.modify(bpmurl,[['strategies','XForwardedHeaderStrategy, HttpProtocolHostStrategy']])


  1. Sometimes, you may want to add more links to the notification email, or remove/replace some existing ones. In that case, you can consider customizing the mail template.

The default mail template name could be found in 99local.xml. {0} will be replaced based on the locale.




And the template files could be found in <BPM_HOME>/BPM/Lombardi/process-server/lib/procsrv_resources.jar. The below part is the definition of the “Run Task” URLs.

<td style="background:white" class="button">

<a href="{1}/process.lsw?zWorkflowState=1&zTaskId={2}">(Run task &gt;&gt;)</a>


<a href="{5}/dashboards/TWP/BPM_WORK?tw.local.view=taskcompletion&tw.local.taskid={2}">(Run task in Process Portal &gt;&gt;)</a>


<a href="{5}/launchInstanceUI?instanceId={6}">(Process information  &gt;&gt;)</a>


[{"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"Product":{"code":"","label":""},"Component":"","Platform":[{"code":"","label":""}],"Version":"","Edition":""}]