Understanding the E-mail Channel

The e-mail channel requires configuration in Integration Broker in addition to settings in PeopleSoft MultiChannel Framework configuration pages. For information on the configuration of e-mail channel in the PeopleSoft Integration Broker see, Configuring E-mail Channel in PeopleSoft Integration Broker.

PeopleSoft MultiChannel Framework (MCF) provides a framework for:

  • Fetching e-mails from a mail server.

  • Storing and retrieving e-mail parts in a database.

  • Managing attachments.

  • Queueing of e-mails 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 e-mail processing.

See Understanding PeopleSoft MultiChannel Framework Mail Classes.

PeopleSoft MultiChannel Framework e-mail channel features include:

  • The GETMAILTARGET target connector.

  • A PeopleCode application package, PT_MCF_MAIL, to retrieve, store, and delete e-mail.

  • Support for both Post Office Protocol 3 (POP3) and Internet Message Access Protocol 4 (IMAP4) e-mail protocols.

  • Support for SSL connections.

  • Support for Transport Layer Security (TLS) connections.

  • Support for NT LAN Manager (NTLM) and Simple Authentication and Security Layer (SASL) authentication mechanisms.

  • Support for e-mail attachments, including:

    • An attachments repository running on the same web server as PeopleSoft Integration Broker.

    • URL access to e-mail attachments.

    • Storage and retrieval of e-mail attachments from database.

    • A relative addressing scheme to enable flexibility of repository location.

    • User- and role-based security to control access to attachments.

  • The option to access e-mail headers, attachments, and body from the mail server.

  • Support for multiple message size thresholds to control distribution of e-mail between the database, the attachment repository, and the mail server.

  • Support for UTF8 Unicode as supported by the Sun Java Runtime Environment (JRE).

    See http://java.sun.com.

  • Time zone conversions to support global service-level agreements.

  • Sample e-mail application pages demonstrating the functionality of the PT_MCF_MAIL application package.

  • Ability to enable logging for MCFOutbound e-mail by setting SMTP trace in psappsrv.cfg. The log file is created in the log directory defined in psappsrv.cfg.

    See SMTPTrace.

This section describes some factors to consider when handling e-mail using PeopleSoft MultiChannel Framework.

POP3 Versus IMAP4

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

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

Note: POP3 mail servers are typically read-only, which can create issues if e-mails are required to be deleted after being read.

Time Zone Offsets

Set the values of the e-mail 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 E-mail 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 E-mails

E-mails 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 noncompliant e-mails, however, at times, invalid parts will be ignored. For example, e-mail 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 e-mail part may not appear.

A common example of a malformed e-mail is one that contains 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 7-bit encoding, as described in RFC 2045 and others. This encoding is usually done by the e-mail sender.

Note: The PeopleSoft e-mail reader only supports e-mail messages that follow the SMTP specification. Many e-mail clients and mail servers have their own proprietary formats; therefore, be aware that PeopleSoft MCF will interpret these e-mails according to the RFC specification. For example, some mail servers and clients allow 8-bit encoded data in e-mail headers, which the PeopleSoft e-mail reader does not allow.

Domain Validation

Application developers can use the method IsDomainNameValid to validate e-mail address domains.

Note: The number of retries for domain validation is set by the parameter SMTPDNSTimeoutRetries in psappsrv.cfg.

See SMTP Settings, IsDomainNameValid.

E-mail Address Syntax Validation

The ValidateAddress method checks the e-mail address syntax against RFC standards.

See ValidateAddress.

Character Sets

If you wish to attach files which are named using characters outside of the character set recognized by your application server or process scheduler operating system, you should update the locale or regional settings of your operating system to allow those characters to be recognized.

SSL Connections

Certificates are an important component in SSL communication for authentication of the parties involved. In this case, one party is the E-mail Server and the other party is PeopleSoft Applications.

For the communication to work, you must import the trusted CA root certificates of the CA which signed the E-mail Server certificate into the Integration Broker Gateway truststore. If a CA issues a chain of certificates, you must add the entire certificate chain from the signer of the E-mail Server certificate to the Root CA certificate.

By default, the gateway truststore is the pskey peoplesoft keystore stored on the web server. The path to the gateway truststore is defined by the SSL_KEY_STORE_PATH variable in the setenv.cmd file.

The E-mail Server certificates must be imported into the Integration Broker keystore. The location of this keystore is defined by the secureFileKeystorePath property in Gateway Properties. By default, this keystore is the pskey peoplesoft keystore.

See Importing Keys and Certificates Into the Keystore.

Connect data for outgoing e-mails can be configured in psappsrv.cfg or provided by the application using application package PT_MCF_MAIL.

See Understanding PeopleSoft MultiChannel Framework Mail Classes.

Transport Layer Security Configurations

Transport Layer Security (TLS) authentication mechanism is more secure than SSL connections. For configuring TLS for inbound e-mails:

  1. Add the property MCF_UseTLS to the GETMAILTARGET target connector of the MCF_GetMail node with Y parameter that enables TLS connection to the server.

  2. Obtain the server certificate and import that in the pskey key store using pskeymanager utility. Update the Integration Broker Gateway properties file with the path to this key store and the key store password.

    • secureFileKeystorePath: Enter the full path and file name of the gateway keystore file, which is located in the web server directory structure. For example: <PIA_HOME>\webserv\<DOMAIN>\piaconfig\keystore.

    • secureFileKeystorePasswd: Enter the keystore password. This password must be encrypted.

NTLM and SASL Authentication Mechanisms

MCF supports the NT LAN Manager (NTLM) and the Simple Authentication and Security Layer (SASL) authentication mechanisms for outgoing e-mails. To enable these authentication mechanisms, you must add and configure the NTLM and the SASL parameters in psappsrv.cfg and psprcs.cfg for a primary server and if required, for a backup server. MCF does not set default values for the NTLM and the SASL parameters in the configuration files.

Note: NTLM and SASL log will be available in the SMTP log because NTLM and SASL are part of SMTP sessions. That is, separate log files are not created for NTLM and SASL.

See SMTP Settings.

Virus Scanning

You can enable virus scanning for inbound MCF e-mail attachments and outbound file attachments.