Email Preview Portlet Configuration

Owned by Doug Sonaty
Last updated: May 20, 2015 by James Wennmacher (Deactivated)
5 min read

Build and Deploy the Email Preview Portlet

  1. Download the most current version from GitHub (example):

    git clone git://github.com/Jasig/email-preview.git

  2. Make sure you have Maven2 installed and that you can run the following command from your command line:

    mvn -version

  3. OPTIONAL Set the password for encryption. (You can skip this step if you don't plan to use portletPreferences authentication.)
    v2.0.4 and later:
    Edit file \Path\to\email-preview\src\main\resources\configuration.properties and set the value of the encryption.salt property

    encryption.salt=changeMe


    v2.0.3 and prior:
    Edit file \Path\to\email-preview\src\main\webapp\WEB-INF\context\applicationContext.xml. Uncomment <property name="password" value="changeMe!"/> and change the value of the password property from the following lines of code:

    <!-- Before using the string encryption service you must
    first set a password
<property name="password" value="changeMe!"/> -->

    For example:

    <!-- Before using the string encryption service you must
    first set a password -->
<property name="password" value="Secret"/>

    If there is a currently instance of the email-preview portlet running on uPortal when you make the above changes, you will need to rebuild and deploy the portlet. Once that is done, restart your Tomcat for the changes to take effect. Any credentials users have already saved will become invalid and need to be re-entered, so don't change this setting unless you have to.

  4. In the email-preview directory, run

    mvn clean package

    Once the project is built, you'll have a file called email-preview.war in the \Path\to\email-preview\target directory.

  5. Deploy the portlet by running

    ant deployPortletApp -DportletApp=/path/to/email-preview.war

    ...in the uPortal source directory on your target server.

Email Preview Portlet Registration

A number of key elements are specified below that should be carefully configured during registration:

includeJQuery Setting

Make sure the javascript.jQuery.include portlet preference is set to the correct value: true for uPortal 3.1 or later or any portal that does not provide jQuery in the global JavaScript namespace; false for uPortal 3.0.x or any portal that provides jQuery in the global JavaScript namespace. The default is true. This setting allows Ajax features in the portlet to function properly.

  1. Select Portlet for channel type and click the Next button.
  2. Select Email Preview Portlet and Email Preview from the drop-down menus.
  3. Populate the Channel Functional Name and Channel Description fields.
  4. Increase the Channel Timeout value to be at least 20000 (for Exchange Web Services, and versions prior to 2.0.4)

  5. Check the edit box for Portlet Control and click on the Next button.

    If edit is not selected, users will not be able to access the edit mode for the portlet.

  6. Click on the Next button.
  7. On the Select Categoriesscreen:
    • Select a category from the All Categories box
    • Click on the Select button.
    • After the category is selected, click the Next button.
  8. On the Select People and Groupsscreen:

    • Select the group(s) you want to be able to add the email-preview portlet to their layout.

      You may select individual users by entering their name in the Search field and clicking the Go button.

    • Click on the Select button.
    • After the group(s) is selected, click the Next button.
  9. Select Published for Lifecycle option and click the Next button.
  10. Click on the Save and Configure button.
    The Edit Portlet Configuration page is displayed. Here you can enter the email settings or enable users to enter their email settings (see next section).

2.0.3 and earlier

Email Preview Configuration

IMAP(S) or POP(S) Integration

Choose imap, imaps, pop, or pops in the protocol input.

The following properties only apply to integration based on one of these four protocols.

  • Host is the incoming email server. In the above example I am using Gmail and enter imap.gmail.com in the field.

  • Port is the connection point to the email server. Gmail uses IMAPS protocol and has a default port of 993. Here is a list of default email ports (can leave port as -1 if the port is the normal default port)

    eMail Servers and Posts

    Here is a list of default email ports:

    • POP3 - port 110
    • IMAP - port 143
    • Secure IMAP (IMAP4-SSL) - port 585
    • IMAP4 over SSL (IMAPS) - port 993
    • Secure POP3 (SSL-POP) - port 995
  • Display mail attribute in UI (2.1.1-M4+) - Set to display the user's 'mail' attribute rather than username+suffix in the UI.  Primarily useful in on-premise Exchange when username is needed for authentication but user's know themselves as the email address in LDAP or another source and it doesn't match username+suffix.
  • Inbox folder name is the name of your email's inbox. Most likely the name is INBOX. If this field is not populated or filled out incorrectly, the portlet will fail to render for the user.
  • Timeout and Connection Timeout can be left at -1.

v2.0.4 and later:

Exchange Web Services Integration

The Email Preview portlet also supports integration with Exchange Web Services.  Select ExchangeWebServices in the protocol input.  

The following properties only apply to the ExchangeWebServices Protocol

  • Exchange Domain is the NTLM domain used to authenticate the accounts against
  • Host is either the autodiscover host or the EWS host. 
  • Autodiscover - set to true if the host entered is the hostname to initiate the autodiscover process with, false if the hostname is the host running EWS.  For outlook.com, you would set autodiscover=true and hostname=www.autodiscover.com and the correct EWS host will be found for each user account.
  • Username suffix is the suffix to append to the username to obtain an email account login id.  Useful if the username is obtained from the uPortal login; e.g. @usd.edu
  • Use mail attribute instead of username+suffix (2.1.1-M4+) - set to true primarily for Office365 when the 'mail' user attribute is more accurate than username+suffix.  This can happen when users get married or other events and their username is not as correct as the mail attribute email address.  If set for on-premise EWS the username part of the mail user attribute would be used for the userId instead of the username (not a common situation).
  • Inbox folder name is the name of your email's inbox. For EWS integrations most likely the name is Inbox (not INBOX). If this field is not populated or filled out incorrectly, the portlet will fail to render for the user.

v2.1.1 and later:

Linking
  • Link Service - enter the https URL of a web email client to open in a new window (does not attempt to do single sign-on)
Authentication
  • Selecting cachePassword will automatically use the user's portal login credential to log into the email server (see uPortal manual for changes needed to store and cache user's password).
    • Use Username Suffix to append the domain of the email account to the user's username (e.g. @gmail.com).

  • Selecting porletPreferences will allow the user to edit the email server login credentials.

    Some email provider such as Google do not have IMAP enabled at default. This will cause the portlet to fail to render. Please contact your email provider if IMAP is not enabled.