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.

• Enable virus scanning .

• 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 SSL connections.

• 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).

  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.

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

  See SMTPTrace.

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.

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

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 noncompliant 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 appear.

A common example of a malformed email 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 email sender.

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

Domain Validation

Application developers can use the method IsDomainNameValid to validate email addresses.

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

See SMTP Settings, IsDomainNameValid.

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 any party involved. In this case one party is Email Server and another party is PeopleSoft Applications. For the communication to work, you must import CA signer of the Server Certificate installed in the Email Server to pskey peoplesoft keystore stored in the web server. The path to pskey peoplesoft keystore is defined in secureFileKeystorePath property for the Gateway Properties.

See Importing Keys and Certificates Into the Keystore.

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

See Mail Classes.

Virus Scanning

You can enable virus scanning for inbound MCF Email attachments and outbound file attachments.

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

See Also

Managing Integration Gateways

Configuring the Gateway

Access the Gateways page using the following navigation path:

PeopleTools, Integration Broker, Gateways, Gateway ID

1. Create a local gateway.

2. 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.

3. Save the page.

4. Click Load Gateway Connectors.

   The connector properties appear.

5. Save the page again.

6. Configure the GETMAILTARGET connector properties.

Configuring GETMAILTARGET Properties

Access the Connector Properties page using the following navigation path:

PeopleTools, Integration Broker, Node Definitions, Connectors

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:

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.

Enabling Virus Scanning

This section discusses how:

• Locate virusscan.xml file for your web server.

• Configure the virusscan.xml file.

• Use virus scan error logs.

Locating virusscan.xml File for Your Web Server

Virus scanning can be enabled for inbound MCF Email and AddAttachment, by configuring the virusscan.xml file for your virus scan engine. The location of this file depends on your web server:

• WebLogic:

  <PIA_HOME>/webserv/<domain>/applications/peoplesoft/PSIGW.war/WEB-INF/classes/psft/pt8/virusscan

• Websphere:

  <PIA_HOME>/webserv/<domain>/installedApps/<domain>NodeCell/<domain>.ear/PSIGW.war/ WEB-INF/classes/psft/pt8/virusscan

See Continue, ConvertChar.

Configuring the virusscan.xml File

To enable the virus scanning feature:

1. Open VirusScan.xml.

   <?xml version="1.0" encoding="UTF-8"?>
   <Providers disableAll="True" logFile="./servers/PIA/logs/VirusScan%u.log">
       <!-- Sample Configuration for Symantec Engine 
   	<Provider>
     	     <name>Symantec</name>
   	     <class>psft.pt8.virusscan.provider.GenericVirusScanProviderImpl</class>
   	     <icapversion>ICAP/1.0</icapversion>
            <service-name>/SYMCScanResp-AV</service-name>
            <policycommand>?action=SCAN</policycommand>
            <address>152.68.144.44</address>
            <port>1344</port>
            <disable>false</disable>
       </Provider>-->
       
       <!-- Configure your own proivider -->
       <Provider>
       <!-- Provider Name of the Scan Engine -->
       <name></name>
       <!-- Provider Class of the Scan Engine. 
            psft.pt8.virusscan.provider.GenericVirusScanProviderImpl is 
            the default
            provider class.  -->
       <class>psft.pt8.virusscan.provider.GenericVirusScanProviderImpl</class>
       <!-- ICAP version -->
       <icapversion>ICAP/1.0</icapversion>
       <!-- ICAP ServiceName. The Service Name changes from Scan Engine to 
      Scan Engine. 
            This is the name Scan Engine Service is will be hosted with -->
       <service-name></service-name>
       <!-- RESPMOD extra commands, These are the RESPMOD commands  
   			(SEE ICAP Protocol). 
            Usually these commands will be chainging from Engine to Engine 
       -->
       <policycommand></policycommand>
       <!-- IP Address of Scan Engine host> -->
       <address></address>
       <!-- IP Port of Scan Engine host -->
       <port></port>
       <!-- Disable scanning for this provider -->
       <disable></disable>
       <!-- 
            Default codes = 200 and 204 for clean, 201,403 for infected 
            Use these tags to change the behaivior if needed
            <clean>200,204</clean>
            <infected>201,403</infected> 
            -->
   </Provider>
   </Providers>
   

   Note. A sample configuration for Symantec Engine is provided in the remarks.

2. In the Providers tag, set the attribute disableAll to False .

   <Providers disableAll="False" logFile="./servers/PIA/logs/VirusScan%u.log">

3. Multiple scan engine can be configured under <Providers>. Each <Provider> tag represents one scan engine. All configured scan engines will check for viruses. For each <Provider> tag enter values for the tags:

   Tag	Description	Example Value for Scan Engine
   <name>	Provider Name of the Scan Engine	Symantec
   <class>	Provider Class of the Scan Engine Default provider class is: psft.pt8.virusscan.provider.⇒ GenericVirusScanProviderImpl	psft.pt8.virusscan.provider.⇒ GenericVirusScanProviderImpl
   <icapversion>	ICAP version	ICAP/1.0
   <service-name>	Service name for the scan engine host.	/SYMCScanResp-AV
   <policycommand>	Policy command used by the Scan Engine. Only SCAN is supported.	?action=SCAN
   <address>	IP address of Scan Engine host.	IP address of the machine where the scan engine is running
   <port>	IP port of Scan Engine host.	Port where the scan engine is running
   <disable>	Disable scanning for this provider.	false
   <clean>	Default codes = 200 and 204 for clean. You can use this tag to change the behavior if needed.	200,204
   <infected>	Default codes = 201 and 403 for infected You can use this tag to change the behavior if needed.	201,403

Using Virus Scan Error Logs

There are two type of logs generated virus scanning logs and error logs.

Virus Scanning Logs

Virus Scanning logs are the only interface with the scanning engine. These logs are located in the path indicated by the logfile property in VirusScanning.xml. If there is a failure, the details will be logged ig.errorLog.filename in integrationGateway.properties

Error Logs

If there is a failure, the details will be logged ig.errorLog.filename in integrationGateway.properties For example, ig.errorLog.filename in <PIA_HOME>/webserv/<domain>/applications /peoplesoft/PSIGW.war/WEB-INF/integrationGateway.properties.

The return value when the virus scan for mail attachments is REPOSITORY_FAILURE = 8.

See Error Messages Returned by MCFGetMail Class Methods.

If there are any errors during file processing the error codes listed in this table will be generated.

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

Using the GetMail - Server Page

Access the GetMail - Server page using the following navigation path:

PeopleTools, MultiChannel Framework, Email, Sample Pages, GetMail - Server

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.

Read Headers

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

Read Emails

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

Access an Email

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

Create IMAP Folder

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

Using the MailStore - DB Page

Access the MailStore - DB page using the following navigation path:

PeopleTools, MultiChannel Framework, Email, Samples Pages, MailStore - DB

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 MCF.

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.

Authorize Email

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

See Also

Using the Email Sample Page