setting up email - pega

Setting Up Email

PegaRULES Process Commander Version 5.3

© Copyright 2007 Pegasystems Inc., Cambridge, MA

All rights reserved.

This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc.

This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described.

This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant.

For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders.

Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document or Help System could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time. This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA 02142-1590 Phone: (617) 374-9600 Fax: (617) 374-9620 www.pega.com PegaRULES Process Commander version 5.3 Document: Setting Up Email Updated: June, 2007

Contents

Setting up Email ............................................................................................................................. 5 Overview of Inbound Email .................................................................................................... 6

Service Package (EmailDefault) ...................................................................................... 6 Email Servers.................................................................................................................... 6 Email Listeners................................................................................................................. 6 Service Activity................................................................................................................. 7 Data Mapping.................................................................................................................... 7

Overview of Outbound Email ................................................................................................. 9 Email Accounts ................................................................................................................ 9 Correspondence Rules .................................................................................................... 9

Generating the Rules and Data Objects ...............................................................................11 Before You Begin ............................................................................................................11 Setting up Inbound Email ...............................................................................................12 Setting up Outbound Email ............................................................................................14 Editing the Results..........................................................................................................15

Testing the Setup ...................................................................................................................16 Testing Inbound Email....................................................................................................16 Testing Outbound Email .................................................................................................16

Overview of Inbound Email .................................................................................................... 6 Service Package (EmailDefault) ...................................................................................... 6 Email Servers.................................................................................................................... 6 Email Listeners................................................................................................................. 6 Service Activity................................................................................................................. 7 Data Mapping.................................................................................................................... 7

Overview of Outbound Email ................................................................................................. 9 Email Accounts ................................................................................................................ 9 Correspondence Rules .................................................................................................... 9

Generating Email Rules and Data Objects ...........................................................................11

iv Setting Up Email

Before You Begin ............................................................................................................11 Setting Up Inbound Email...............................................................................................12 Setting up Outbound Email ............................................................................................14 Editing the Results..........................................................................................................15

Testing the Setup ...................................................................................................................16 Testing Inbound Email....................................................................................................16 Testing Outbound Email .................................................................................................16

Setting Up Email Email messages are a key part of the business processes that developers build in their Process Commander applications. Flow processing typically sends email messages to work parties, including people outside your organization such as customers and vendors. Additionally, incoming e-mail messages can deliver work objects to your business processes.

Inbound email is processed by email services (Rule-Service-Email) while outbound email is processed by an email account object (Data-EmailAccount) and the PegaProCom agent. You use the Email Accelerator to create and configure the rules and data objects necessary for both inbound and outbound email.

This document describes the email features in Process Commander and how to use the Email Accelerator to set up email for your system.

6 Setting up Email — 0BSetting Up Email

Overview of Inbound Email Email services (Rule-Service-Email) manage inbound email. An email listener monitors an inbox on an email server and, when messages arrive, routes them to an email service rule. Typically, the service activity for the email service uses the information in the email message to create a work object. If there are any email attachments on the email message, the service activity can attach them to the work object.

To configure an email service, you use the Email Accelerator to set up the following rules and data objects:

■ The default service package named EmailDefault

■ An email service rule whose service activity creates work objects from the incoming message

■ An email server data object that represents a physical email server

■ An email listener data object that monitors an inbox on the email server and routes the messages to the email service

Service Package (EmailDefault) Unlike the other service rule types, email service rules have only one key and their names do not include a service package name (Data-Admin-ServicePackage). Instead, email service rules rely on a standard service package named EmailDefault.

All email services share the EmailDefault service package, which means that all email services use the same access group unless they run as authenticated users.

Email Servers Email server data instances (Data-Admin-Connect-EmailServer) represent a physical email server. Email listeners connect to the server represented by the data object and then route messages from the server to email service rules.

Email Listeners Email listeners (Data-Admin-Connect-EmailListener) provide Process Commander with the information it needs to route email messages from an email server to an email service rule. A listener object identifies the email server, the

0BSetting Up Email — 1BOverview of Inbound Email 7

name of the mail folder to monitor, the message format of the incoming messages, which email service rule to route messages to, and so on.

When the flow for the work object created from the email message routes assignments to "current operator," the service requestor must run as an authenticated user. In such a case, you specify a user ID and password that identifies a valid operator ID on the Email Listener form in the Accelerator. Or, after the Accelerator finishes, you can open the generated listener and enter these values on the Properties tab of the listener form.

When an email listener routes a message that has files attached to it, the listener creates a page named pyAttachmentPage (of class Data-ServiceMessage) and puts the file(s) on that page.

Like other types of listeners (file, MQ, and JMS), email listeners start when Process Commander starts. When you create new listeners, you can start them from the System Management application.

Service Activity By default, the Email Accelerator specifies a standard activity named createWorkProcess as the service activity of all the email services it generates. The createWorkProcess activity creates a work page, starting the specified flow, but it does not automatically manage email attachments.

If you want your email service to use the attached files from incoming email messages as work object attachments, see PRKB-24059 How to Configure an Email Service to Use an Email Attachment as a Work Object Attachment.

Data Mapping

As described in the Data Mapping chapter of Integrating with External Systems, data mapping defines the relationships between parameter-value pairs in external systems and property-value pairs on Process Commander clipboard pages. When you use the Email Accelerator to generate an email service, the Accelerator maps the request to a set of standard Work- properties and the response from a set of standard HTML rules.

Inbound Mapping ― Request (Map To) The Work- base class has a page property named pyInboundEmail. This page property is of the class Embed-Services-InboundEmailInfo, which has the following properties:

■ pyBody

■ pyCC


■ pyDate

■ pyFrom

■ pySubject

■ pyTo

Because your work classes inherit this property, you (or the Accelerator) can map email data directly to the clipboard without creating additional properties. When you use the Accelerator to generate email services, it configures the following inbound mappings:

■ The string from the To field is mapped to InboundEmailInfo.pyTo

■ The string from the From field is mapped to InboundEmailInfo.pyFrom

■ The message data is mapped to InboundEmailInfo.pyBody

Note: In versions of Process Commander prior to 5.3, the standard, single-value text property Work-.pyEmailBody supported the process of setting up inbound email through the email account data object. This property remains to support backward compatibility, but you should not use it with email services.

Outbound Mapping — Response (Map From)

When you use the Accelerator to generate email services, it configures data mappings on the Response tab to use the following standard HTML stream rules:

■ Work-.EmailSubject, which uses the text from the original email message: Re: {.pyInboundEmailInfo.pySubject}

■ Work-.EmailResponse, which is a simple thank-you message that provides the work object ID for the new work item (created by the service processing) and includes the message data from the original email.

You can edit the stream rules or change the outbound mapping as necessary.

When the service activity is finished with its processing, the email service sends the response configured on its Response tab through the email listener. If at a later point in the flow processing another email message is sent, that message is managed by an outbound email account and not by the email listener.

0BSetting Up Email — 2BOverview of Outbound Email 9

Overview of Outbound Email When configured correctly, the standard flow correspondence feature sends email messages generated by flow processing to operators and to work parties who are external to your organization. An email account (Data-EmailAccount) object holds information about the server and user account. An agent activity in the Pega-ProCom agent uses the information from the email account object to send outgoing e-mail and Short Message Service text messages.

Use the Email Accelerator to configure outbound email accounts.

Email Accounts Email account objects have two keys:

■ Name – by convention, use the name of the work object’s work pool (classgroup)

■ Type – by convention, specify the string “Notify”

The flow correspondence feature is implemented by a set of standard activities and rules. The activity Work-.getEmailSenderInfo looks for an e-mail account with a Name that matches the classgroup of the work object and the Type set to Notify. If the activity does not find a match, it uses the standard e-mail account named Default.Notify instead.

You should configure the standard e-mail account named Default.Notify so it is valid for your Process Commander system. That way the activity will always find an account. If different applications need to use different e-mail accounts, use the name of the application’s classgroup (work pool) as the name of the email account so the standard activities will find it. For example: HomeLoan.Notify.

Note: The form for an email account data object includes a tab named Incoming. In versions of Process Commander prior to 5.3, this tab was used to configure email accounts that managed incoming email. The Incoming tab remains on the form to support backward compatibility but you should use email services to manage incoming email.

Correspondence Rules The email messages generated during flow processing are created from email correspondence rules. These rules are instances of Rule-Obj-Corr that have their correspondence type set to Email.


You write standard messages in the correspondence rules and then standard notify and utility activities such as Work-.Notify and Work-.CorrNew and flow actions to call them at the appropriate places in your flows.

The PegaProCom agent checks for email correspondence to send every 30 seconds.

0BSetting Up Email — 3BGenerating Email Rules and Data Objects 11

Generating Email Rules and Data Objects This section describes how to use the Email Accelerator to set up email. You gather email account and other configuration information and then you run the Accelerator.

Before You Begin Before you begin, gather the following information.

For Inbound Email ■ For the rules that manage the work object creation:

– Name of the work class and the flow

– Organization name

– RuleSet and version to use

■ For the email server object and the listener:

– DNS name of the actual email server (an email server object represents a physical email server)

– Port number for the email server (typically 110 for POP3 and 143 for IMAP)

– Email protocol the server uses: POP3 or IMAP

– Account name and password for the email account for Process Commander

– Whether the email server requires the listener to use SSL to retrieve messages

– Name of the mail folder the listener monitors

– If the email service needs to run as an authenticated user, the name of the operator ID it should use

For Outbound Email ■ IP address or domain name of the SMTP host

■ Email account (e-mail address and password) that Process Commander is to use

■ Whether the SMTP host is configured to use SSL

■ Name of the work pool (class group) for which you are creating the account


Setting Up Inbound Email Complete the following steps:

1. From the Developer portal home page, select Integration.

2. From the Integration home page, under Accelerators, select Email Accelerator. Then, click New.

3. In the Enter Email Processing Information form, complete the fields as shown in Figure 1, and then click Next.

Field Value

Email Processing Type

Select Receive an email and create a work object.

Work Class Select the class of the work object to be created by this email service. The generated service rule will apply to this class.

Starting Flow Name Select the flow the service should use to create the work object. The list shows all the flows that apply to the work class or that the work class inherits.

Organization Name Flow processing requires that there be an organization associated with a work object. Use this field to specify the organization.

RuleSet Name Select the RuleSet for the generated service rule.

RuleSet Version Select the version of the RuleSet for the generated service rule.

Figure 1. Email Processing Information form for inbound email

4. In the Email Listener form, complete the fields as shown in Figure 2 and then click Next.

Field Value

Server Name Select or enter the name of an email server data object. If you enter the name of an email server that does not yet exist, the Accelerator displays the Email Server form next, so you can finish creating it.

Email Listener Name

Enter the name you want to use for the generated email listener.

Folder Name The name of the email folder the listener will monitor

Requestor User ID If the email service needs to run as an authenticated user, select the name of the operator ID it should use.

Password Enter the password for the operator you specified.


Field Value

Blocked When selected, this option disables the listener and it cannot be started. This option is selected by default so your generated listeners don’t start until you are ready for them to do so.

Figure 2. Email Listener form

5. In the Email Server form, complete the fields as shown in Figure 3 and then click Next.

Field Value

Host Name Enter the DNS name of the mail server.

Port Number Enter the TCP/IP port for the email server. Typically, port 110 for POP3 and port 143 for IMAP. The ports will be different if Process Commander is to use a secure port (SSL) to retrieve messages from this mail server.

Protocol Select the email protocol used to retrieve the messages, POP3 or IMAP

Email Address Specify the email address or username for the email account.

Password Specify the password to use for the email account.

SSL Indicate whether the mail server is using SSL.

Figure 3. Email Server form

6. In the Service Package form, specify the access group for the EmailAccount service package. All email services use the same service package, so the access group you specify must be correct for all email services.

7. In the Review form, examine the list of data objects and rules. To make changes, click the Back button. When you are satisfied with the list, click Next. The Accelerator generates the rules and data objects for the email service.

8. When the Generated Instances form appears, either click the Edit icons to examine the rules and objects or click Finish to exit the Accelerator.


Setting up Outbound Email Complete the following steps:

1. From the Developer portal home page, select Integration.

2. From the Integration home page, under Accelerators, select Email Accelerator. Then, click New.

3. In the Enter Email Processing Information form, complete the fields as shown in Figure 4. and then click Next.

Field Value

Email Processing Type

Select Configure outbound email.

Default Email Account

Select to configure the email account Default.Notify.

Workpool If you are not configuring the Default email account, select the work pool (class group) for which you are setting up this account.

Figure 4. Email Processing Information form for outbound email

4. In the Email Acount form, complete the fields as shown in Figure 5 and then click Next.

Field Value

Email address Enter the email address of the email account that Process Commander is to use.

Host (SMTP) Enter the IP address or domain name of the SMTP host.

Password Specify the password for the email account represented by the email address you entered.

Use SSL Specify whether Process Commander is to use SSL when sending email from this account.

Figure 5. Email Account form

5. In the Review form, verify your settings and then click Next. The Accelerator generates the email account.

6. When the Generated Instances form appears, either click the Edit icon to examine the generated email account object or click Finish to exit the Accelerator.


Editing the Results

The Email Accelerator automates much of the process of configuring email. However, because there are many way to configure email, you may need to edit at least some of the default settings. For example, for email services, you may need to configure additional data mappings for the subject or data of the incoming messages, or, you may want to use a service activity other than createWorkProcess.

When the Generated Instances form appears, open and examine the rules and data objects. Then make any necessary changes.


Testing the Setup When you are finished modifying the generated rules and data objects, test the configuration.

Testing Inbound Email

To test an email service rule, complete the following steps:

1. Open the listener and click Test Connectivity to ping the email server. If the listener cannot connect to the email server, determine the source of the problem — usually a typo in a configuration setting – and then try again.

2. Unblock the listener.

3. Use the System Management application, Tools > System Management Application, to start the listener.

4. Open the email service rule and use the Run Rule feature to run the service. Examine the Run Rule results to determine whether it ran correctly.

5. From the client application, send a request message to the inbox monitored by the email listener. Then check the inbox of the client application to determine whether the response message arrived and whether it contains the information you expected.

6. Check the inbox of the client application to determine whether the response message arrived and whether it contains the information you expected.

Testing Outbound Email

For each flow rule that generates email correspondence, run through the entire flow. Select Run > Process from the menu, or, use the Run Rule feature in the individual flow rules.

Run through the entire flow and then verify that notify and other email messages are delivered the way you expect them to be.

setting up email - pega

Documents