This chapter explains how to integrate email functionality in a Portal Framework application at design time.
This chapter includes the following sections:
Note:
WebCenter Portal Mail supports only the Inbox. No other folders (or moving of messages) are supported.For more information about managing and including mail, see:
the "Managing Mail" chapter in Administering Oracle WebCenter Portal
the "Working with Mail" chapter in Using Oracle WebCenter Portal
This section provides an overview of WebCenter Portal mail features and requirements. It includes the following subsections:
Mail functionality enables users to access 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.
This mail does not replace users' mail clients; it simply enables users to access and compose mail in a single, collaborative environment.
With mail, 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 mail messages 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.
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).
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 Mail Messages 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.
Use the Search icons to find mail addresses and contacts of users in the LDAP store that the Framework application uses. For any user not in the LDAP store, you must enter an explicit mail address.
For more information about mail at runtime, see the "Working with Mail" section in Using Oracle WebCenter Portal.
Mail requires a mail server that supports IMAP4 and SMTP. The Microsoft Exchange mail server is required for automatic creation of distribution lists when portals are created. In a Portal Framework application, this feature may not be desirable. To disable it, do not provide the LDAP (Active Directory) server details in the mail connection.
This section describes the steps required for adding mail functionality to your application. It includes the following subsections:
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 mail working in Portal Framework applications.
Figure 35-4 Configuring Mail for Portal Framework Applications
Table 35-1 Configuring Mail for Portal Framework Applications
Actor | Task | Sub-task |
---|---|---|
Administrator |
1. Install WebCenter Portal and the back-end components for mail |
1.a For Microsoft Exchange 2007 only, follow additional configuration steps |
Developer |
2. Integrate mail in your Portal Framework application |
|
Developer or Administrator |
3. Deploy the Portal Framework application using one of the following tools:
|
|
Developer or Administrator |
4. (Optional) Add/modify connection parameters using one of the following tools:
|
|
End User |
Before you can use mail, you must first set up the connection to your mail server. This can be 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, see Administering Oracle WebCenter Portal.To create a connection to your mail server from the application:
In Oracle JDeveloper, open the application in which to consume mail.
In your application, under Application Resources, right-click Connections, then select Mail from the list.
Select to create the Mail 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
When configuring multiple mail accounts, you are not necessarily required to select this as the default connection. Keep in mind, however, that one connection must 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
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 mail to create distribution lists reliably, the WebCenter Portal 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:
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 74.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.On the Name page:
For Application Name, enter a unique name to identify the application. This name must be unique not only within the Framework 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.
Click Next.
On the General page, you can optionally enter values if you want the external application for mail 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 mail requires this authentication method.
Click Next.
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
Note:
The external application for mail requires theEmail Address
field, and it must be shown to users. Fields for Display Name
and Reply-To Address
also are leveraged when sending mail.External applications allow 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 Framework 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.
Click Finish to have the external application use private credentials, or click Next to set up shared or public credentials.
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.
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.
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 portal distribution lists.
For detailed parameter information, see Table 35-2.
Note:
For WebCenter Portal and mail to share an identity management system for setting up portal mailing lists, you must use Active Directory. For information about installing and configuring mail servers as the WebCenter Portal administrator, see Administering Oracle WebCenter Portal.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. For example, if the domain value is set to |
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 portal distribution list that is created. The users specified must exist in the base LDAP schema (specified in the |
|
Indicate whether a secured connection (SSL) is required between the Framework 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.
This section explains a basic incorporation of mail functionality. It includes the following subsections:
The Mail task flow displays a mail inbox.
To add mail to your application:
Follow the steps described in Chapter 2, "Setting Up 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 Framework application must be made secure using ADF security. ADF security is configured by default if you created your application using WebCenter Portal's Framework application template. For information about configuring ADF security, see Section 74.3, "Configuring ADF Security."
Open the page on which to add mail functionality.
In the Resource Palette, expand My Catalogs, WebCenter Portal - 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 task flows that require connections to back-end servers, such as task flows from discussions or announcements.
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>
The Mail 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
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
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 task flow.
Table 35-3 Mail Task Flow Parameters
Property | Description | Task Flow |
---|---|---|
|
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. |
|
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
Mail requires security to fetch mail for each logged-in user. ADF security is configured by default if you created your application using WebCenter Portal's Framework application template. For information about configuring ADF security, see Section 74.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 application point to the same identity store.
Note:
Even if the application and the mail server share the same identity store, mail does not support identity propagation. Single sign-on functionality is enabled through the external application mechanism.Mail works in a non-secured 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 74.13, "Working with External Applications."
This section describes optional features available with mail. It includes the following subsections:
The Mail Compose page enables users to determine how they want to compose individual messages within the application.
Invoke 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 portal but want to provide the ability for portal members to send mail 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 portal members.
Example 35-2 shows some 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="#{'Mail......'}" to="#{pageFlowScope['collab.mail.compose.subject']}"/> <af:setActionListener from="#{'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:setActionListener from="Shared-mail-connection-name" to="${pageFlowScope['collab.mail.compose.useConnectionName']}" /> </af:commandLink>
Example 35-3 shows how to hide the recipients fields (like To, Cc and Bcc) by setting the following action listener in ComposeView.jspx
:
By default, the 50 most recent mail messages are displayed 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 Mail Messages 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
.
This change applies to all users; that is, following Example 35-4, all users see 500 recent mail messages in their Inbox in the Framework application. Increasing the number of messages shown correspondingly increases the cache size on the Framework application. Take care to set this to a reasonable size.
This section describes common problems and solutions for mail.
Users are not able to retrieve their mail messages or send mail messages from within the Portal Framework application.
Ensure the following:
Ensure that a Mail connection exists in your application.
Ensure that the required Mail 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.
The mail within your Portal Framework application requires users to log in, but users are not able to authenticate and do not see any content at runtime. When users access mail, it throws an ExtApp Authorization Exception.
Mail works in a non-secured Portal Framework 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 Portal Framework application to run in secure mode, then you must configure ADF security for your application.
When users receive mail in Portal Framework 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.
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
.