Enabling email for Process Portal notifications

Process Portal users can set their preferences to receive an email notification when a new task is assigned to them. The configuration works for all types of email. To use this capability, you must enable the email environment to send notifications.

Before you begin

Verify that the following components are stopped:

Process Center server
Process Server

If Process Portal users are using email with an IBM® Lotus Domino V9 server, they can complete Process Portal tasks directly from their email notifications. To make sure that the integration is set up correctly, complete the following prerequisite tasks:

Configure single sign-on (SSO) with an LTPA token on IBM WebSphere Application Server and IBM Lotus Domino. See the IBM Lotus Domino documentation at Configuring single sign-on with an LTPA token on IBM WebSphere and IBM Lotus Domino platforms.

Make sure that the IBM Lotus Domino server is set up properly by following the steps in the IBM Lotus Domino documentation:

Create an XML file that you import into IBM Lotus Domino as described in

Using widgets in iNotes.

Customize the following example:

<?xml version="1.0" encoding="UTF-8"?>
<webcontextConfiguration version="1.1">
  <palleteItem contributeTabOnStartup="false" contributeToSideshelfOnStartup="false" description="Embedded Experience OpenSocial gadget used to display Coach" hideThumbnail="false" id="1074909581" imageUrl="" providerId="com.ibm.rcp.toolbox.opensocial.provider.internal.OpenSocialPalleteProvider" singletonSidebar="false" title="BPM Coach EE" url="http://bpm80.swg.usma.ibm.com:9080/ProcessPortal/gadgets/OpenSocial/BPMOpenSocialGadget.xml" viewImageUrl="">
<preferences/>    
<data>
      <object-capabilities url="http://[hostname]:[WC_defaulthost port]/ProcessPortal/gadgets/OpenSocial/BPMOpenSocialGadget.xml">
        <grant-feature id="opensocial-data"/>
        <grant-feature id="opensocial-templates"/>
        <grant-feature id="opensocial-1.0"/>
        <grant-feature id="dynamic-height"/>
        <grant-feature id="embedded-experiences"/>
        <grant-feature id="open-views"/>
        <grant-feature id="settitle"/>
        <grant-feature id="osapi"/>
        <grant-feature id="content-rewrite"/>
        <grant-feature id="embedded-experiences-render"/>
        <grant-feature id="core"/>
      </object-capabilities>
    </data>
  </palleteItem>
</webcontextConfiguration>

Set up Domino Web SSO authentication between the iNotes server and IM server Part of overall topic for setting up iNotes and IM.
Configure the component as described in Configuring Domino Social Edition Open Social component for iNotes clients.
Complete the configuration as described in Widgets created from an OpenSocial gadget.
Set up SSO in IBM Lotus Notes.
1. Create an account as described in Creating and editing accounts from Notes preferences.
2. Publish the account for all users as described in the Using administrative accounts to manage client plug-ins document in the IBM Domino 9.0 Social Edition Administrator Help.

Adding the email server to the trusted servers list prevents problems with sizing in Process Portal. See Adding servers to the trusted server list.
The email facility (used for task notification, task assignment, and so on) must be configured to use a local SMTP server that is listening on the default port (25) and does not require authentication. This local SMTP server can then be used to forward emails to any other external SMTP that requires authentication.
If you are using IBM BPM V8.5.0.0, complete the following additional tasks:
- Make sure that SSO is configured with the same domain in both IBM Business Process Manager and IBM Lotus Domino. The IBM BPM domain that is specified in the 99Local.xml file must match your IBM Lotus Domino server. If the domain does not match, you must edit the 100Custom.xml file. Update the domain in the <gadget-link> tab that is in the <email> element; for example, <gadget-link>http://bpm80.swg.usma.ibm.com:9080/ProcessPortal/gadgets/OpenSocial/BPMOpenSocialGadget.xml</gadget>. Edit the files according to the following procedure.
- Using the same security protocol for both the IBM BPM server and the email server prevents an issue where Process Portal users see a blank task completion view in email. For example, use HTTPS for both the IBM BPM server and the email server, or use HTTP for both the IBM BPM server and the email server. If your environment uses HTTPS for one of the servers, and HTTP for the other server, you must copy the IBM BPM server URLs from the 99Local.xml file under the <email> section and paste them into the 100Custom.xml file. Then edit the URLs so that the SSL protocol matches your email server. For editing the 100Custom.xml file, follow the instructions in The 99Local.xml and 100Custom.xml configuration files.

About this task

The entries in the email properties section in the 99Local.xml configuration file define the properties for your email environment. Make all required modifications to the 100Custom.xml file.

Important: Do not edit the 99Local.xml file.

Procedure

If you are using IBM BPM V8.5.0.1, complete the following steps to configure email notifications:
1. Open the 99Local.xml file and locate the email properties section.
2. Open the 100Custom.xml file and copy and paste the email properties section into the 100Custom.xml file.
3. In the <email> element, insert the values that are appropriate for your environment.
  - <smtp-server> element - Ensure that the value of this element is a valid SMTP server.
  - <default-from-address> element - Ensure that the value of this element is a valid email address.
  The following example shows the values that you set for the <email> element in the 100Custom.xml file.
```
<server merge="mergeChildren">
	<email merge="mergeChildren">
		
		<smtp-server merge="replace">smtp.example.com</smtp-server>
		<valid-from-required merge="replace">true</valid-from-required>
		<default-from-address merge="replace">username@example.com</default-from-address>
		<send-external-email merge="replace">true</send-external-email>
	</email>
</server>
```
4. Save your changes.
5. Optional: If you want to force URLs that are included in emails to go through a network router, see the following scenario keys in Configuring IBM BPM endpoints to match your topology.
  - SERVER_EMAIL_GADGET_LINK
  - SERVER_EMAIL_PORTAL_LINK
  - SERVER_EMAIL_PORTAL_PROCESS_INFO_LINK
  - SERVER_EMAIL_PORTAL_RUN_TASK_LINK
  - SERVER_EMAIL_TEMPLATE_CLIENT_LINK
6. Restart the cluster.
If you are using IBM BPM V8.5.0.0, complete the following steps to enable email notifications:
1. Open the 99Local.xml file and locate the email properties section.
2. Open the 100Custom.xml file and copy and paste the email properties section into the 100Custom.xml file.
3. In the <email> element, insert the values that are appropriate for your environment.
  - <smtp-server> element - Ensure that the value of this element is a valid SMTP server.
  - <default-from-address> element - Ensure that the value of this element is a valid email address.
4. If you need to change the URL for your Process Portal Server, modify the BPMVirtualHostInfo configuration object as described in Security configuration properties.
  Tip: You might change the BPMVirtualHostInfo configuration object if you need to be sure that a fully qualified host name is used for the BPM server, if you need to change the default transport protocol setting to use HTTPS instead of HTTP, or if you are working with an IBM Lotus Domino server that is on a different domain than your Process Portal server.
  
  The following example shows how you might modify the BPMVirtualHostInfo configuration object using the previously described instructions:
```
INSTALL_HOME\bin>wsadmin -conntype NONE -lang jython 
wsadmin>print AdminConfig.showall(AdminConfig.list('BPMVirtualHostInfo'))
 [port -1]
 [transportProtocol https]
wsadmin>AdminConfig.modify(AdminConfig.list('BPMVirtualHostInfo'),[['port','9443']])
wsadmin>AdminConfig.modify(AdminConfig.list('BPMVirtualHostInfo'),[['hostname','myhostname.ibm.com']])
wsadmin>AdminConfig.modify(AdminConfig.list('BPMVirtualHostInfo'),[['transportProtocol','https']])
wsadmin>print AdminConfig.showall(AdminConfig.list('BPMVirtualHostInfo'))
 [hostname myhostname.ibm.com]
 [port 9443]
 [transportProtocol https]
wsadmin>AdminConfig.save()
```
5. Restart the cluster.

If the email gadget fails to render in the Notes Client or iNotes, verify the following items:

Single sign-on (SSO) has been configured properly between the IBM Lotus Domino server and the BPM server.
Check the IBM Lotus Domino server error logs. The IBM Lotus Domino server logs can be found in the Domino_root/data/domino/workspace/logs directory. If you see an error similar to the following error, you must import the BPM certificate into the IBM Lotus Domino server:
- Certificate, OU=Cellname, OU=Dmgr, O=IBM, C=US, is not trusted. Validation failed with error 3659.
To import the certificate into the IBM Lotus Domino server, you must complete the following tasks:
1. Import an Internet certifier into the Domino Directory.
2. Create an Internet cross-certificate in the Domino Directory from a certifier document.

What to do next

So that process participants receive email notifications, ask them to update their user preferences as described in Setting preferences in Process Portal.