Configuring the Email Channel

This chapter provides an overview of the email channel and discusses how to:

Configure PeopleSoft Integration Broker for the email channel.
Demonstrate the email channel.

Understanding the Email Channel

Because the email channel uses a PeopleSoft Integration Broker gateway, the email channel requires additional configuration outside of PeopleSoft MultiChannel Framework configuration pages.

PeopleSoft MultiChannel Framework (MCF) provides a framework for:

Fetching emails from a mail server.
Storing and retrieving email parts in a database.
Managing attachments.
Queueing of emails by the queue server.

Application developers use the PeopleCode application package PT_MCF_MAIL to develop PeopleSoft Application Engine programs and PeopleSoft Pure Internet Architecture components for email processing.

See Mail Classes.

PeopleSoft MultiChannel Framework email channel features include:

The GETMAILTARGET target connector.
A PeopleCode application package, PT_MCF_MAIL, to retrieve, store, and delete email.
Support for both Post Office Protocol 3 (POP3) and Internet Message Access Protocol 4 (IMAP4) email protocols.
Support for email attachments, including:
- An attachments repository running on the same web server as PeopleSoft Integration Broker.
- URL access to email attachments.
- A relative addressing scheme to enable flexibility of repository location.
- User- and role-based security to control access to attachments.
The option to access email headers, attachments, and body from the mail server.
Support for multiple message size thresholds to control distribution of email between the database, the attachment repository, and the mail server.
Support for UTF8 Unicode as supported by the Sun Java Runtime Environment (JRE) 1.3.1 or later.

See http://java.sun.com.
Time zone conversions to support global service-level agreements.
Sample email application pages demonstrating the functionality of the PT_MCF_MAIL application package.

Handling Email

This section describes some factors to consider when handling email using PeopleSoft MultiChannel Framework.

POP3 Versus IMAP4

Most mail servers support simultaneous client connections through both POP3 and IMAP4. Using IMAP4 for your MCF email connection provides significant benefit over using POP3. IMAP4 allows for the use of email folders, which allows malformed emails to be set aside for separate processing. Quarantining malformed emails allows system administrators to remove or correct invalid emails without interrupting normal processing.

Note. Using IMAP4 for your MCF email connection does not preclude the use of POP3 for any other client connections to your mail server.

Time Zone Offsets

Set the values of the email sent time zone offset (in minutes) and the receive time zone offset (in minutes) whenever possible. The default value is 800, which indicates time zone information is not available. When available, the values range from +720 to −720.

Connector Determination of Email Size

The connector sometimes cannot determine the size of the message. In such cases the size is set to 0 and an error message is written to the gateway error log.

Malformed Emails

Emails with syntax that does not comply to the latest standard definitions may not be processed successfully by MCF. MCF will return as much as possible of non-compliant emails, however, at times, invalid parts will be ignored. For example, email addresses with invalid characters will not be displayed, such as two @ symbols. Also, if the header information is not valid, such as a malformed content-type, the associated email part may not be displayed.

A relatively common example of a malformed email is one in which there is 8-bit encoded information in a header, such as the To, Cc or Subject field, or in an attachment file name. According to the standard definitions, this information must be encoded using a 7-bit encoding, as described in RFC 2045 and others. This encoding is usually done by the email sender.

Note. PeopleSoft's email reader only supports email messages that follow the SMTP specification. Many email clients and mail servers have their own proprietary formats, please be aware that PeopleSoft MCF will only interpret these emails according to the RFC specification. For example, some mail servers and clients allow 8-bit encoded data in email headers. PeopleSoft’s email reader does not allow this, however, as it does not comply with the specification.

Configuring PeopleSoft Integration Broker for the Email Channel

This section discusses how to:

Configure the gateway.
Configure GETMAILTARGET properties.

Configure nodes and gateways for the email channel in PeopleSoft Integration Broker.

Pages Used to Configure Integration Broker for Email

Page Name	Object Name	Navigation	Usage
Node Info	IB_NODE	PeopleTools, Integration Broker, Node Definitions, Node Info	Define the MCF_GetMail node.
Connectors	IB_NODECONN	PeopleTools, Integration Broker, Node Definitions, Connectors	Define the MCF_GetMail connector.
Gateways	IB_GATEWAY	PeopleTools, Integration Broker, Gateways, Gateway ID	Set up the PeopleSoft Integration Broker gateway for the MCF_GetMail connector node.

Configuring the Gateway

Access the Gateways page.

Create a local gateway.
Enter the gateway URL in the form http://<gatewayservername>/PSIGW/PeopleSoftListeningConnector, where <gatewayservername> is the fully qualified host name for the gateway machine.

For example, http://host1.peoplesoft.com/PSIGW/PeopleSoftListeningConnector.
Save the page.
Click Load Gateway Connectors.

The connector properties appear.
Save the page again.
Configure the GETMAILTARGET connector properties.

Configuring GETMAILTARGET Properties

Access the Connector Properties page.

Configure GETMAILTARGET connector properties on the MCF_GETMAIL node. You can also set threshold values for email routed to the attachment repository.

The following table lists node properties:

Property Name	Default Value	Description
MCF_AttRoot	c:\temp\att	Defines the location of the attachment repository on the gateway. For example, if the attachment root is c:\temp\att, then attachments for emails addressed to user name support are downloaded to c:\temp\att\<mail server host name>\<mailbox>. Note. The directory on the remote machine where the attachments are stored should be shared. The user permissions for should be stored on the node (local node) that will retrieve the attachments. Note. The user name or mailbox portion of the attachment root path may include encoded characters. All email attachments, and email parts not of the content types specified for the MCF_ContentTypes property, are always written to the attachment repository. A relative URL is returned to the application that allows the application to access the attachment. The attachment retrieval depends on the file system of the operating system. For Windows NTFS/FAT 16 file system, the folder length or maximum characters of the file extension is 256/512. For Unix and Solaris UFS file system, the length is 256. Attachment security is managed at a user and role level using the PT_MCF_EMAIL application package. Users can configure attachment folder paths using metastrings to enable multiple folders based on several variables: %OPRID%: PeopleSoft user ID. %DBNAME%: database name. %CURRDATE%: current date. %CURRHOUR%: current hour.
MCF_AttServ	http://<machine_name>.<domain_name>/PSAttachServlet/ps/	Defines the location of the MCF attachment repository servlet, located on the gateway web server. Attachment relative URLs are appended to this address to create a fully qualified URL to reference an attachment in the repository. Note. When you are setting a remote gateway to access email attachments stored on the remote machine, the database that the gateway/psattachservlet accesses should have the permissions to view the attachments. Note. If your web server is installed with a PeopleSoft Pure Internet Architecture site name other than ps, include the site name in the specified path.
MCF_ContentTypes	text/plain	Specifies email content types that will be stored in the database. Content types not specified will be stored as attachments. Enter content types separated by commas. For example, you can Enter text/html and text/xml to enable storage in the database of HTML email and email containing XML. The content type text/plain is always stored in the database, regardless of values specified for MCF_ContentTypes. Do not include binary encoded content types in the content types list unless the application can handle base64 encoded text.
MCF_Count	0	Defines the default number of emails retrieved from the mail server unless otherwise specified in the SyncRequest. The PeopleSoft MultiChannel Framework email application package always specifies the number of emails to be retrieved and does not reference this property.
MCF_EmSz_Conn	4000000	Defines the connector threshold, in bytes. This parameter ensures that emails retrieved from a POP3 mail server do not exceed the available memory on the gateway server. Email content retrieved from IMAP4 servers can be streamed to a file on the attachment repository, but content retrieved from POP3 servers must first be read into memory before being written to a file. Therefore, the MCF_EmSz_Conn threshold can be set very high for IMAP4 mail servers. PeopleSoft MultiChannel Framework does not process an email if its size is greater than this value. The status returned to the application is 1. The triggering email is neither downloaded nor deleted from the mail server. Only the email header is returned to the application. See Mail Classes.
MCF_EmSz_IB	500000	Defines the PeopleSoft Integration Broker threshold, in bytes. This is the maximum size message that the GETMAILTARGET connector can send through PeopleSoft Integration Broker. The purpose of this threshold is to ensure that retrieved emails do not exceed the available memory on the gateway server and that the server running the application that requested the emails. A PeopleSoft Integration Broker message can contain one or more emails, depending on the number of emails the application retrieves per message. As soon as this threshold is reached, the remainder of the triggering email is written to the repository, and no more emails are retrieved. Emails fetched prior to the triggering email are returned normally. The triggering email is returned with a return status of 2, indicating that some of its parts were written to the repository. See Mail Classes.
MCF_EmSz_Part	30000	Defines the text part threshold, in bytes. If any text part of an email exceeds this value , the part is routed to the attachment repository. This ensures that excessively large objects of text are not written to the database. For databases with limitations on the maximum size of rows or long text field lengths, this value must be lower than that limit to avoid SQL errors when saving emails.
MCF_Email_Lang_CD	ENG	Defines the expected language of emails downloaded by this node. This code is included in the email header returned to the application. Configure a node for each language you expect to handle, because Simple Mail Transfer Protocol (SMTP) mail servers and clients do not guarantee correct identification of the email's language when creating an email.
MCF_MethodName	MessageCount	Defines the methods associated with the application class package. The defined method is the default method used unless otherwise specified in the SyncRequest. The email application package always specifies the method to be used and does not reference this property. See Mail Classes.
MCF_Password	None	Defines the default password for the mailbox unless otherwise specified in the SyncRequest. See Mail Classes.
MCF_Port	143	Defines the mail server port to be used. By default, POP3 servers use port 110 and IMAP4 servers use port 143. Confirm the port number with your system administrator and set it accordingly here.
MCF_Protocol	IMAP4	Defines the protocol used by the connector to access emails on the mail server. Supported values are POP3 or IMAP4.
MCF_Quarantine	Quarantine	Defines a quarantine folder for email meeting the following criteria: Connector size overflow. Unsupported encoding. Unknown Java exception. JavaMail content error. No attachment repository. Mail parse exception. The quarantine folder is created for each user account and must be managed by each email user, not by system administrators. Note. Folders are supported only on IMAP4 mail servers.
MCF_Server	None	Defines the fully qualified host name of the mail server. This is the default fully qualified host name of the mail server, unless otherwise specified in the SyncRequest. For example, bigserver.peoplesoft.com. See Mail Classes.
MCF_User	None	Defines the user name for the email account (mailbox) being accessed. This is the default user name used unless otherwise specified in the SyncRequest. For example, if emails are addressed to [email protected], the user name is support.
MCF_Force_Download_Attachments	False	Enables downloading attachments that might otherwise be interpreted as text. If set to True all attachments, including text/plain, irrespective of their size, are downloaded to the attachment repository. This property enables reading of non-ASCII attachments.

Note. The POP3 and IMAP4 email protocols calculate message size differently. POP3 does not include header size, but IMAP4 does. As a result, message sizes affecting thresholds behave differently depending on the protocol used.

Multipurpose Internet Mail Extensions (MIME), is an Internet standard for representing multipart and multimedia data in email so that they can be exchanged between different email systems. The parts may be nested. PeopleSoft embeds the Sun JavaMail API to implement support for the MIME standard. However, all parts of an email are represented in PeopleSoft as level 1 rowsets, regardless of whatever hierarchy existed in the original email. Email clients determine the MIME format of the emails sent from them, so identical email content sent from different email clients may have a different MIME structures.

Demonstrating the Email Channel

To demonstrate the email channel, use the Email Sample Pages (MCFEM_DEMOERMS_CMP) component.

This section discusses how to:

Use the GetMail - Server page.
Use the MailStore - DB page.

The PeopleSoft system provides email sample pages to demonstrate the functionality of the PT_MCF_MAIL application package.

Note. The email sample pages are not intended for any purpose other than demonstration and troubleshooting. They should not be used in production.

The email sample pages can be also used to test the configuration of your integration gateway and MCF_GETMAIL node.

Note. Using the email sample pages requires access to a mail server.

Pages Used to Demonstrate the Email Channel

Page Name	Object Name	Navigation	Usage
GetMail - Server	MCFGETMAIL_PG	PeopleTools, MultiChannel Framework, Email, Sample Pages, GetMail - Server	Demonstrate GetMail functionality.
MailStore - DB	MCFMAILSTORE_PG	PeopleTools, MultiChannel Framework, Email, Samples Pages, MailStore - DB	Demonstrate MailStore functionality.

Using the GetMail - Server Page

Access the GetMail - Server page.

This page demonstrates reading or deleting emails from the mail server. It also demonstrates the storage and retrieval of emails to and from the database tables. Output of the response to each of the requests is written to a file at %PS_SERVDIR%/files/mcfdata.out on the application server. Check this file after each test for the output data.

To demonstrate email functionality, send an email to the user name and server that you enter on the GetMail - Server page.

Username and Password	Enter a valid username and password for an account on the mail server.
Server	Enter the mail server.
IB Nodename (integration broker node name)	Enter the PeopleSoft Integration Broker node used to access email from the mail server. The default is MCF_GETMAIL
Use Rowset API	Select to use the rowset-based GetMail API. Deselect to use the new Mail Classes API.

Read Headers

Select a method to be called from the drop-down list box, then click Fetch. Select from:

Message Count:	Writes the number of emails in the specified mailbox to the output file mcfdata.out.
ReadHeadersWithAttach:	Writes headers and attachment information for all emails in the specified mailbox to the output file mcfdata.out.

Read Emails

Enter the number of emails to read, select other parameters, then click Fetch to read emails.

Emails to Read	Enter the number of emails to retrieve from the specified mailbox and write to the output file mcfdata.out.
Write to Database	Select to have the retrieved emails written to the database as well as to the output file mcfdata.out.
Remove from Mail Server	Select to delete emails from the mail server after they have been retrieved .

Access an Email

Enter an email UID list, select a method from the drop-down list box, then click Fetch to access the selected emails.

UID List (unique identifier list)

Enter the unique ID of an email to be retrieved or deleted. To delete, you can enter a comma-delimited list of unique email IDs (UID) to be deleted.

Each email has a unique number (the UID) associated with it that is permanently guaranteed not to refer to any other email in the mailbox. To find the UID of an email, run the ReadHeadersWith Attach option first, which returns the UID for each email. If an invalid UID is specified, one empty row is returned.

Read Email w/ attachment

Retrieves the specified email from the specified mailbox and writes it to the output file mcfdata.out.

Remove Message

Deletes the specified email from the specified mailbox.

Create IMAP Folder

Create an email folder; only valid for IMAP4 mail servers.

Folder Name

Enter the name of the folder to create.

Using the MailStore - DB Page

Access the MailStore - DB page.

View an example of how to access emails from the database (how to retrieve and delete email) and how to authorize email attachments for viewing or deletion using the PT_MCF_MAIL application package provided with PeopleSoft MultiChannel Framework.

Email ID

Enter the PeopleSoft email ID (not to be confused with the UID) with which the email was saved to the database.

Emails from Database

Enter an email ID, select an action from the drop-down list box, and then click Execute to perform the selected action.

Select from:

Delete Email from Database	Deletes the specified email from the database and any corresponding attachments from the repository.
Retrieve Email	Retrieves the specified email from the database and writes it to the output file mcfdata.out.
Force Delete	Select after entering Delete Email from Database to force the deletion even if there is an error deleting any associated attachments from the repository.
Use Rowset API	Select to use the rowset-based GetMail API. Deselect to use the new Mail Classes API.

Authorize Email

Enter an email ID, a user role or name, and click Authorize or Unauthorize to perform the specified action.

Email ID

Enter the PeopleSoft email ID (not to be confused with the UID) with which the email was saved to the database.

User/Role Name

Enter a PeopleSoft user ID or role to be authorized or unauthorized to view the attachment associated with the selected email.

After entering an ID or role, select User or Role, as appropriate, from the drop-down list box.