35 Integrating the Mail Service

This chapter explains how to integrate the Mail service in a WebCenter Portal application at design time.

For more information about managing and including mail, see:

"Managing the Mail Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter
"Working with the Mail Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces

This chapter includes the following sections:

Section 35.1, "Introduction to the Mail Service"
Section 35.2, "Basic Configuration for the Mail Service"
Section 35.3, "Advanced Information for the Mail Service"

Note:

The Mail service supports only the Inbox. No other folders (or moving of messages) are supported.

35.1 Introduction to the Mail Service

This section provides an overview of Mail service features and requirements. It includes the following subsections:

Section 35.1.1, "Understanding the Mail Service"
Section 35.1.2, "Requirements for the Mail Service"

35.1.1 Understanding the Mail Service

The Mail service enables users to ac cess the inbox of a mail server that supports Internet Message Access Protocol4 (IMAP4) and Simple Mail Transfer Protocol (SMTP). Additionally, it enables users to compose a new mail message from within the application (with attachments) and delete, reply to, and forward messages.

The Mail service does not replace users' mail clients; it simply enables users to access and compose mail in a single, collaborative environment.

With the Mail service, you can do the following:

Read a message by clicking the linked mail subject.
View sender details (including date) by expanding the From field.
Scroll down to see the other messages not in the view. You can navigate among the fetched messages as cached messages.
Attach a file to a message by expanding the attachment section within the mail dialog and clicking Attach. Specify an attachment in the new dialog pop-up. Remove an attachment from the mail by clicking the Remove Attachment icon.
Reply to a message by clicking the Reply or Reply All icon.
Forward a message by clicking the Forward icon.
Cancel an operation (for example, sending a mail) by clicking Cancel.

Figure 35-1 shows the Mail task flow at runtime. At the top of the view are three elements: a dropdown list that shows the number of mails to display (here, All), the Compose icon, and the Refresh icon. The Refresh icon provides a means of manually checking for new messages in the inbox.

Figure 35-1 Mail Service at Runtime

Description of "Figure 35-1 Mail Service at Runtime"

The dropdown list provides filters to focus the view on messages received today, messages received since yesterday, messages received this week, and messages received this month (Figure 35-2).

Figure 35-2 Message Filter

Description of "Figure 35-2 Message Filter"

Note:

By default, All displays the 50 most recent messages. For information on how to increase this amount, see Section 35.3.2, "Configuring the Number of Mails Displayed."

Click the Compose icon next to the dropdown list to compose a new message right from your application. Clicking this icon displays the Compose page, as shown in Figure 35-3.

Figure 35-3 Compose Mail

Description of "Figure 35-3 Compose Mail"

Use the Search icons to find mail addresses and contacts of users in the LDAP store that the WebCenter Portal application uses. For any user not in the LDAP store, you must enter an explicit mail address.

For more information about the Mail service at runtime, see Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

35.1.2 Requirements for the Mail Service

The Mail service requir es a mail server that supports IMAP4 and SMTP protocols.

In WebCenter Spaces, the Microsoft Exchange mail server is required for automatic creation of distribution lists when Spaces are created. In a WebCenter Portal application, this feature may not be desirable. To disable it, do not provide the LDAP (Active Directory) server details in the mail connection.

35.2 Basic Configuration for the Mail Service

This section describes the steps required for adding the Mail service to your application. It includes the following subsections:

Section 35.2.1, "Configuration Roadmap - Mail Service"
Section 35.2.2, "Setting up Connections for the Mail Service."
Section 35.2.3, "Adding the Mail Service at Design Time"
Section 35.2.4, "Setting Security for the Mail Service"

35.2.1 Configuration Roadmap - Mail Service

Use the roadmap in this section as a guide through the configuration process.

Figure 35-4 and Table 35-1 provide an overview of the prerequisites and tasks required to get the Mail service working in WebCenter Portal applications.

Figure 35-4 Configuring the Mail Service for WebCenter Portal Applications

Description of "Figure 35-4 Configuring the Mail Service for WebCenter Portal Applications"

Table 35-1 Configuring the Mail Service for WebCenter Portal Applications

Actor	Task	Sub-task
Administrator	1. Install WebCenter and the back-end components for the Mail service	1.a For Microsoft Exchange 2007 only, follow additional configuration steps
Developer	2. Integrate the Mail service in your WebCenter Portal application	2.a Configure a connection to your mail server in JDeveloper, associating the mail server with an external application
		2.b Add the Mail task flow to a page in JDeveloper
Developer or Administrator	3. Deploy the WebCenter Portal application using one of the following tools: JDeveloper (Developer) Fusion Middleware Control (Administrator) WLST (Administrator) WLS Admin Control (Administrator)
Developer or Administrator	4. (Optional) Add/modify connection parameters using one of the following tools: JDeveloper, then redeploy the application (Developer) Fusion Middleware Control (Administrator) WLST (Administrator)
End User	5. Access mail by clicking Login to Mail on a Mail task flow, and entering your login credentials for the mail server

35.2.2 Setting up Connections for the Mail Service

Before you can use the Mail service, you must first set up the connection to your mail server. The Mail service supp orts any mail server based on IMAP4 and SMTP protocol.

Note:

While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

To create a connection to your mail server from the application:

In Oracle JDeveloper, open the application in which to consume the Mail service.
In your application, under Application Resources, right-click Connections, then select Mail from the list.
Select to create the Mail service connection in Application Resources.

A connection in Application Resources is available only for that application; while a connection in IDE Connections is available for all applications you create. If you plan to use the connection in other applications, then select IDE Connections to avoid having to re-create it.
In the Connection Name field, enter a unique name for the connection.
When configuring a single mail account, select the Set as default connection checkbox to use this as the active connection (Figure 35-5).

Figure 35-5 Configure a New Mail Connection, Step 1

Description of "Figure 35-5 Configure a New Mail Connection, Step 1"

When configuring multiple mail accounts, you are not necessarily required to select this as the default connection. Keep in mind, however, that the service requires that one connection be marked as the default connection.

Note:
After you create a connection as the default connection, you cannot edit it so that it is not the default. To use a different default connection, you must create a new connection and mark that as the default connection.
On the General page, enter values for the parameters (Figure 35-6).

Figure 35-6 Configure a New Mail Connection, Step 2

Description of "Figure 35-6 Configure a New Mail Connection, Step 2"
- IMAP Host: The location of your IMAP server
- IMAP Port: The IMAP server port number (default is -1)
- SMTP Host: The location of your SMTP server
- SMTP Port: The SMTP server port number (default is -1)
- IMAP Secured: Indicates (true/false) a secure SSL connection (default is false)
- SMTP Secured: Indicates (true/false) a secure SSL connection (default is false)
- LDAP Host and LDAP Port: These, and all other LDAP values, are required only if Microsoft Exchange is the mail server. For the Mail service to create distribution lists reliably, the WebCenter Spaces application should use the same Active Directory server as Microsoft Exchange.
- Connection Timeout: The connection timeout (in seconds).
Click Test Connection to check that the host and port are available.
You must select an existing external application or create a new external application to proceed:
1. For External Application, click the + icon to open the Register External Application wizard
  
  The application maps the mail server user to the application user so that end users are not required to enter their user names and passwords each time.
  
  For more information on external applications, see Section 67.13, "Working with External Applications."
  
  Note:
  External application credential provisioning is built into the mail connection. You do not need to drop the External Application - Change Password task flow on a page.
2. On the Name page:
  
  For Application Name, enter a unique name to identify the application. This name must be unique not only within the WebCenter Portal application, but also among other connections. Note that you cannot edit this field afterward.
  
  For Display Name, enter a name for the application that end users see in the credential provisioning screens.
3. Click Next.
4. On the General page, you can optionally enter values if you want the external application for the Mail service to participate in Click Through Login.
  
  For Login URL, enter the URL to which the HTML login page is submitted. View the HTML source of the application's login form to retrieve this URL.
  
  For User Name/ID Field Name, enter the label that the application uses for the user name field, for example, User Name.
  
  For Password Field Name field, enter the label that the application uses for the password field, for example Password.
  
  From the Authentication Method list, select POST. This submits login credentials within the body of a form. The external application for the Mail service requires this authentication method.
5. Click Next.
6. On the Additional Fields page, click Add Field, and add an extra field with the name Email Address. This field captures the user's mail address, so that when the user sends mail, the sender address is this mail address. Select the Display to User checkbox.
  
  Additionally, to specify that replies to the user's mail should go to different mail address than the Email Address field, click Add Field again, and add an extra field with the name Reply-To Address. Select the Display to User checkbox, as shown in Figure 35-7.
  
  Figure 35-7 Email Address and Reply-To Additional Fields
  
  Description of "Figure 35-7 Email Address and Reply-To Additional Fields"
  
  Note:
  The external application for the Mail service requires the Email Address field, and it must be shown to users. Fields for Display Name and Reply-To Address also are leveraged when sending mail.
7. The External Application service allows different types of credentials to be associated with a connection.
  
  When shared credentials are specified, every authenticated user uses the same credentials to access the external application; that is, the user name and password you define here.
  
  With public credentials, without authenticating your WebCenter Portal application, you can view mail from a certain mail ID for all unauthenticated (public) users. Public credentials are used whenever an application is not secured or the user has not yet logged in.
  
  Note:
  Public credentials are required to send mail from a self-registration page.
  
  With private credentials, each user must authenticate to an individual mail ID. That is, each application user must specify his own credentials.
8. Click Finish to have the external application use private credentials, or click Next to set up shared or public credentials.
9. For Shared Credentials Only: On the Shared Credentials page, ensure that Specify Shared Credentials is selected and then enter the shared user credentials and mail ID.
10. For Public Credentials Only: On the Public Credentials page, ensure that Specify Public Credentials is selected and then enter the user credentials and mail ID for public use.
11. Click Finish to register the external application.
Back on the Mail connection wizard, ensure that this newly-created external application connection for mail is selected.

Optionally, you can add LDAP parameter values for the Active Directory server to manage (WebCenter Spaces) Space distribution lists.

For detailed parameter information, see Table 35-2.

Note:

For WebCenter Spaces and the Mail service to share an identity management system for setting up Space mailing lists, you must use Active Directory. For information about installing and configuring mail servers as the WebCenter administrator, see Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

Table 35-2 LDAP Directory Server Configuration Parameters

Field	Description
LDAP Host	Enter the host name of the computer where the LDAP directory server is running.
LDAP Port	Enter the port on which the LDAP directory server listens.
LDAP Base DN	Enter the base distinguished name for the LDAP schema. For example, CN=Users,DC=oracle,DC=com.
LDAP Domain	Enter the domain to be appended to distribution list names. In WebCenter Spaces, for example, if the domain value is set to `oracle.com`, then the Finance Project Space maintains a distribution list named `FinanceProject@oracle.com`.
LDAP Administrator User Name	Enter the user name of the LDAP directory server administrator. A valid user with privileges to make entries into the LDAP schema.
LDAP Administrator Password	Enter the password for the LDAP directory server administrator. The password is stored in a secured store.
LDAP Default User	Enter a comma-delimited list of user names to whom you want to grant moderator capabilities. These users become members of every Space distribution list that is created. The users specified must exist in the base LDAP schema (specified in the `LDAP Base DN` field).
`ldap.secured`	Indicate whether a secured connection (SSL) is required between the WebCenter Portal application and the LDAP directory server. If LDAP is configured to run in secure mode, then add this property (set to true/false) to use LDAP while creating distribution lists.

Click Finish.

You can see the new mail connection under Application Resources - Connections.

35.2.3 Adding the Mail Service at Design Time

This section explains a basic incorporation of the Mail service. It includes the following subsections:

Section 35.2.3.1, "Mail Service Task Flows"
Section 35.2.3.2, "How to Add the Mail Service to your Application"

35.2.3.1 Mail Service Task Flows

The Mail service includes one task flow: Mail. This task flow displays a mail inbox.

35.2.3.2 How to Add the Mail Service to your Application

To add the Mail service to your application:

Follow the steps described in Chapter 3, "Preparing Your Development Environment" to create a customizable page in your application.
Ensure that you have configured your application to connect to the mail server.
If you configured your external application for private or shared credentials, then the WebCenter application must be made secure using ADF security. ADF security is configured by default if you created your application using the WebCenter Portal Application template. For information about configuring ADF security, see Section 67.3, "Configuring ADF Security."
Open the page on which to add the service.
In the Resource Palette, expand My Catalogs, WebCenter Services Catalog, and Task Flows.
Drag and drop the Mail task flow on to the page.
In the Create list, select Region to add the task flow to your page.
The resulting Edit Task Flow Binding dialog displays the optional tabularView parameter. If this parameter is set to true, then mail messages appear in a table, like an Inbox on any mail client. If this parameter is set to false, then mail messages render in a list view.

Note:
If you created a connection in IDE and not in the application, then the connection must be added to the application. For example, in the Resource Palette under IDE Connections, right-click the connection and select Add to Application.
Save your page and run it to the browser.
When you run the page with the Mail task flow for the first time, you are prompted to enter external application mail credentials from within the Mail task flow.

Enter the credentials, then click Submit.

Notes:

All instances of the Mail task flow in an application run against the same mail server, and it serves no purpose to add multiple Mail task flow instances. This is true for all service task flows that require connections to back-end servers, such as task flows from the Discussions or Announcements services.
After an application has been accessed with saved credentials, those credentials are persisted even after redeployment. To ignore saved credentials from previous deployments, edit appUID in adf-config.xml before redeploying the application. Edit the following value in bold to specify a modified value; for example, add 1 to the last value to update it as WCApp1-1235).
```
<adf:adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
     <adf-property name="adfAppUID" value="WCApp1-1234"/>
 </adf:adf-properties-child>
```

35.2.3.3 How to Modify the Mail Service Task Flow Parameters

The Mail service task flow has an optional task flow binding parameter.

You can adjust the parameter values when you drop the task flows onto a page or after you have placed a task flow on a page:

Navigate to the Edit Task Flow Binding dialog by clicking the Bindings tab at the bottom of the page (next to the Source tab).
Under Executables, you'll see the task flow you added. Figure 35-8 shows an example of a Search task flow in the Executables section.

Figure 35-8 Page Data Binding Definition

Description of "Figure 35-8 Page Data Binding Definition"
Select the task flow, and next to the Executables heading, click the Edit selected element (pencil) icon.
In the Edit Task Flow Binding dialog Figure 35-9, revise the binding parameter values as required.

Figure 35-9 Edit Task Flow Binding Dialog for Mail Task Flow

Description of "Figure 35-9 Edit Task Flow Binding Dialog for Mail Task Flow"
When you are finished, click OK.
Save and run your page to see the results.

Table 35-3 describes the properties that are unique to the Mail service task flow.

Table 35-3 Mail Service Task Flow Parameters

Property	Description	Task Flow
`tabularView`	Using the EL value type, enter a value of true to display the information associated with a mail message, such as its subject, sender, and, date sent, in a tabular format. If this parameter is set to false, then mail messages render in a list view.	Mail

Figure 35-10 depicts the Mail task flow where the region parameter tabularView is set to true.

Figure 35-10 A Mail Task Flow where the Region Parameter Tabular Is Set to True

Description of "Figure 35-10 A Mail Task Flow where the Region Parameter Tabular Is Set to True"

35.2.4 Setting Security for the Mail Service

The Mail service requires security to fetch mail for each logged-in user. ADF security is configured by default if you created your application using the WebCenter Portal Application template. For information about configuring ADF security, see Section 67.3, "Configuring ADF Security."

The external application credentials for the user name used to log in to the application are fetched and used to log in to the mail server. The recommended approach is to have the mail server and the WebCenter application point to the same identity store.

Note:

Even if the WebCenter application and the mail server share the same identity store, the Mail service does not support identity propagation. Single sign-on functionality is enabled through the external application mechanism.

The Mail service works in a non-secured WebCenter application if, and only if, the external application connection is configured with public credentials. If you do not apply security, and if mail requires a login to access the content, then users are not able to authenticate and do not see any content at runtime.

For information about using external applications, see Section 67.13, "Working with External Applications."

35.3 Advanced Information for the Mail Service

This section describes optional features available with the Mail service. It includes the following subsections:

Section 35.3.1, "Invoking the Mail Compose Page"
Section 35.3.2, "Configuring the Number of Mails Displayed"
Section 35.3.3, "Troubleshooting the Mail Service"

35.3.1 Invoking the Mail Compose Page

The Mail Compose page enables users to determine how they want to compose individual messages within the application.

Invok e the Mail Compose page directly with a navigation rule that directs the user to the full page (Example 35-1).

Example 35-1 Invoking the Mail Compose Page

/oracle/workplace/collab/mail/view/jsf/pages/ComposeView.jspx

When you cannot provision mail accounts for all users within a Space but want to provide the ability for Space members to send mails to other members, then specify a shared (public) mail connection with the useConnection parameter. (Specify the connection name as a region input parameter to the mail-service compose view.) The end user Mail Preferences does not display mail connections with shared credentials.

You can pass optional parameters to seed the compose message. For example, you can pass parameters to pre-populate fields like To, Cc, Bcc, From, Subject, and Content. Set parameters only for items you want to pre-populate. If you require an empty ComposeView.jspx, then no setActionListener is necessary. You must set all parameters on pageFlowScope.

Use the scope parameter to set the scope within which the compose view should be launched.

Use the sendMailToGSMembers parameter to select the option to send mail to all Space members.

Example 35-2 shows parameters for the Mail Compose page (ComposeView.jspx):

Example 35-2 Parameters of the Mail Compose Page

<af:commandLink text="Compose Mail" action="sendMail">
    <af:setActionListener from="#{'john.doe@oracle.com'}" to="#{pageFlowScope['collab.mail.compose.toList']}"/>
    <af:setActionListener from="#{'Testing Mail......'}" to="#{pageFlowScope['collab.mail.compose.subject']}"/>
    <af:setActionListener from="#{'Testing Mail Service'}" to="#{pageFlowScope['collab.mail.compose.content']}"/>
    <af:setActionListener from="#{'ruby@oracle.com'}" to="#{pageFlowScope['collab.mail.compose.ccList']}" />
    <af:setActionListener from="#{'ruby@oracle.com'}" to="#{pageFlowScope['collab.mail.compose.bccList']}" />
    <af:setActionListener from="#{'monty@oracle.com'}" to="#{pageFlowScope['collab.mail.compose.from']}" />
    <af:setActionListener from="#{'text/html'}" to="#{pageFlowScope['collab.mail.compose.contentType']}" />
</af:commandLink>

To hide the recipients fields (like To, Cc and Bcc), set the following action listener in ComposeView.jspx:

Example 35-3 Hiding Recipient Fields in the Mail Compose Page

<af:setActionListener from="#{'false'}" to="#{pageFlowScope['collab.mail.message.showrecipients']}" />

35.3.2 Configuring the Number of Mails Displayed

By default, the Mail service displays the 50 most recent mail messages from your Inbox folder. Providing that your mail server supports the increase in memory cache that fetching additional mail requires, the administrator can change this to a higher number in the adf-config.xml file.

Add the mail.messages.fetch.size property as shown in Example 35-4:

Example 35-4 Increasing the Number of Mails Displayed

<adf-collaboration-config xmlns="http://xmlns.oracle.com/webcenter/collab/config">

<service-config
serviceId="oracle.webcenter.collab.mail">
<property name="mail.messages.fetch.size" value="500"/>
</service-config>

</adf-collaboration-config>

Alternatively, your Fusion Middleware administrator can increase this value with the WLST command setMailServiceProperty. For more information, see Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

This change applies to all users; that is, following Example 35-4, all users see 500 recent mails in their Inbox in the WebCenter Portal application. Increasing the number of messages shown correspondingly increases the cache size on the WebCenter Portal application. Take care to set this to a reasonable size.

35.3.3 Troubleshooting the Mail Service

This section describes common problems and solutions for the Mail service.

Problem

Users are not able to retrieve their mail messages or send mail messages from within the WebCenter Portal application.

Solution

Ensure the following:

Ensure that a Mail service connection exists in your application.
Ensure the required Mail service connection is marked as the default connection.
Ensure the mail server configured in the connection is up and running. You can try connecting from any other mail client to ensure that the connection details are correct.

Problem

The Mail service within your WebCenter Portal application requires users to log in, but users are not able to authenticate and do not see any content at runtime. When users access the Mail service, it throws the ExtApp Authorization Exception.

Solution

The Mail service works in a non-secured WebCenter Portal application if, and only if, the Mail connection is configured to use an external application connection with public credentials. If your application is running in non-secured mode, then ensure that you have configured public credentials for your external application.

If you want your WebCenter Portal application to run in secure mode, then you must configure ADF security for your application.

Problem

When users receive mail in WebCenter Portal applications, message content is shown as an attachment (named content.html) rather than within the message body. This can occur if the mail server is running Microsoft Exchange Server 2007 and the "Update Rollup 3 for Microsoft Exchange Server 2007" is not yet installed.

Solution

Mail server administrators must download and install "Update Rollup 3 for Microsoft Exchange Server 2007" which fixes this issue. For more information, see http://support.microsoft.com/kb/930468.