Setting Up Integration with Third-Party Email and Calendar Systems

This chapter provides overviews of the Email pagelet and Calendar Events pagelet, basic email and calendar setup steps, application and mail server configuration, and the Microsoft Exchange/Outlook integration. This chapter also discusses how to:

• Integrate with Microsoft Exchange 2003 and 2007.

• Integrate with Lotus Domino email and calendar.

• Configure the server for POP mail and IMAP mail.

• Assign primary mail systems.

• Set up additional mail systems.

Understanding Basic Email and Calendar Setup Steps

The following steps provide a roadmap for setting up the Email pagelet and Calendar Events pagelet.

Note. Detailed setup instructions for each third-party email system are described later in this chapter.

1. The portal administrator configures application and email servers.

   • Lotus Domino.

     Install the delivered PeopleSoft jar file, com.peoplesoft.pa.pp.jar on the application server.

     Copy the Lotus Dominao NCSO.jar file to the application server.

     Make the relevant changes on the Domino server end and perform other operating-system-related setting changes.

     See Integrating With Lotus Notes Email and Calendar.

   • Microsoft Exchange.

     Install the delivered PeopleSoft Active Server Page files in the relevant places and change the security.

     See Integrating With Microsoft Exchange 2003 and 2007.

   • POP mail.

     Download and install the required files from the Java site.

     Install the delivered PeopleSoft jar file, com.peoplesoft.pa.pp.jar on the application server. Enter the POP mail server name and the URL for the POP mail inbox on the Email and Calendar Defaults page.

     See Integrating With a POP Server.

   • IMAP mail.

     Download and install the required files from the Java site.

     Install the delivered PeopleSoft jar file, com.peoplesoft.pa.pp.jar on the application server.

     Enter the IMAP mail server name and the URL for the IMAP mail inbox on the Email and Calendar Defaults page.

     See Configuring the Primary Email System to Use IMAP.

2. The portal administrator and individual users complete the integration with the Email pagelet and Calendar Events pagelet:

   1. The portal administrator selects and sets up the primary email and calendar on the E-mail and Calendar Defaults page.

      See Designating the Primary Mail System.

   2. Each user sets up the pagelet's user ID and password.

Understanding Application and Mail Server Configuration

In accordance with the primary email and calendar systems that are selected for the Email pagelet and Calendar Events pagelet, system administrators must configure servers with special settings, files, and views. It might also be necessary to configure the servers for any additional POP mail systems.

This chapter provides information about setting up the following supported applications and mail server configurations:

• Microsoft Exchange/Outlook 2003 and 2007 Email and Calendar on Windows.

• Lotus Domino 6.5, 7.0, and 8.0 Email and Calendar.

• POP mail.

• IMAP mail.

See Also

Setting Up Additional Mail Systems

Enterprise PeopleTools 8.50 PeopleBook: PeopleTools Portal Technology, "Administering Portals"

Integrating With Microsoft Exchange 2003 and 2007

This section provides an overview of prerequisites for integrating with Exchange 2003 and discusses:

• How to install and configure ASP files for Microsoft Exchange 2003 and 2007.

• Implementation tips for integrating with Microsoft Exchange 2003 and 2007.

Understanding Integration with Microsoft Exchange

The Email pagelet on the portal homepage can display email from Microsoft Exchange when it is designated as the primary mail system. It requires Outlook Web Access (OWA), which enables access to Outlook using a browser. OWA requires that a Microsoft Internet Information Server (IIS) be running with access to an Exchange server. PeopleSoft Enterprise Portal supports integration with Microsoft Exchange/Outlook 2003 and 2007 on Windows.

In the PeopleCode, an iScript makes a request to the ASPs on the Exchange server. The ASPs send back a response in HTML format. PeopleCode then extracts the HTML to get the relevant email and calendar data and then formats the information and displays it in the Email and Calendar Events pagelets.

On the Exchange server side, ASPs, based on the WebDAV (Web-based distributed authoring and versioning) protocol are installed. You can search the Microsoft website to learn more about WebDAV.

See Also

Integrating With Microsoft Exchange 2003 and 2007

Prerequisites

Before integrating Microsoft Exchange with the PeopleSoft Enterprise Portal, you must:

• Plan for the functionality that you need.

• Install the Windows 2003 server and related systems.

  Exchange must be installed in a domain that contains a Windows 2003 server that is configured as a domain controller with a global catalog.

  Note. During the Windows 2003 server setup, you must install the Network News Transfer Protocol (NNTP) service.

• Install the Microsoft Exchange 2003 or Microsoft Exchange 2007 server. Refer to the installation guide.

• Create mailboxes for users on the Exchange server.

  Select Active Directory Users and expand the domain name to see the Users folder.

Installing and Configuring Active Server Page Files for Exchange

You can perform the following steps only after the Microsoft Exchange server has been installed.

To install and configure ASP files:

1. Create a new folder, such as c:\aspcode, on the Microsoft Exchange machine.

2. Copy the following files into the newly created folder:

   • For Microsoft Exchange 2003:

     Psmsinbox2003.asp

     Psmcal2003_1day.asp

   • For Microsoft Exchange 2007:

     Psmsinbox2007.asp

     Psmcal2007_1day.asp

3. Map the new folder to the Virtual Directory for Exchange 2003/2007 using Microsoft Internet Services Manager (ISM):

   1. Access ISM from your Windows machine by navigating to Start, Programs, Administrative Tools.

   2. Expand the left-side Domain name folder to see the Default Web Site folder.

   3. Right-click and select New, Virtual Directory.

      This starts a wizard, which takes you through the relevant steps.

   4. In the wizard, select the folder that contains all of the PeopleSoft ASP files as the source (for example, c:\aspcode).

      It is important that you select the same folder in which you installed the delivered PeopleSoft ASP files.

   5. For easy reference, give the virtual directory the same name as the folder in which you installed the delivered ASP files (for example, aspfolder).

      Note. Once you have mapped the folder to the virtual directory, you will see your virtual directory and its contents in the ISM folder's Default Web Site.

4. Ensure that the Basic Authentication value is used as the directory security for the virtual directory.

   1. Access ISM from your Windows machine by navigating to Start, Programs, Administrative Tools.

   2. Go to the Default Web Site in the domain folder and find your mapped virtual directory, as specified in step 3e.

   3. Right-click and select Properties.

   4. Select the Directory Security tab and select Anonymous Access and Authentication.

   5. Select Basic Authentication.

Important! The URL that you use on the Email and Calendar Defaults page must use the format http://<servername>/<aspfolder>, where aspfolder is the folder name that is used in the virtual directory specified above. If this folder name is not the virtual folder name, the integration will not work.

When the configuration of applications and mail servers is complete, proceed to assigning the primary mail system in the PeopleSoft Enterprise Portal.

See Designating the Primary Mail System.

Implementation Tips for Configuring Exchange

If the pagelet cannot display the messages, but the Microsoft Outlook link on the pagelet works, check the following:

1. In the browser, enter a URL using the following format, replacing the domain and user ID with the individual user's email account and user ID:

   http://<Outlook Web Access server name>/aspfolder/Psmsinbox2003.asp?
   mailbox=<userid>&exchsvr=
   <Exchange Server name>&numrows=5 

   For Microsoft Exchange 2007 replace 2003 with 2007.

2. If there is an error on this website (that is, on an ASP page), then the folder in which you stored the delivered PeopleSoft ASP files is not properly mapped as a virtual drive.

   If the virtual drive is correctly mapped, but this URL site still generates errors that are MAPI-related, then check the IMS security to ensure that the Basic Authentication value has been selected.

   See Installing and Configuring Active Server Page Files for Exchange.

3. If after changing the security you still receive MAPI-related errors when trying to access the above URL, then perform the following verifications on the Members Of tab of the User Properties in Active Directory Users and Computers.

   1. Navigate to the Members Of tab by going to Windows Start, Programs, Administrative Tools, Active Directory Users and Computers.

   2. Select the Users folder in the left-side domain folder.

   3. Right-click the appropriate user and select Properties.

   4. On the Members Of tab, look at all domains for which the user is a member and try to make the user a member of the relevant domains and directories.

      Correcting the Member Of properties can resolve several MAPI-related permission issues with the above URL.

Identifying Typos in Output Parameters

Make the following setting changes to display debugging information on the pagelet. It displays data that is being sent. Check the accuracy of this data.

To identify typos in output parameters:

1. In PeopleSoft Application Designer, open the record WEBLIB_EMAIL.

2. Open the FieldFormula PeopleCode.

3. Search for the following iScript function:

   Function IScript_mail()

4. Locate the second line of the function:

   &Debug = False; 

5. Set the value to True.

6. The set of statements should now look like the following:

   Function IScript_mail()
      /* Set the debug flag to True, for getting all the debug information, 
   		/* otherwise set it to false */
      ​&Debug = True;
      &titleStyle = "PABOLDBLUETEXT";
   

7. Save. The debugging information will display on the pagelet.

Ensuring That Microsoft Exchange is Working Over the Web

To ensure that Microsoft Exchange is working:

1. Click the Microsoft Outlook link that displays on the Email pagelet.

2. Supply the user ID and password in the dialog box.

   Ensure that you use the <DOMAIN NAME><User Id> format when specifying a user outside of the domain in which the Microsoft Exchange server resides.

3. If this link opens a web-based outlook, then proceed to the next section. If the link does not open, then contact the Exchange server administrator.

Checking the Outlook Web Access URL

To verify that the Outlook Web Access URL is working:

1. Use the following format for an Outlook Web Access URL:

   http://<Outlook Web Access name>/aspfolder/Psmsinbox2003.asp?
   mailbox=<userid>&exchsvr=
   <Exchange Server name>&numrows=5 

   For Microsoft Exchange 2007 replace 2003 with 2007.

2. Open a new browser window and enter the appropriate URL for your version of Exchange. Login when prompted. Tabular data consisting of mail headers should be returned.

   If this step does not work, then the errors may possibly be the result of a setup issue. Return to the Exchange administration steps to verify the setup issues.

   See Installing and Configuring Active Server Page Files for Exchange.

   If this step works, but email is still not accessible, then add a few emails to the account and try again.

   If this is working, then try the next section.

Understanding Browser Errors

This section explains several browser error messages that may display for the Email pagelet integration, along with possible associated errors.

• Page cannot be found error.

  This error screen could mean that the file psmsinbox2003.asp (or psmsinbox2003.asp) is not available. This can happen because:

  • Either the file is missing, or because the virtual folder is wrong or not mapped correctly.

  • There's a typographical error in the file name.

• Network password error.

  If the Enter Network Password dialog box displays after executing the OWA that was formed, it may be because the domain name, user ID, or password entered for the user is missing or wrong.

• Page cannot be displayed error.

  This page can display under two circumstances.

  • If this page appears when you place the OWA URL in the browser, verify that the OWA server name is correct.

  • This page can also appear when the URL tries to access a resource that does not exist due to a wrong mailbox or a wrong Microsoft Exchange server name.

• You are not authorized to view this page.

  This page appears if the either the user ID or password are incorrect.

Integrating With Lotus Notes Email and Calendar

This section provides overviews of the Lotus Notes email and calendar integration and prerequisites, and discusses how to integrate with a Lotus Domino server to retrieve email and calendar information.

Understanding Integration with Lotus Notes Email and Calendar

The Email pagelet on the PeopleSoft Enterprise Portal homepage can display email from Lotus Domino server when Lotus is designated as the primary mail system. Integration requires a specific configuration of the portal application server and a hub Domino server.

How the Integration Works

PeopleSoft Enterprise Portal integrates with Lotus Notes mail files to retrieve an individual’s email and calendar appointment lists. To retrieve this information from each user’s mail file, PeopleSoft Enterprise Portal uses the Notes Client Side Objects (NCSO) to interact with the Domino server. The NCSO uses Internet Inter-ORB Protocol (IIOP) to exchange data and communicate internally. A server task needs to be set up on the Lotus Domino server to work with the Domino Object Request Broker DIIOP (Domino Internet Inter-ORD Protocol) to allow the internal communication.

Enabling iNotes

iNotes is the web-enabled solution for Lotus Notes. To enable users to launch iNotes from the Email pagelet, you must specify the iNotes URL on the Email and Calendar Defaults page.

Prerequisites

The following prerequisites must be in place:

• All mail files at an organization must refresh from a single mail file template, or there must be some other easy way for a Lotus Notes administrator to add two hidden custom views to each user's mail file.

• There is a single Domino server that can run both the HTTP and DIIOP tasks for access by the portal.

  This server should use Java security and have the corporate name and address book on it.

• All users at the organization have an internet password stored in their Person document in the Lotus Name and Address Book on the Domino hub server.

• A custom view that is added to the address book provides the location and file name of each user's mailbox

Integrating With Lotus Notes

Complete the steps outlined in this section to configure the Lotus Notes email and calendar functions.

Placing the NCSO.Jar file on the Application Server Machine

To place the NCSO.Jar file on the application server machine:

1. Copy the Lotus Domino NCSO.jar file from LOTUS_HOME\Domino\data\domino\java\NCSO.jar.

2. Place the NCSO.jar file on the PeopleSoft application server in the appropriate directory.

   For Windows-based application servers place the file in PS_CFG_HOME\class\.

   For UNIX-based application servers place the file in PS_CFG_HOME/appserv/classes/.

3. Add the NCSO.jar and com.peoplesoft.pa.pp.jar files to the environment variable CLASSPATH.

Completing the Lotus Notes Integration

After setting up your Lotus Notes client application servers, complete the following Lotus Notes setup steps.

This section discusses how to:

• Configure the Lotus Domino server.

• Place custom views in Lotus templates.

See Also

Designating the Primary Mail System

Configuring the Lotus Domino Server

To configure the Lotus Domino Server:

1. Configure Java/COM Restrictions on the Lotus Domino Server

2. Enable IIOP

3. Set up Session Based Authentication

4. Verifying Web settings

Configuring Java/COM Restrictions on the Lotus Domino Server

To configure Java/COM restrictions on the Lotus Domino server:

1. Access the Lotus Domino Administrator.

2. Select Configuration tab from the navigation bar.

3. Select Server.

4. Double click your server name from the list (or on current server document if you have only one server).

5. Select Edit Server.

6. Click on the Security tab.

7. Scroll to the section labeled Run restricted Java/Javascript/COM and enter an asterisk character (*) in the text area provided.

8. Scroll to the section labeled Run unrestricted Java/Javascript/COM and enter an asterisk character (*) in the text area provided.

9. Click on the Save and Close link.

Enabling IIOP

The Lotus Notes Pagelets implementation uses the Notes Client Side Objects to communicate with the Lotus Domino server. The Notes Client Side Objects internally use IIOP (Internet Inter-ORB Protocol) to communicate and exchange object data. To allow this communication, a server task that runs on the Lotus Domino Server and works with the Domino Object Request Broker DIIOP (Domino Internet Inter-ORB Protocol) needs to be enabled.

To enable IIOP:

1. Access the Lotus Domino Administrator.

2. Select the Configuration tab.

3. Double click your server name from the list (or on current server document if you have only one server).

4. Select the Ports: Internet Ports tab.

5. Click on the DIIOP tab to go to the IIOP Server screen.

6. Verify that TCP/IP Port number is 63148 (default port).

7. Verify that TCP/IP Port status is Enabled.

   If not, then select Enabled and click Save and Close to save the changes.

8. Now, if it is not already started, start the DIIOP server task on the Lotus Domino Server.

   To start the DIIOP server task, enter this command on Lotus Domino Server console: load diiop.

Setting Up Session Based Authentication

Before publishing the Lotus Notes Pagelets, you need to set up Session Based Authentication for Web clients who have access to a Domino Web server.

To set up session based authentication:

1. Access the Lotus Domino Administrator.

2. Select Configuration tab from the navigation bar.

3. Select Server.

4. Double click your server name from the list (or on current server document if you have only one server).

5. Select Edit Server.

6. Select Internet Protocols: Domino Web Engine.

7. In the HTTP Sessions section, for Session Authentication, select Single Server.

8. Click on Save and Close.

Verifying Web settings

To verify web settings:

1. Access the Lotus Domino Administrator.

2. Select the Configuration tab from the navigation bar.

3. Select Server.

4. Double click your server name from the list (or on current server document if you have only one server).

5. Select Edit Server.

6. Select the Ports: Internet Ports: Web tab.

7. Under Authentication Options select Yes for the Anonymous option.

Placing Custom Views in Lotus Templates

To place custom views in Lotus templates:

1. The portal administrator sends the Portal_Lotus_Views.nsf file to the Lotus Notes administrator.

   This file is provided on the PeopleSoft Enterprise Portal CD and can be found in PS_HOME in the scripts folder.

   The Lotus Notes Administrator performs the following steps.

2. Open the Portal_Lotus_Views.nsf file in the Lotus Domino Designer.

3. Copy the two views, PS_PORTAL_MAIL and PS_PORTAL_CALENDAR, into the mail file template that is used for all mail files in the organization.

4. Copy the view PS_PORTAL_MAIL_LOCATION either into the Name and Address Book template in the organization (if one is used) or into the Name and Address Book of the hub Domino server that the portal application server accesses to retrieve user mail file information.

   1. If the organization uses customized Domino user names that are not any of the entries listed in the User Name field of the Person document in the Name and Address Book, then customize the PS_PORTAL_MAIL_LOCATION view that you just copied.

   2. To customize this view, open it in Lotus Domino Designer and change the first column of the view to reflect the customized Domino user names used in the organization.

      For example, if the entries in the User Name field are John Smith/ACME Corp and John Smith, but a custom Domino user name of jsmith is used, the column formula is @Left(FirstName;1)+LastName.

   3. Change the first column of the PS_PORTAL_MAIL_LOCATION view only if the system uses custom Domino user names that are not any of the entries in the User Name field.

Integrating With a POP Server

This section provides an overview of post office protocol (POP) configuration and prerequisites, and discusses how to extract .jar files.

Understanding POP Configuration

The setup for POP mail is optional. It is required only when the portal administrator has designated a primary mail system that is POP-based or has set up additional email selections for the email pagelet. POP mail requires correct placement of third-party .jar files from the Sun website to the portal application server.

POP mail integration requires the following:

• If you access POP mail on an internal mail server, that mail server must be POP-enabled.

• If you access POP mail from an external mail system, the remote POP mail server to which you point must be POP-enabled.

  Also, users must set up their external mail accounts to POP forward.

Extracting .jar Files for POP Email Integration

This section discusses how to extract the following Sun .jar files into the <PS_CFG_HOME>\class Directory of the NT portal application server:

• mail.jar

• activation.jar

• pop3.jar

Note. When you transfer .jar files, be sure to use binary transfers, not ASCII transfers. Also, you must install the required Java files in the proper directory for each portal application server.

Extracting mail.jar (JavaMail)

To download mail.jar:

1. FTP download mail.jar (JavaMail) from http://www.javasoft.com/products/javamail/index.html.

2. Extract the mail.jar file into the PS_CFG_HOME\class directory on each portal application server.

3. Delete the javamail1_1_3.zip file.

Extracting activation.jar (JavaBeans Activation Framework)

To download activation.jar:

1. FTP download activation.jar (JavaMail) from http://www.javasoft.com/products/javamail/index.html.

2. Extract the activation.jar file into the PS_CFG_HOME\class directory on each portal application server.

3. Delete the jaf1_0_1.zip file.

Extracting pop3.jar (POP3 Provider)

To download pop3.jar:

1. FTP download pop3.jar (POP3 Provider) from http://www.javasoft.com/beans/glasgow/jaf.html.

2. Extract the pop3.jar file into the PS_CFG_HOME\class directory on each portal application server.

3. Delete the pop31_1_1.zip file.

Note. The Sun Microsystems website from which the drivers are downloaded is external to PeopleSoft, and its content and layout might change at any time. For assistance in locating files on the Sun Microsystems website, contact Sun Microsystems.

Integrating With an IMAP Server

Since IMAP is an internet protocol, the only configuration required by the portal administrator is:

• Install the delivered PeopleSoft jar file, com.peoplesoft.pa.pp.jar on the application server.

• Enter the IMAP mail server name and the URL for the IMAP mail inbox on the Email and Calendar Defaults page.

See Configuring the Primary Email System to Use IMAP.

Designating the Primary Mail System

The administrative information that you assign drives both the Email pagelet and Calendar Events pagelet. The portal supports Lotus Notes/Domino, Microsoft Outlook Web Access/Exchange, POP3, and IMAP systems for email, and Lotus and Microsoft for calendars. Remember that only one email and calendar system is designated as the portal's default system. The default system is considered primary and is the first email section on a user's pagelet. It is possible to override the system default for an individual user.

This section discusses:

• Designating the primary email and calendar system.

• Configuring the Primary Email System to Use Microsoft Outlook Web Access.

• Configuring the Primary Email System to Use Lotus Notes.

• Configuring the Primary Email System to Use POP.

• Configuring the Primary Email System to Use IMAP.

• Overriding email and calendar settings for individual user IDs.

• Support for SSL-enabled web servers.

Note. For the pagelets to be fully functional, you must complete setup procedures for the application and mail servers.

See Also

Understanding Application and Mail Server Configuration

Pages Used to Assign Mail Servers

Designating the Primary Email and Calendar System

The Portal Administrator designates the primary email and calendar system.

Access the Email and Calendar Defaults page (Portal Administration, Pagelets, Email / Calendar, Email / Calendar Defaults).

Note. The fields shown on this page vary depending on which email system is selected as the primary email system.

Configuring the Primary Email System to Use Microsoft Outlook Web Access

This sections discusses the configuration for Microsoft Outlook Web Access.

Access the Email and Calendar Defaults page and select the Microsoft (Outlook Web Access) option.

Configuring the Primary Email System to Use Lotus Notes

This sections discusses the configuration for Lotus Notes.

Access the Email and Calendar Defaults page and select the Lotus Notes option.

Configuring the Primary Email System to Use POP

This sections discusses the configuration for POP.

Access the Email and Calendar Defaults page and select the POP (No Calendar) option.

Configuring the Primary Email System to Use IMAP

This sections discusses the configuration for IMAP.

Access the Email and Calendar Defaults page and select the IMAP (No Calendar) option.

Overriding the Primary System for Individual User IDs

Access the Email and Calendar by User page (Portal Administration, Pagelets, Email / Calendar, Email / Calendar by User).

Select the user ID for which you want to define overriding email and calendar information. The remaining fields function like those on the Primary E-mail and Calendar Defaults page. Entries on this page override the primary email system settings entered on that page for the specified user.

See Also

Designating the Primary Email and Calendar System

Support for SSL-Enabled Web Servers

If your web server is SSL-enabled, in addition to specifying an HTTPS URL on the E-mail and Calendar Defaults page, you must do the following:

• For Microsoft Exchange, in the ASP file change the strProtocol value to https, or change the isFormBasedAuth flag to true, or both.

• For POP/IMAP, specify the SSL port number in the mail server URL.

• No extra steps are required for Domino.

Setting Up Additional Mail Systems

To enable users to add external POP email accounts to their Email pagelets, the portal administrator must set up a URL identifier and a URL for each POP mail system. Once these entries are stored in the URL Catalog, the POP mail system appears in the server and URL drop-down list boxes of the pagelet's Personalize Email Options - Add a Personal Email Account page.

This section discusses how to add and maintain mail system URLs.

Note. The POP mail system must have POP forwarding on a user's individual profile. Each user needs to set this with the external mail system. Some mail systems automatically activate POP forwarding; some (such as Yahoo!) require the user to change a profile setting, while others (such as Microsoft Hotmail) do not allow forwarding. Non-forwarding mail systems do not appear on the Email pagelet.

See Also

Working With the Email Pagelet

Pages Used to Set Up Additional Mail Systems

Maintaining URLs

Access the URL Maintenance page (PeopleTools, Utilities, Administration, URLs, URL Maintenance).

URL Identifier	Enter a URL identifier. The URL identifier indicates whether the URL points to a web address or to a POP3 mail server that cannot be accessed through the web. For a webmail URL, the URL ID must start with MAIL_. For a POP3 mail server, the URL ID must start with SERVERMAIL_. Whatever follows the MAIL_ or SERVERMAIL_ prefix must be unique for each MAIL or SERVERMAIL ID. For example: MAIL_YAHOO or SERVERMAIL_YAHOO.
Description	This description appears in the Mail Account Server drop-down list box on the Add a Personal Email Account page. For example: Yahoo Mail Server or Yahoo Mail URL.
URL	Enter the URL associated with the URL identifier.
Comments	You may optionally enter comments. For example, you may enter your name and the date on which the URL was enabled for the Email pagelet.

See Also

Working With the Email Pagelet