1. Administering Oracle WebCenter Portal
  2. Administering Tools and Services
  3. Managing Mail

9 Managing Mail

Configure and manage mail for WebCenter Portal or the "Send Mail" feature to send mail directly from within a portal.

Note:

Oracle WebCenter Portal has deprecated the support for Jive features (announcements and discussions/discussion forums). Hence, Jive features are not available in 14.1.2 instances.

Always use Fusion Middleware Control or WLST command-line tool to review and configure back-end servers for WebCenter Portal. Any changes that you make to post-deployment, are stored in MDS metatdata store as customizations.

Permissions:

To perform the tasks in this chapter, you must be granted the WebLogic Server Admin role through the Oracle WebLogic Server Administration Console and the Administrator role granted through WebCenter Portal Administration.

For more information about roles and permissions, see Understanding Administrative Operations, Roles, and Tools.

For troubleshooting issues with mail, see Troubleshooting Issues with Mail.

Topics:

9.1 About Mail Server Connections

Oracle WebCenter Portal supports any mail server that supports IMAP4 and SMTP. To enable users to access mail and perform basic operations such as read, reply, and forward within WebCenter Portal, you must first register the appropriate mail server. Mail is not configured out-of-the-box.

You can register multiple mail server connections.

WebCenter Portal supports multiple mail connections. The mail connection marked active is the default connection for mail in WebCenter Portal. All additional connections are offered as alternatives; users can choose which one they want to use through user preferences.

9.2 Configuration Roadmap for Mail

Use the roadmap in this section as an administrator's guide through the configuration process:

Figure 9-1 and Table 9-1 provide an overview of the prerequisites and tasks required for mail to work in WebCenter Portal.

Figure 9-1 Configuring Mail

Description of Figure 9-1 follows
Description of "Figure 9-1 Configuring Mail"

Table 9-1 Configuring Mail for WebCenter Portal

Actor Task Link

Administrator

1. Install WebCenter Portal and the required mail server.

Mail Server - Installation

Administrator

2. Configure a connection between WebCenter Portal and your mail server -- associating the mail server with an external application -- using one of the following tools:

  • Fusion Middleware Control

  • WLST

Registering Mail Servers

Application Specialist

3. Add the Mail task flow to a portal page.

Adding the Mail Task Flow to a Page in Building Portals with Oracle WebCenter Portal

Application Specialist/End User

4. Access mail with one of the following methods:

  • Click Login to Mail on a Mail task flow, and enter your login credentials for the mail server

  • Navigate to the Preferences - Mail page and specify your mail credentials

See:

9.3 Mail Server Prerequisites

This section includes the following subsections:

9.3.1 Mail Server - Installation

See your mail server documentation for installation information.

9.3.2 Mail Server - Configuration

You can allow WebCenter Portal to create and manage portal distribution lists. This feature is supported only with Microsoft Exchange.

If enabled, a portal distribution list is created automatically whenever a portal is created. Users added or removed from the portal are implicitly added or removed from the corresponding portal distribution list, provided that the LDAP Base DN does not change (only one LDAP Base DN is supported) and that users created on Microsoft Exchange Active Directory correspond with users created in the identity store used by WebCenter Portal. To disable this feature, do not enter the LDAP (Active Directory) server details in the mail connection.

For information about adding users on a mail server, see the mail server's product documentation. For information about adding users to WebCenter Portal's identity store, see Adding Users to the Embedded LDAP Identity Store.

Microsoft Exchange 2007, Microsoft Exchange 2010, and Microsoft Exchange 2013 are the only mail servers for which there are configuration prerequisites. If you are working with a different mail server, then you can bypass the rest of this section.

9.3.3 Mail Server - Security Considerations

For more information, see Securing the WebCenter Portal Connection to IMAP and SMTP with SSL.

Note:

If LDAP is configured to run in secure mode, then add the LDAP Secured property (set to true/false) to use LDAP while creating distribution lists. For more information, see Table 9-4.

9.3.4 Mail Server - Limitations

In WebCenter Portal, mail requires a Microsoft Exchange mail server connection to enable automatic WebCenter Portal distribution list management.

9.4 Registering Mail Servers

You can register multiple mail server connections. To start using the new mail connections you must restart the managed server on which WebCenter Portal is deployed.

This section includes the following subsections:

9.4.1 Registering Mail Servers Using Fusion Middleware Control

To register a mail server with WebCenter Portal:

  1. Log in to Fusion Middleware Control and navigate to the home page for the WebCenter Portal.
  2. From the WebCenter Portal menu, select Settings > Service Configuration.
  3. On the WebCenter Portal Service Configuration page, select Mail Server.
  4. To connect to a new mail server, click Add.

    Figure 9-2 Configuring Mail Servers

    Description of Figure 9-2 follows
    Description of "Figure 9-2 Configuring Mail Servers"
  5. Enter a unique name for this connection, and indicate whether this connection is the active (or default) connection for the application.

    Table 9-2 Mail Server Connection - Name

    Field Description

    Connection Name

    Enter a unique name for the connection. The name must be unique (across all connection types) within WebCenter Portal.

    Active Connection

    Select to indicate whether this connection is the default (or active) connection for mail.

    You can register multiple mail server connections:

    WebCenter Portal supports multiple mail connections. The mail connection marked active is the default connection for mail. All additional connections are offered as alternatives; users can choose which one they want to use through user preferences.

  6. Enter connection details for the mail server.

    Table 9-3 Mail Server Connection Details

    Field Description

    IMAP Host

    Enter the host name of the computer where IMAP (Internet Message Access Protocol) is running.

    IMAP Port

    Enter the port on which IMAP listens.

    IMAP Secured

    Indicate whether a secured connection (SSL) is required for incoming mail over IMAP.

    SMTP Host

    Enter the host name of the computer where SMTP (Simple Mail Transfer Protocol) is running.

    SMTP Port

    Enter the port on which SMTP listens.

    SMTP Secured

    Indicate whether a secured connection (SSL) is required for outgoing mail over SMTP.

    Associated External Application

    Associate the mail server with an external application. External application credential information is used to authenticate users against the IMAP and SMTP servers. Mail uses the same credentials to authenticate the user on both IMAP and SMTP.

    You can select an existing external application from the list, or click Create New to configure a new external application. For more information, see Managing External Applications.

    The external application for mail must use Authentication Method=POST, and you can customize some mail header fields (with Display to User enabled):

    • Property: mail.user.emailAddress (who the mail is from)

      Property: mail.user.displayName (display name from the mail)

      Property: mail.user.replyToAddress (address used to reply to the mail)

    These properties ensure that a specific mail address is the same in the external application and in the mail server. They are added to the mail connection and are used by mail for the From, Display Name and Reply To fields (Figure 9-3). See Table 9-7 for Additional Properties configuration.

    If your application offers a self-registration page with the facility to mail user ID information on request, then you must ensure that public credentials are configured for the external application selected here. If public credentials are not defined, then mail cannot be sent to users on their request. WebCenter Portal, for example, offers this feature on its default self-registration page.

  7. Specify LDAP connection details for the Active Directory server managing WebCenter Portal distribution lists (Table 9-4).

    WebCenter Portal supports Microsoft Exchange where distribution lists are managed on an Active Directory server.

    Note:

    Active Directory server details must be provided as part of the mail connection for distribution lists to work in WebCenter Portal.

    Table 9-4 LDAP Directory Server Configuration Parameters

    Field Description

    LDAP Host

    Enter the host name of the computer where the LDAP directory server (Lightweight Directory Access Protocol) 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 appended to distribution list names.

    For example, if the domain value is set to example.com, then a portal named Finance Project maintains a distribution list named FinanceProject@example.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 moderation 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 LDAP Base DN field).

    LDAP Secured

    Indicate whether a secured connection (SSL) is required between WebCenter Portal and the LDAP directory server.

  8. Configure advanced options for the mail server connection.

    Table 9-5 Mail Server Connection - Advanced Configuration

    Field Description

    Connection Timeout (seconds)

    Specify a suitable timeout for the connection.

    This is the length of time (in seconds) WebCenter Portal waits for a response from the mail server before issuing a connection timeout message.

    The default is -1, which means that the default is used. The default is 10 seconds.
  9. Optionally, you can add more parameters to the mail server connection.

    Table 9-6 Additional Mail Connection Properties

    Additional Connection Property Description

    charset

    Characterset used on the connection.

    The default charset is UTF-8. To use a different characterset, such as ISO-8859-1, set the charset connection property.

    Various IMAP properties

    Any valid IMAP connection property. For example, mail.imap.connectionpoolsize.

    For a list of valid protocol properties, see your mail server documentation. For a list of standard IMAP properties, see the Java Mail APIs:

    https://javaee.github.io/javamail/docs/api/com/sun/mail/imap/package-summary.html

    Various SMTP properties

    Any valid SMTP connection property. For example, mail.smtp.timeout.

    For a list of valid protocol properties, see your mail server documentation. For a list of standard SMTP properties, see the Java Mail APIs:

    https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html

    If additional parameters are required to connect to the mail server, expand Additional Properties and enter details as required.

    Table 9-7 Mail Connection - Additional Properties

    Field Description

    Add

    Click Add to specify an additional connection parameter:

    • Property Name -Enter the name of the connection property.

    • Property Value - Enter the default value for the property.

    • Is Property Secured - Indicate whether encryption is required. When selected, the property value is stored securely using encryption.

      For example, select this option to secure the admin.password property where the value is the actual password.

    Delete

    Click Delete to remove a selected property.

    Select the correct row before clicking Delete.

    Note: Deleted rows appear disabled until you click OK.

    Figure 9-3 Additional Properties for Mail Connection

    Description of Figure 9-3 follows
    Description of "Figure 9-3 Additional Properties for Mail Connection"
  10. Click OK to save this connection.
  11. To start using the new (active) connection, restart the managed server on which WebCenter Portal is deployed.

9.4.2 Registering Mail Servers Using WLST

Use the WLST command createMailConnection to create a mail server connection. For command syntax and examples, see createMailConnection in WebCenter WLST Command Reference.

Use the WLST command setMailConnectionProperty to add additional required properties through your external application. The external application for mail must use Authentication Method=POST, and you can customize some mail header fields (with Display to User enabled). For example: 

setMailConnectionProperty(appName='webcenter', name='NotificationSharedConn', key='mail.user.emailAddress', value='john.doe@example.com')

setMailConnectionProperty(appName='webcenter', name='NotificationSharedConn', key='mail.user.displayName', value='John Doe')

setMailConnectionProperty(appName='webcenter', name='NotificationSharedConn', key='mail.user.replyToAddress', value='feedback@example.com')

where:

  • mail.user.emailAddress = Email Address ('From' from the mail)

  • mail.user.displayName = Your Name (display name from the mail)

  • mail.user.replyToAddress = Reply-To Address (address when replying to the mail)

These properties ensure that a specific mail address is the same in the external application and in the mail server. These properties are added to the Mail connection and are used by mail for the From, Display Name and Reply To fields.

For Exchange 2007 only, create an universal distribution list which means that the default property value of 2 should be updated to 8. Specify a value of 8 for the mail property mail.exchange.dl.group.type, as follows: 

setMailServiceProperty(appName='webcenter', property='mail.exchange.dl.group.type', value='8')

If your application offers a self-registration page with the facility to mail user ID information on request, then you must ensure that public credentials are configured for the external application selected here. If public credentials are not defined, then mail cannot be sent to users on their request. WebCenter Portal offers this feature on its default self-registration page.

For command syntax and examples, see setMailConnectionProperty in WebCenter WLST Command Reference.

To configure mail to use the new mail server connection as its default connection, set default=true. For more information, see Choosing the Active (or Default) Mail Server Connection Using WLST.

Note:

To start using new connections you must restart the managed server on which WebCenter Portal is deployed.

9.5 Choosing the Active (or Default) Mail Server Connection

You can register multiple mail server connections with WebCenter Portal, but only one connection can be designated as the default connection. The default connection becomes the back-end mail server for:

  • Mail task flows

  • WebCenter Portal distribution lists

  • Anywhere there is a Send Mail icon

This section includes the following subsections:

9.5.1 Choosing the Active (or Default) Mail Server Connection Using Fusion Middleware Control

To change the default connection:

  1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Portal.
  2. From the WebCenter Portal menu, select Settings > Service Configuration.
  3. On the WebCenter Portal Services Configuration page, select Mail Server.

    The Manage Mail Server Connections table indicates the current active connection, if any.

    Figure 9-4 Mail Server - Active Connection

    Description of Figure 9-4 follows
    Description of "Figure 9-4 Mail Server - Active Connection"
  4. Select the connection you want to make the active (or default) connection, and then click Edit.
  5. Select the Active Connection check box.
  6. Click OK to update the connection.
  7. To start using the new default connection you must restart the managed server on which WebCenter Portal is deployed.

9.5.2 Choosing the Active (or Default) Mail Server Connection Using WLST

Use the WLST command setMailConnection with default=true to make an existing mail server connection the default connection for mail. For command syntax and examples, see setMailConnection in WebCenter WLST Command Reference.

A connection does not cease to be the default connection for mail if you change the default argument from true to false.

To disable a mail connection, either delete it, make another connection the 'active connection', or use the removeMailServiceProperty command: 

removeMailServiceProperty(appName='webcenter', property='selected.connection')

Using this command, connection details are retained but the connection is no longer named as an active connection. For more information, see removeMailServiceProperty in WebCenter WLST Command Reference.

Note:

To start using the active connection you must restart the managed server on which WebCenter Portal is deployed.

9.6 Modifying Mail Server Connection Details

You can modify mail server connection details at any time.

To start using updated mail connections you must restart the managed server on which WebCenter Portal is deployed.

This section includes the following subsections:

9.6.1 Modifying Mail Server Connection Details Using Fusion Middleware Control

To update mail server connection details:

  1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Portal.
  2. From the WebCenter Portal menu, select Settings > Service Configuration.
  3. On the WebCenter Portal Service Configuration page, select Mail Server
  4. Select the connection name, and click Edit.
  5. Edit connection details, as required.

    Table 9-8 Mail Server Connection Details

    Field Description

    IMAP Host

    Enter the host name of the computer where IMAP (Internet Message Access Protocol) is running.

    IMAP Port

    Enter the port on which IMAP listens.

    IMAP Secured

    Indicate whether a secured connection (SSL) is required for incoming mail over IMAP.

    SMTP Host

    Enter the host name of the computer where SMTP (Simple Mail Transfer Protocol) is running.

    SMTP Port

    Enter the port on which SMTP listens.

    SMTP Secured

    Indicate whether a secured connection (SSL) is required for outgoing mail over SMTP.

    Associated External Application

    Associate the mail server with an external application. External application credential information is used to authenticate users against the IMAP and SMTP servers. Mail uses the same credentials to authenticate the user on both IMAP and SMTP.

    You can select an existing external application from the list, or click Create New to configure a new external application. For more information, see Managing External Applications.

    The external application for mail must use Authentication Method=POST, and you can customize some mail header fields (with Display to User enabled):

    • Property: mail.user.emailAddress (who the mail is from)

      Property: mail.user.displayName (display name from the mail)

      Property: mail.user.replyToAddress (address used to reply to the mail)

    These properties ensure that a specific mail address is the same in the external application and in the mail server. They are added to the mail connection and are used by mail for the From, Display Name and Reply To fields (Figure 9-3). See Table 9-7 for Additional Properties configuration.

    If your application offers a self-registration page with the facility to mail user ID information on request, then you must ensure that public credentials are configured for the external application selected here. If public credentials are not defined, then mail cannot be sent to users on their request. WebCenter Portal, for example, offers this feature on its default self-registration page.

  6. Click OK to save your changes.
  7. To start using updated connection details, restart the managed server on which WebCenter Portal is deployed.

9.6.2 Modifying Mail Server Connection Details Using WLST

Use the WLST command setMailConnection to edit existing mail server connection details. For command syntax and examples, see setMailConnection in WebCenter WLST Command Reference.

If additional parameters are required to connect to your mail server, use the setMailConnectionProperty command. For more information, see setMailConnectionProperty in WebCenter WLST Command Reference.

Note:

To start using the updated connections you must restart the managed server on which WebCenter Portal is deployed.

9.7 Deleting Mail Server Connections

You can delete mail server connections at any time, but use caution when deleting the active (or default) connection. If you delete the active connection, Mail task flows do not work, as they all require a back-end mail server.

When you delete a connection, consider deleting the external application associated with the mail server connection if the application's sole purpose was to support this connection. For more information, see Deleting External Application Connections.

This section includes the following subsections:

9.7.1 Deleting a Mail Connection Using Fusion Middleware Control

To delete a mail server connection:

  1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Portal.
  2. From the WebCenter Portal menu, select Settings > Service Configuration.
  3. On the WebCenter Portal Services Configuration page, select Mail Server.
  4. Select the connection name, and click Delete.
  5. To make this change, restart the managed server on which WebCenter Portal is deployed.

    Note:

    Before restarting the managed server, mark another connection as active; otherwise, mail is disabled.

9.7.2 Deleting a Mail Connection Using WLST

Use the WLST command deleteConnection to remove a mail server connection. For command syntax and examples, see deleteConnection in WebCenter WLST Command Reference.

9.8 Setting Up Mail Defaults

Use the WLST command setMailServiceProperty to set defaults for mail:

  • address.delimiter: Defines the delimiter that is used to separate multiple mail addresses. A comma is used by default.

    Some mail servers require mail addresses in the form lastname, firstname and, in such cases, a semicolon is required.

  • mail.emailgateway.polling.frequency: Frequency, in seconds, that portal distribution lists are checked for new incoming mail messages. The default is 1800 seconds (30 minutes).

    Email communication through WebCenter Portal distribution lists can be published as discussion forum posts on a discussions server. For details, see Publishing Portal Mail in a Discussion Forum in Building Portals with Oracle WebCenter Portal.

  • mail.messages.fetch.size: Maximum number of messages displayed in mail inboxes

  • resolve.email.address.to.name: Determines whether user email addresses are resolved to WebCenter Portal user names when LDAP is configured. Valid values are 1 (true) and 0 (false). The default value is 0.

    When set to 1, WebCenter Portal user names display instead of email addresses in Mail task flows.

  • mail.recipient.limit: Restricts the number of recipients to a message. For example, setting this value to '500' limits the number of recipients to 500.

For command syntax and examples, see setMailServiceProperty in WebCenter WLST Command Reference.

9.9 Testing Mail Server Connections

Confirm that the mail server is running by connecting to the server using any client, such as Thunderbird or Outlook.

9.10 Configuring Send Mail Notifications for WebCenter Portal

System administrators are responsible for setting mail options through WebCenter Portal administration settings.

Figure 9-5 Setting Mail Options

Description of Figure 9-5 follows
Description of "Figure 9-5 Setting Mail Options"

From this page, you can assign the mail client for the Send Mail feature. This feature allows application assets to send mail directly from their task flows, using the Send Mail icon (Figure 9-6).

Figure 9-6 Send Mail Icon

Send Mail icon

For example, from an announcement, users can click the Send Mail icon to open a mail window prepopulated with information including the announcement text, author, date created, and location. They can edit and add to the mail, as necessary. The way the mail window is prepopulated depends on the resource sending it. For example, from an announcement, Send Mail opens a mail window prepopulated with the title of the announcement.

Within a portal, the mail can be addressed to all members of the portal, which is the default distribution list that is created when the portal is created. Portal Mangers (and anyone granted the Manage Security and Configuration permission on the portal) set this through the Tools and Services page in the portal's administration settings. See Configuring the Mail Distribution List for a Portal in Building Portals with Oracle WebCenter Portal.

For all Send Mail notifications throughout WebCenter Portal, you can choose to use the local mail client, such as Microsoft Outlook or Mozilla Thunderbird, or WebCenter Portal's own Mail service. The local mail client is the default. The Send Mail feature does not require the Mail service, that is, if the Mail service is not yet configured, you can still use the Send Mail feature with WebCenter Portal's Mail service. Application specialists or portal managers can specify whether portal members can override the default mail client setting.

Note:

With some browsers, Send Mail notifications are garbled for many non-English languages. When multibyte characters are encoded (required for the "mailto:" protocol), the URL length exceeds the browser limit. As a workaround, configure the Send Mail feature to use WebCenter Portal's Mail service instead of the local mail client.

As the system administrator, you can also specify whether users can override the default mail client setting.

9.10.1 Enabling Shared Mail Connections for Send Mail Notifications

Users do not need to specify credentials while sending mail using WebCenter Portal's Mail service when shared credentials are configured for the external application associated with the mail server connection.

To enable shared mail connections:

  1. Ensure you have set up a mail connection that uses an external application configured with the shared credentials, and note down the mail connection name.

  2. Configure WebCenter Portal to use WebCenter Portal Mail service to send mail:

    1. On the Settings page (see Accessing the Settings Pages in WebCenter Portal Administration), click Tools and Services.

      You can also enter the following URL in your browser to navigate directly to the Tools and Services pages: 

      http://host:port/webcenter/portal/admin/settings/tools

      See Also:

      WebCenter Portal Pretty URLs in Building Portals with Oracle WebCenter Portal.

    2. Click the icon for Mail Settings.

    3. Under Default Mail Client for Send Mail, select WebCenter Portal's Mail Service.

    4. Click Apply.

Portal managers can now specify the name of the shared mail connection in the portals where shared mail credentials are required.