Configuring Email Channel in PeopleSoft Integration Broker
Before you configure the email channel for PeopleSoft Multichannel Framework, you must successfully install and configure the PeopleSoft Integration Broker.
See Installing PeopleSoft Integration Broker.
For the email channel to work, you must configure the following in PeopleSoft Integration Broker:
Define a gateway that will be used with the MCF_GETMAIL connector node.
Define a connector for the MCF_GETMAIL node and specify the gateway.
Configure the GETMAILTARGET connector properties.
Note: To use MCF email in
UNIX and LINUX systems, add -Djava.awt.headless=true in the JAVA_OPTIONS variable of the setEnv.sh file.
Use this option only if the operating system is set up as headless (no graphics option).
Access the Connector Properties page using the following navigation path:
. The Node Definition search page opens. Open a Node Definition and click the Connectors tab to open the Connectors page.
This example illustrates the Data Type/Properties tab on the Connectors page where you can set the Property Name of a Connector ID.
Configure GETMAILTARGET connector properties on the MCF_GETMAIL node. You can also set threshold values for email routed to the attachment repository.
Note: The threshold parameters MCF_EmSz_IB, MCF_EmSz_Part, and MCF_FetchSize, are not used. If the size of the email reads exceed the resources available, tuning needs to be done either by reducing the number of emails read at each time, or by limiting the size of emails, particularly attachments, at the mail server level.
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 a mail box support are downloaded to c:/temp/att/<mail server host name>/<mailbox>. Note: If the attachments are to be stored by a gateway that is remote to the webserver specified in the MCF_AttServ property, be sure that the file system permissions are set so that the directory may be accessed by both. The user permissions for the directory specified by MCF_AttRoot should be set such that the node (such as the local node) that will retrieve the attachments has read permissions. Note: The user name or mailbox portion of the attachment root path may include encoded characters. All email attachments, and email parts that are not of the content type 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:
MCF_AttRoot is only used for file-based attachments. Database attachments ignore this parameter. When using the HTTPS email protocol, this directory is used as a temporary staging area even in the case of database attachment storage |
|
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_ClientCertAlias |
ClientCert |
Provide the alias of the client certificate. Note: The client certificate must be imported in the pskey keystore. Note: The MCF_ClientCertAlias property must be set only if the Email Server is set for client authentication, that is, the Email Server is set to request the client’s certificate for authentication. Additionally, you must ensure that the trusted certificates and the certificate chain (if any) of the client certificate are loaded in the Email Server. See Installing Integration Gateway-Based Digital Certificates. |
|
MCF_ClientCertPass |
password |
Enter the password of the private key that you provided when you created the client certificate. Note: The alias and the password must match the alias and password of the imported client certificate in the pskey keystore. Note: The MCF_ClientCertPass property must be set only if the Email Server is set to request the client’s certificate for authentication. Additionally, you must ensure that the trusted certificates and the certificate chain (if any) of the client certificate are loaded in the Email Server. |
|
MCF_ContentTypes |
text/plain |
Lists those email content types (separated by commas) that are to be accessible by using the Text property of the MCFBodyPart class. The content type, text/plain, is always an implicit member of this list. Content types that are not members of this list will be stored in the attachment repository and, as a result, instead be accessible by using the AttachmentURL property of the MCFBodyPart class. For example, you may specify text/html or text/xml as a member of this list, and, as a result, it will be accessible through the Text property of the MCFBodyPart class. Since a binary content type is automatically converted to base64-encoded text by the email server, if it is specified as a member of the content types list, it will be stored in the PeopleSoft database in this form. So, do not specify binary content types in this list unless the application is prepared to convert this base64-encoded text back to its original binary form as needed. Note: If the value of the MCF_Force_Download_Attachments property is True, then the value of the MCF_ContentTypes property is entirely ignored. |
|
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_DBLengthType |
N |
Specifies the double byte length type of the database. The default value is N, which denotes that the type is Unicode. The other supported types are:
|
|
MCF_DisableAuthPlain |
N |
A value of Y indicates that MCFInboundEmail is prevented from attempting to connect to a mail server using PLAIN authentication. The default value is N. This property is not a required parameter. |
|
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. When using the HTTPS email protocol, determines the quantity of emails that can be retrieved in a request. See Understanding PeopleSoft MultiChannel Framework 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 Understanding PeopleSoft MultiChannel Framework 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. Note: The value of MCF_EmSz_Part divided by 3 is the character threshold for moving email body text into the attachment repository for HTTPS email. You can adjust this threshold according to your database needs and characters sets you use. |
|
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_FetchSize |
819200 |
Determines the number of bytes retrieved for an IMAP email in a single fetch. It also controls the size of the buffer ( in bytes) used to write email attachments to the repository. Setting MCF_FetchSize to a higher number uses more memory, but it may also increase the speed of download for larger emails and attachments. |
|
MCF_Force_Download_Attachments |
False |
A value of True indicates that all email parts, including text/plain, irrespective of their size or content type, are to be downloaded to the attachment repository. This property may be used to facilitate the viewing of an email body containing multi-byte characters. A value of False indicates that email parts are evaluated individually on the basis of their size, content type and the value of the MCF_ContentTypes property. Note: If the value of the MCF_Force_Download_Attachments property is True, then the value of the MCF_ContentTypes property is entirely ignored. |
|
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 Understanding PeopleSoft MultiChannel Framework Mail Classes. |
|
MCF_Password |
None |
Defines the default password for the mailbox unless otherwise specified in the SyncRequest. This property is not applicable to the HTTPS connection protocol. See Understanding PeopleSoft MultiChannel Framework 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. This property is not applicable to the HTTPS connection protocol. |
|
MCF_Protocol |
IMAP4 |
Defines the protocol used by the connector to access emails on the mail server. Supported values are POP3 , IMAP4 and HTTPS. Configuration of HTTPS will also require OAuth 2.0. |
|
MCF_Quarantine |
Quarantine |
Defines a quarantine folder for email meeting the following criteria:
The quarantine folder is created for each user account and must be managed by each email user, not by the system administrators. Note: Folders are supported only on IMAP4 mail servers. This property is not applicable to the HTTPS connection protocol. |
|
MCF_RepositoryType |
FILE |
Specifies the location for storing email attachments. Email attachments can be stored either in the attachment repository or in the database. The default value is FILE. If you select DATABASE, the email attachments are stored in the database. Also, when you select DATABASE, the value in the MCF_AttRoot property is ignored. If you select FILE, the email attachments are stored in the attachment repository. |
|
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.example.com. When using the HTTPS email protocol, MCF_Server will refer to the application name. See Understanding PeopleSoft MultiChannel Framework Mail Classes. |
|
MCF_TrashFolder |
Trash |
Determines that the deleted mails are transferred to a trash folder and not permanently expunged from the system. You need to provide a mail server that supports IMAP4 folders. This feature does not support POP3 protocol because local folders are not supported. |
|
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 support@example.com, the user name is support. This property will be used to hold the application name from the configuration page. |
|
MCF_UseSSL |
N |
A value of Y indicates that SSL/TLS must be used when communicating to the mail server. The SSL settings will be loaded from the GETMAILTARGET connector, including client certificate settings. For information on SSL connections, see Working With Emails using PeopleSoft Multichannel Framework, SSL Connections. This property is not applicable to the HTTPS connection protocol. |
|
MCF_UseTLS |
N |
If the property value is set to Y, then it requires an SSL/TLS connection for the inbound email system using STARTTLS. This property is not applicable to the HTTPS connection protocol. For information on TLS connections, see Working With Emails using PeopleSoft Multichannel Framework, Transport Layer Security Configuration. |
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.
Setting Java Truststore Properties for the GETMAILTARGET Connector
You may set the Java truststore path and password for the GETMAILTARGET connector.
Use these properties to set the Java truststore path and password in the IntegrationGateway.properties file:
secureTruststorePath=<fileLocation>secureTruststorePasswd=<password>Use the supplied encryption utility to provide an encrypted password for these entries.
Note: If the truststore path is not specified, it will be undefined for email retrieval, and trusted root certificates may not be honored.