| Oracle® Fusion Middleware Administrator's Guide for Oracle WebCenter 11g Release 1 (11.1.1) E12405-05 |
|
 Previous |
 Next |
| Oracle® Fusion Middleware Administrator's Guide for Oracle WebCenter 11g Release 1 (11.1.1) E12405-05 |
|
Previous |
Next |
This chapter describes how to configure and manage the Mail service for WebCenter Spaces and custom WebCenter applications. It also describes how to configure the "Send Mail" feature, which allows application resources to send mail directly from them. The Send Mail feature does not require the Mail service. That is, even if the Mail service has not been configured in your application, users can send mail notifications with the local mail client. For more information on using the Send Mail notifications, see the section "What You Should Know About the Send Mail Feature" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter.
Always use Fusion Middleware Control or WLST command-line tool to review and configure back-end services for WebCenter applications. Any changes that you make to WebCenter applications, post deployment, are stored in MDS metatdata store as customizations. See Section 1.3.5, "Oracle WebCenter Configuration Considerations."
|
Note: Changes that you make to WebCenter services configuration, through Fusion Middleware Control or using WLST, are not dynamic so you must restart the managed server on which the WebCenter application is deployed for your changes to take effect. See Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments." |
This chapter includes the following sections:
Section 15.1, "What You Should Know About Mail Server Connections"
Section 15.4, "Choosing the Active (or Default) Mail Server Connection"
Audience
The content of this chapter is intended for Fusion Middleware administrators (users granted the Admin or Operator role through the Oracle WebLogic Server Administration Console). See also, Section 1.8, "Understanding Administrative Operations, Roles, and Tools."
WebCenter supports the Microsoft Exchange Server or any mail server that supports IMAP4 and SMTP. To enable WebCenter users to access mail within a WebCenter application and perform basic operations such as read, reply, and forward, you must first register the appropriate mail server with the WebCenter application. The Mail service is not configured out-of-the-box.
You can register multiple mail server connections:
WebCenter Spaces supports multiple mail connections. The mail connection marked active is the default connection for mail services in WebCenter Spaces. All additional connections are offered as alternatives; WebCenter Spaces users can choose which one they want to use through user preferences.
Custom WebCenter applications only use one mail connection—the connection marked active. Any additional connections are ignored.
This section includes the following subsections:
See your mail server documentation for installation information.
You can allow WebCenter to create and manage group space distribution lists in WebCenter Spaces (or in custom WebCenter applications leveraging WebCenter Spaces group space management). This feature is supported only with Microsoft Exchange. The group space distribution list is created automatically whenever a group space is created. Users added or removed from the group space are implicitly added or removed from the corresponding group space distribution list, provided users created on Microsoft Exchange Active Directory correspond with users created in the identity store used by the WebCenter application. To disable this feature, do not enter the LDAP (Active Directory) server details in the mail connection. For more information, see step 7 of Section 15.3.1, "Registering Mail Servers Using Fusion Middleware Control."
For information about adding users on a mail server, see the mail server's product documentation. For information about adding users to the WebCenter application's identity store, see Section 23.3, "Configuring the Identity Store."
Microsoft Exchange 2007 is the only mail server for which there are configuration prerequisites. If you are working with a different mail server (including Microsoft Exchange 2003), then you can skip the rest of this section.
The Microsoft Exchange Server 2007 certificate must be added to the WebCenter keystore. This requires the following steps.
Section 15.2.2.1.1, "Obtain the Certificate from the Microsoft Exchange Server 2007."
Section 15.2.2.1.2, "Add the Certificate to the WebCenter Keystore."
Restart the server after the certificate is imported.
Obtain the certificate from your mail server installation administrator. This section describes one way to get the certificate from the Microsoft Exchange Server 2007.
Follow these steps to obtain the certificate from a Microsoft Exchange 2007 server.
Open a browser and connect to your IMAP server with the following command:
https://host_name/owa
Where host_name is the name of the Microsoft Exchange Server 2007.
Place your cursor on the page, right-click, and select Properties, then click Certificate.
In the popup window, click the Details tab, and click Copy to File...
Be sure to use the DER encoded binary (X.509) format, and copy to a file.
Convert the .DER format certificate to .PEM format.
|
Note: WebLogic only recognizes .PEM format. |
Use Firefox 3.0 or later to download the certificate directly to .PEM format. For other browsers, use the WebLogic Server der2pem tool to convert to .PEM format. For more information about der2pem see the Oracle Fusion Middleware Command Reference for Oracle WebLogic Server.
Import the downloaded certificate into the keystore, which is generally the file named cacerts in the JAVA_HOME. For example:
keytool -import -alias imap_cer -file cert_file.cer -keystore cacerts -storepass changeit
Where cert_file is the name of the certificate file you downloaded. In a standard installation, the JAVA_HOME is in the following location:
/scratch/wcinstall/ps2/1225/wlshome/jrockit_160_17_R28.0.0-616
See Section 23.7.3.2.2, "Generating and Registering Certificates," for information about adding the certificate to the keystore.
Restart the server.
The IMAP port is 993 and secured true. SMTP port is 587 and secured true.
(Microsoft Exchange Server 2005 used 465.)
If you see the following error, then you must change the trust store entry in the domain startup file setDomainEnv.sh:
Caused by: java.io.IOException: Keystore was tampered with, or password was incorrect at sun.security.provider.JavaKeyStore.engineLoad(JavaKeyStore.java:771) at sun.security.provider.JavaKeyStore$JKS.engineLoad(JavaKeyStore.java:38) at java.security.KeyStore.load(KeyStore.java:1185) at com.sun.net.ssl.internal.ssl.TrustManagerFactoryImpl.getCacertsKeyStore (TrustManagerFactoryImpl.java:202) at com.sun.net.ssl.internal.ssl.DefaultSSLContextImpl.getDefaultTrustManager (DefaultSSLContextImpl.java:70)
To change the entry:
Shutdown the managed server on which WebCenter is deployed.
Edit the domain startup script setDomainEnv located at:
Unix: DOMAIN_HOME/bin/setDomainEnv.sh
Windows: DOMAIN_HOME\bin\setDomainEnv.cmd
Add the Java property, as follows:
-Djavax.net.ssl.trustStore=<path to truststore> -Djavax.net.ssl.trustStorePassword=<truststore password>
For example:
set JAVA_PROPERTIES=-Dplatform.home=%WL_HOME% -Dwls.home=%WLS_HOME%Â -Dweblogic.home=%WLS_HOME% -Djavax.net.ssl.trustStore=C:\jive\mailtool\jssecacerts -Djavax.net.ssl.trustStorePassword=changeit
Restart the managed server.
For more information, see Section 23.6.8, "Securing the WebCenter Spaces Connection to IMAP and SMTP with SSL."
|
Note: If LDAP is configured to run in secure mode, then add theLDAP Secured property (set to true/false) to use LDAP while creating distribution lists. For more information, see Table 15-3. |
In WebCenter Spaces, the Mail service requires a Microsoft Exchange mail server connection to enable automatic group space distribution lists.
You can register multiple mail server connections. To start using the new mail connections you must restart the managed server on which the WebCenter application is deployed.
This section includes the following subsections:
To register a mail server with WebCenter applications:
Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or the custom WebCenter application. For more information, see:
Do one of the following:
For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.
For WebCenter applications - From the Application Deployment menu, choose WebCenter > Service Configuration.
From the list of services on the WebCenter Service Configuration page, select Mail Server.
To connect to a new mail server, click Add (Figure 15-1).
Enter a unique name for this connection, and indicate whether this connection is the active (or default) connection for the application (Table 15-1).
Table 15-1 Mail Server Connection - Name
| Field | Description |
|---|---|
|
Name |
Enter a unique name for the connection. The name must be unique (across all connection types) within the WebCenter application. |
|
Active Connection |
Select to indicate whether this connection is the default (or active) connection for the Mail service. You can register multiple mail server connections:
|
Enter connection details for the mail server (Table 15-2).
Table 15-2 Mail Server Connection Parameters
| Field | Description |
|---|---|
|
IMAP Host |
Enter the host name of the computer where the IMAP (Internet Message Access Protocol) service is running. |
|
IMAP Port |
Enter the port on which the IMAP service 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 the SMTP (Simple Mail Transfer Protocol) service is running. |
|
SMTP Port |
Enter the port on which the SMTP service listens. |
|
SMTP Secured |
Indicate whether a secured connection (SSL) is required for outgoing mail over SMTP. |
|
Associated External Application |
(Mandatory) Associate the mail server with an external application. External application credential information is used to authenticate users against the IMAP and SMTP servers. The Mail service 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. The external application you configure for the Mail service must use the If your WebCenter 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 mails cannot be sent to users on their request. WebCenter Spaces offers this feature on its self-registration page. |
Specify LDAP connection details for the Active Directory server managing group space distribution lists (Table 15-3).
This section applies to WebCenter Spaces (or custom WebCenter applications leveraging the WebCenter Spaces group space management feature). WebCenter applications support 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 group space distribution lists to work. |
Table 15-3 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, |
|
LDAP Domain |
Enter the domain to be appended to distribution list names. In WebCenter Spaces, 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 moderation capabilities. These users become members of every group space distribution list that is created. The users specified must exist in the base LDAP schema (specified in the |
|
LDAP Secured |
Indicate whether a secured connection (SSL) is required between the WebCenter application and the LDAP directory server. |
Configure advanced options for the mail server connection (Table 15-4).
Table 15-4 Mail Server Connection - Advanced Configuration
| Field | Description |
|---|---|
|
Connection Timeout (in Seconds) |
Specify a suitable timeout for the connection. This is the length of time (in seconds) the WebCenter application waits for a response from the mail server before issuing a connection timeout message. The default is -1, which means that the service default is used. The service default is 10 seconds. |
Optionally, you add can more parameters to the mail server connection (Table 15-5).
Table 15-5 Additional Mail Connection Properties
| Additional Connection Property | Description |
|---|---|
|
Various IMAP properties |
Any valid IMAP connection property. For example, For a list of valid protocol properties, see your mail server documentation. For a list of standard IMAP properties, see the Java Mail APIs:
|
|
Various SMTP properties |
Any valid SMTP connection property. For example, For a list of valid protocol properties, see your mail server documentation. For a list of standard SMTP properties, see the Java Mail APIs:
|
If additional parameters are required to connect to the mail server, expand Additional Properties and enter details as required (see Table 15-6, "Mail Connection - Additional Properties").
Table 15-6 Mail Connection - Additional Properties
| Field | Description |
|---|---|
|
Add |
Click Add to specify an additional connection parameter:
|
|
Delete |
Click Delete to remove a selected property. Select the correct row before clicking Delete. Note: Deleted rows appear disabled until you click OK. |
Click OK to save this connection.
To start using the new (active) connection you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."
Use the WLST command createMailConnection to create a mail server connection. For command syntax and examples, see the section, "createMailConnection" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
To configure the Mail service to use the new mail server connection as its default connection, set default=true. For more information, see Section 15.4.2, "Choosing the Active (or Default) Mail Server Connection Using WLST."
For information on how to run WLST commands, see Section 1.12.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."
|
Note: To start using new connections you must restart the managed server on which the WebCenter application is deployed. For more information, see the section, "Starting and Stopping WebLogic Managed Servers Using the Command Line" in the Oracle Fusion Middleware Administrator's Guide. |
You can register multiple mail server connections with a WebCenter application but only one connection can be designated as the default connection.
For WebCenter Spaces and custom WebCenter applications, the default connection becomes the back-end mail server for:
Mail task flows
Group space distribution lists
Anywhere there is a Send Mail icon
This section includes the following subsections:
To change the default connection:
Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or the custom WebCenter application. For more information, see:
Do one of the following:
For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.
For WebCenter applications - From the Application Deployment menu, choose WebCenter > Service Configuration.
From the list of services on the WebCenter Services Configuration page, select Mail Server.
The Manage Mail Server Connections table indicates the current active connection (if any).
Select the connection you want to make the active (or default) connection, and then click Edit.
Select the Active Connection checkbox.
Click OK to update the connection.
To start using the new default connection you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."
Use the WLST command setMailConnection with default=true to make an existing mail server connection the default connection for the Mail service. For command syntax and examples, see the section, "setMailConnection" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
A connection does not cease to be the default connection for the Mail service 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 the section, "removeMailServiceProperty" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
For information on how to run WLST commands, see Section 1.12.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."
|
Note: To start using the active connection you must restart the managed server on which the WebCenter application is deployed. For more information, see the section, "Starting and Stopping WebLogic Managed Servers Using the Command Line" in the Oracle Fusion Middleware Administrator's Guide. |
You can modify mail server connection details at any time.
To start using updated mail connections you must restart the managed server on which the WebCenter application is deployed.
This section includes the following subsections:
Section 15.5.1, "Modifying Mail Server Connection Details Using Fusion Middleware Control"
Section 15.5.2, "Modifying Mail Server Connection Details Using WLST"
To update mail server connection details:
Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or the custom WebCenter application. For more information, see:
Do one of the following:
For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.
For WebCenter applications - From the Application Deployment menu, choose WebCenter > Service Configuration.
From the list of services on the WebCenter Service Configuration page, select Mail Server
Select the connection name, and click Edit.
Edit connection details, as required. For detailed parameter information, see Table 15-2, "Mail Server Connection Parameters".
Click OK to save your changes.
To start using updated connection details you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."
Use the WLST command setMailConnection to edit existing mail server connection details. For command syntax and examples, see the section, "setMailConnection" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
If additional parameters are required to connect to your mail server, use the setMailConnectionProperty command. For more information, see the section, "setMailConnectionProperty" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
For information on how to run WLST commands, see Section 1.12.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."
|
Note: To start using the updated connections you must restart the managed server on which the WebCenter application is deployed. For more information, see the section, "Starting and Stopping WebLogic Managed Servers Using the Command Line" in the Oracle Fusion Middleware Administrator's Guide. |
You can delete mail server connections at any time but take care 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 Section 22.5, "Deleting External Application Connections."
This section includes the following subsections:
To delete a mail server connection:
Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or the custom WebCenter application. For more information, see:
Do one of the following:
For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.
For WebCenter applications - From the Application Deployment menu, choose WebCenter > Service Configuration.
From the list of services on the WebCenter Services Configuration page, select Mail Server.
Select the connection name, and click Delete.
To effect this change you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."
|
Note: Before restarting the managed server, mark another connection as active; otherwise, the service is disabled. |
Use the WLST command deleteConnection to remove a mail server connection. For command syntax and examples, see the section, "deleteConnection" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
For information on how to run WLST commands, see Section 1.12.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."
Use the WLST command setMailServiceProperty to set defaults for the Mail service:
mail.messages.fetch.size: Maximum number of messages displayed in mail inboxes
resolve.email.address.to.name
For command syntax and examples, see the section, "setMailServiceProperty" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
For information on how to run WLST commands, see Section 1.12.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."
Confirm that the mail server is up by connecting to the server using any client, such as Thunderbird or Outlook.
For Microsoft Exchange, go to Administrative Tools - Services to confirm that the following services are running (Status: Started):
Microsoft Exchange IMAP4
Simple Mail Transfer Protocol (SMTP)
As the WebCenter Spaces administrator, you are responsible for setting mail options through WebCenter Spaces Administration (Figure 15-2).
From this page, you can assign the mail client for the "Send Mail" feature. This feature allows application resources to send mail directly from them, with the Send Mail icon (Figure 15-3).
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 your Buddies list, users can click the Send Mail icon to open a mail window prepopulated only with the address of that person.
With group spaces, the mail can be addressed to the individual members of the group space, and, if the group space is configured with a distribution list, then it can be addressed to the distribution list. Group space moderators select the default for Send Mail actions (whether mails should be addressed to a distribution list, or individual member mail addresses, or both, or none) on the Settings - Services - Mail page.
|
Note: When the Send Mail icon is clicked from a group space with a large number of members, length restrictions may prevent the local mail client from prepopulating the addresses of all group space members. The user gets an error and must enter the addresses manually. To avoid this error, configure a distribution list for the group space. |
For all Send Mail notifications throughout WebCenter, you can choose to use either a local mail client or the WebCenter Mail service. The local mail client is the default. The Send Mail feature does not require the Mail service. That is, even if the Mail service has not been configured in your application, you can use the Send Mail feature with your local mail client.
The local mail (mailto) client allows plain text editing of the mail, but it does not allow attachments. Due to the limitations with the mailto URL (used for launching the local mail client), the text could be truncated.
The WebCenter Mail service launches the Mail Compose window. Although users cannot edit the prepopulated HTML (shown as the content.html attachment), they can view the prepopulated attachment, add other attachments, and add plain text to the compose window. If the WebCenter Mail service has not been configured in your application, then this option does not appear on the page.
You can select the checkbox to enable users to override the default mail client setting.
|
Note: The Fusion Middleware administrator maintains the connection between WebCenter Spaces and the mail server. If you are experiencing issues with this connection, report the problem to the Fusion Middleware Administrator. See also, Section 15.3, "Registering Mail Servers." |
This section includes the following subsections:
Section 15.10.1, "Mail Service is Not Accessible in Secure Mode"
Section 15.10.2, "Mail Service is Not Accessible in Non-Secure Mode"
Section 15.10.3, "Unable to Create Distribution Lists in the Non-Secure Mode"
Section 15.10.4, "Unable to Create Distribution Lists in the Secure Mode"
Section 15.10.5, "Unable to Configure the Number of Mails Downloaded"
Section 15.10.6, "Unable to Publish and Archive Group Space Mail"
Problem
You configured the Mail service to function in secure mode, but the service is not accessible.
Solution
Ensure the following:
IMAP and SMTP ports are specified correctly. See Section 15.3, "Registering Mail Servers."
Properties are set to true in your mail server.
mail.imap.Secured = true
mail.smtp.Secured = true
Problem
You configured the Mail service to function in non-secure mode, but the service is not accessible.
Solution
Ensure the following:
IMAP and SMTP ports are specified correctly. See, Section 15.3, "Registering Mail Servers."
Properties are set to false in your mail server.
mail.imap.Secured = false
mail.smtp.Secured = false
Problem
You are unable to create group space distribution lists in non-secure mode (SSL not configured).
Solution
Check if the mail server has been reinstalled or the user has been deleted. Also ensure that the following parameters are configured accurately in non-secure mode, in the LDAP server:
ldapHost
defaultUser
ldapAdminPassword
ldapBaseDN
ldapPort
Problem
You are unable to create group space distribution list in secure mode, that is, SSL is configured on the LDAP server.
Solution
Check if the mail server has been reinstalled or the user has been deleted. Also ensure that the following parameters are configured accurately in secure mode, in the LDAP server:
ldapHost
defaultUser
ldapAdminPassword
ldapBaseDN
ldapPort
ldap.connection.secure, 'true'
Problem
You cannot configure how many mails are downloaded to each user's Inbox.
Solution
Use the setMailServiceProperty WLST command. For example, to download 100 mails from the mail client, specify the mail.messages.fetch.size parameter as 100, as shown in the following example:
setMailServiceProperty(appName='webcenter', property='mail.messages.fetch.size', value='100')
For command syntax and examples, see "setMailServiceProperty" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Problem
You are unable to archive group space mail.
Solution
If the archiving fails, check the following:
In WebCenter Spaces, open WebCenter Administration pages, navigate to the Services tab, and then choose Discussions. Check whether the required configuration is accurate. See also, Section 12.10.3, "Enabling Discussion Forums to Publish Group Space Mail."
Check whether the user account configured here is a member of the distribution list.
For a particular group space, check whether the forum configured is available in the discussions server. See "Publishing Group Space Mail in a Discussion Forum" in Oracle Fusion Middleware User's Guide for Oracle WebCenter.
Check whether the user who sends mails to the distribution list is available in the discussions server and his mail address is the same.
Problem
If multiple users log on to Microsoft Exchange with the same user name and password, and then one user changes the password, the original password remains valid until all users log off.
For example, say the current password of the user monty is welcome1. Two users, A and B, log on from different clients using either WebCenter or Microsoft Exchange. Both log on as monty/welcome1, and both are able to see the mails. Now user A changes the password in Microsoft Exchange to oracle1. Because there currently are clients using the passwords oracle1 and welcome1, both are valid passwords; that is, new users can log on as monty/welcome1 and still see the mails.
Solution
After all existing users with the original password log off, the new password takes effect. Until then, users can use both passwords to log on.
