12.3 Outlook Plugin Administrators Guide

12.3.1 Overview

The Outlook Plugin integrated the Retain storage directly into the Outlook client. Users will have a new tab and ribbon added to the Outlook client offering connection to their Retain storage. Messages may be retrieved and added to the user’s local machine and administered through the Outlook client. Message data may be searched in both the Retain storage, and the locally restored messages. The client will not modify Retain administration nor will anything done through the Outlook Plugin modify the Retain Server or the Retain Storage. The Outlook Plugin is provided for both individual and distribution installations.

The Outlook Plugin is found on the tools page. To access the tools page, select the 'tools' link from the top right of the Retain Server administration page.

12.3.2 System Requirements

  • Windows 7 SP1, Windows 8.1 or Windows 10, fully updated

  • Retain 4.3 or higher

  • Visual Studio Tools for Office v. 4

  • .Net 4 or higher

  • Outlook 2010, 2013, 2016 32-Bit and 64-Bit, October 2017 update or later.

    NOTE:Whether the 64-Bit or 32-Bit version should be used is determined by the bit version of Outlook installed, not the version of the OS. To check the version of Outlook being used;

    2010: The information on the system is located under File | Help | About Microsoft Office

    2013: The information on the system is located under File | Office Account | About Outlook

    2016: The information on the system is located under File | Office Account | About Outlook

Proxy Access

The Retain Outlook plugin does not return mailbox data from other users the primary user has proxy access to but only the messages from the primary user's Retain mailbox.

If the user has access rights to other mailboxes on the Retain system, Outlook will error because it doesn't know how to handle multiple users.

12.3.3 Installation

Prerequisites

On the Retain Server: Under Server Configuration | Communications | Retain Server Connection, set the Server Protocol (http or https), Retain Server Host (IP or hostname of the Retain server), Retain Server Port (default: 48080), and Retain Server Path (default: /RetainServer).

On the Workstation: Install:

  • Visual Studio Tools for Office v. 4

  • .Net 4 or higher

Retain Outlook Plugin Installation

If deploying to an individual user on a workstation, the Outlook plugin needs to be installed by the user account that will be using it (HKEY_CURRENT_USER), and administrator credentials will be required to be entered during the installation process.

If deploying to multiple users on a single workstation a group policy will need to be created to set the registry keys needed by the Outlook plugin across all users. The October 2017 updates of Office and Windows have caused some issues that may need workarounds.

If deploying from a distribution server, utilize the MSI installer package. In addition, silent install commands are provided. A full list of silent install commands can be found in the Silent Install section below.

Make sure to utilize the correct version of the installer to match the bitness (32-Bit or 64-Bit) of the version of Outlook, not the operating system, the workstation has installed.

Begin the installation, accept the license agreement, and click ‘Next’.

Select whether the installation will be system wide or restricted.

The Retain Outlook Plugin may be customized during installation, to only allow certain functions once installed.

Retain server URL: this is the connection address for the Retain Server. Do not put the ‘/RetainServer/’ suffix on the end of the URL. Use the following syntax:

https://<Retain_Server_URL>

Please Select the Outlook Plugin to Install: There are two options for the plugin. Retain Download allows the user to download data from the Retain server to their workstation. Retain Archive opens the Retain interface in the Outlook window

Download Retain Data on Outlook Startup: This tells the Retain plugin to match the local data with what is in the Retain Server. This does not push any data from the plugin to the Server. The plugin may be configured to download at start, or on an automatic time period. The setting is designated in hours.

Allow users to change settings: If checked, the following selected options are available to be changed by the user in the plugin. If this option is not checked, the options will be grayed-out in the settings section of the plugin, and cannot be modified.

Configure as desired and select ‘Next’.

If any settings need to be changed, use the ‘back’ button and change then.

Select the ‘Install’ button to begin the plugin installation. (Installation will require admin rights.)

Wait for the plugin to install.

Once the install has completed, select ‘Finish’ to exit the installer.

12.3.4 Features and Use

To access the Retain Outlook plugin, open the Outlook client.

A dialog will appear asking for Retain login credentials. Users will then need to log into Retain with their Active Directory/Azure Logon.

Once installed and initialized, the Retain tab, ribbon, and folder structure are available. A new folder called Retain Download will appear.

To access the folder structure, simply select it as you would the normal folder structure in Outlook.

Individual settings of the plugin can be changed from the ribbon.

12.3.5 Retain Archive

The Retain Archive button is simply a portal to the Retain web interface for users.

A new folder called Retain Archive will also be created at the Inbox level of the user’s local folder. This will allow the user to Browse or Search their Retain archive mailbox. Click on Launch Retain or the Retain Archive folder to log into Retain and the Retain web interface will appear in the Outlook window.

12.3.6 Download Settings

The Download Settings contains the criteria which dictates what message data will be added into the local storage and made available in the Outlook client. It is recommended to keep the download size small because Outlook has difficulty serving very large amounts of data.

The download time limit dictates the time frame of messages which will be displayed in the Outlook client. This can download a large amount of data which may overwhelm the resources available to Outlook, so it is best to limit this to 90 days or less.

Messages may be limited by total number, as may the search results. (Search results limit the number of results by default to only display 500 messages.)

In addition, the type of data may be limited to only the types selected, or all types.

What data is added to local storage can be limited by age, number of messages, or item type. ‘Save’ saves your settings. However, before the download can be performed, the login information must be provided. Select the ‘Account Settings’ button.

12.3.7 Account Settings

The account settings are simply the login credentials of the account which is to be used for the download. Input the email and password. GroupWise usernames must not be the full address. If inputting an Exchange username, enter the entire email address. Save settings.

12.3.8 Clear Local Archive

The Clear local archive button does exactly as it sounds, it will empty the local archive, Retain, folder tree of all message data items. Any folders which were part of the Retain archive, and not part of the default folder set of Outlook will also be removed. The default set of folders and the Retain folder tree will still be present. To completely remove the Retain outlook plugin, please uninstall the plugin from the system’s Control Panel.

12.3.9 Launch Retain

The Launch Retain button will cause the default browser to open to the Retain Server URL.

12.3.10 Retain Download

The Retain Download button initiates a download of the users Retain archive according to the download settings. Download settings and the user credentials must be configured before the download will complete.

12.3.11 Retain Search

The user’s downloaded Retain archive can be searched with the search functions of the ribbon. To search the entire archive click on the Retain Archive button and use the search tab.

Searching the downloaded Retain Archive with the Retain Plugin is simple. Select the ‘Retain Search’ button from the Retain ribbon.

The search interface has two different screens: Easy and Advanced search.

12.3.12 Easy Search

With the Easy search, the plugin only offers a simple keyword and date range.

The search keywords are subject to the same restrictions and abilities as the Retain web interface. Easy search supports wildcards and quotes for search criteria. Without quotes, the search text will be searched as each word is an individual search term. With quotes, the search phrase is the criteria.

For example: Searching for ping pong will result in messages with the term ‘ping’, with the term ‘pong’, and with both, ‘ping pong’.

While searching for “ping pong” will only result in messages with the term ‘ping pong’.

Searching with wildcards: Searching for gwava.* will produce results of ‘gwava.com, gwava.org, gwava.edu’, and ‘gwava.’.

In general, if multiple search terms are desired, move to the advanced search option. After search terms and a date range has been applied, select the ‘Search’ button.

12.3.13 Advanced Search

The advanced search allows for more control in the search process.

The ‘Search in’ drop-down menu allows for customization of the limiting function of the keyword.

  • Content

  • Sender email

  • Sender name

  • Recipients

  • Subject

  • File name

The condition field restricts the condition of the data items in the Retain Message Store.

  • Contains (exact)

  • Contains (fuzzy)

  • Starts with

  • Ends with

  • Does not contain

Finally, the Connector setting allows for the logical connection between criteria.

And

Or

The “+ and -” buttons to the right of the window allow the user to add multiple search term lines. There is no limit to the amount of lines, or criteria, which may be added.

The Message type option allows the search to be limited to the specific selected type or types. (Note, Appointment, Task, or Mail)

The Date Range is designed with appointments, tasks, and notes. If the date range is used, the range for the desired date applies. This is essentially a date range for the date ranges. This is a good way to look for tasks and appointments which were placed into the system before, but not removed later.

Created

Stored

The Status restriction allows the user to search for messages with a specific message state; opened, read, and private.

Once the search terms are satisfactory, select the ‘Search’ button to begin the search. Once the search has completed, the resulting group of messages is added to the Retain local archive, under the ‘Retain search results’ folder.

NOTE:It is important to note that the number outside the folders represents the ‘unread’ message count, not the total message count. To view the total message count, see the ‘Items:’ count at the bottom left of the Outlook window.

12.3.14 Quick Search

The Retain ribbon contains a quick search field, which performs a simple search of last six months of the user’s downloaded archive right from the ribbon without opening any additional windows. Simply place the desired criteria in the field and click on the ‘Quick Search’ button. Results will be displayed the same way they are for the Easy and Advanced search. In addition, the Quick Search supports the same wild-cards.

12.3.15 Retain Outlook Plugin Settings

The Plugin settings button opens the plugin settings window. This is where the user can modify the basic plugin settings.

This window contains all connection and plugin settings. If the entries here are grayed-out, then the ability to change the settings has been disabled during install, and the setting information is display-only.

The connection URL should be specified with just the hostname or IP address. If a port number is required, it may also be specified, but is not necessary if Apache or IIS is handling requests for the Retain Server.

Whether the Retain Download section or the Retain Archive section is visible is controlled here. The plugin may be set to automatically download messages from the archive on startup, or at a set time interval, to ensure that the plugin shows what is present in the Retain Archive.

The Launch Retain button will cause the default browser to open to the Retain Server URL.

The Language set in the Plugin Settings will change the displayed language for all Retain plugin displays.

12.3.16 Data File

The Retain Outlook plugin stores the downloaded data in the user's folder. You can find this location by right-clicking on the Retain Download folder and selecting Data File Properties.

It will be generally found in C:\Users\[userName]\Documents\GWAVA\Retain.nst

12.3.17 Log File Location

The plugin will create a log file if the folder C:\temp exists.

For example: C:\temp\WrapPST.txt

12.3.18 Outlook Plugin Silent Install

The Retain Outlook plugin can be deployed across your network with a Windows policy.

12.3.19 Command Line Install

Prerequisites: To install the MSI, two packages must be installed. These packages are included in the bundle which is an EXE, not an MSI. If either of these are missing the install will fail.

  • Microsoft .NET Framework 4 Extended

  • Microsoft Visual Studio 2010 Tools for Office Runtime.

If you open a non-admin command prompt, you will be asked to provide Administrator level credentials to proceed with the install.

The plugin is designed to be installed via command line silently. To do this, open a Command Prompt and run the .msi file and add a /q then enter the settings desired from the following:

RETAINURL: The Retain server URL http://<Retain_Server_Address> no trailing slash. For example: http://retain.company.com. Default http://RetainURL

MAXSYNC: Maximum integer number of items to be synced in every synchronization. Default 50.

MAXSEARCHRESULTS: If using the Retain search feature, the maximum integer number of items that will appear in the results. Default 500.

USERNAME: The username of the user (generally the user’s email address).

MESSAGESYSTEM: The type of messaging system. Values: 0-> Exchange 1-> GroupWise

FILTERTYPE: Filter messages based on the type during the synchronization. It uses bit pattern to store the values: 0-> 0000-> No filter (All types) 1-> 0001-> Mail 2-> 0010-> Appointment 4-> 0100-> Note 8-> 1000-> Task COMBINE THE BIT NUMBERS TO HAVE MULTIPLE VALUES SET 3-> 0011 -> MAIL & APPOINTMENT 6-> 0110-> APPOINTMENT & NOTE 15-> 1111-> ALL FILTERS

ARCHIVEFILEPATH: The path and the file name of the desired local NST file. The path should exist but not the NST file itself.

ISWEBUI: Use the new Retain login within Outlook. Boolean value. Default true.

ISNATIVE: Download Retain files into Outlook, original plugin style. Boolean value. Default true.

HASAUTOSYNC: Enable auto synchronization to Retain. Boolean value. Default true.

SYNCINTERVAL: How often to automatically download new items, in hours. Default 3.

SYNCSTARTUP: Enable Synchronize on startup. Boolean value. Default true.

DAYSAGOARCHIVED: Synchronize messages older than x days ago

CANCHANGESETTINGS: Enable the right for the user to change settings. Boolean value. Default true.

SCOPE: Install just for one or all users on the machine. perUser or perMachine. Default perMachine.

Here is an example of the command line that could be used. Using the /qb option will present a progress prompt, but is not required. Adding the /l* will output a log for troubleshooting.

msiexec /qb /l* plugin.log /i "Retain Outlook plugin_x86.msi" /norestart ARCHIVEFILEPATH="C:\Users\UserName\My Documents\RetainLocalStore.NST" RETAINURL=http://10.1.43.17/ MAXSYNC=200 DAYSAGOARCHIVED=0 DURATION=7 RANGE=2 USERNAME=UserName@company.com MESSAGESYSTEM=0 FILTERTYPE=6

12.3.20 Group Policy Install

You can use an AD Group Policy to install the Outlook Plugin. You may use MS System Center Configuration Manager using this as a template or a third-party program such as Orca to adjust the settings in the MSI file for your organization. Orca is a third-party program that allows you to set parameters within an MSI file.

  1. Download the correct Outlook plugin MSI file that you need for your installation from the Tools menu. Make sure you get the 32bit or 64bit version that corresponds to your version of Outlook, not your operating system. If using Outlook 32-bit on Windows 64-bit, use the 32-bit plugin installer.

  2. If using Orca, download Orca and install it on the computer where you have your newly downloaded MSI file.

  3. Run Orca and open the MSI file that you wish to make the changes to.

  4. After you open the MSI file you will need to go down to the table called "property" and select this table which will show you all the properties and switches of the MSI file. Here is where you will set your switches to true or false depending on what you would like your final settings to be after the silent install.

  5. After you have made the changes, save the amended file and close Orca. Now you are ready to deploy the MSI file in your group policies across your network.

  6. Make sure that the prerequisites: October 2017 Office and Windows updates, Visual Studio Tools for Office v. 4. and Net 4 or higher are installed on the workstations.

  7. Setup the Group Policy in Active Directory.

12.3.21 Retain Outlook Plugin Single Sign-On

The Retain Outlook Plug-in can be enabled to use Single Sign-On (SSO) so users can connect to Retain from within Outlook without being prompted to log into Retain separately.

NOTE:These instructions require the Retain Server to be hosted on a Windows server.

You are expected to have some knowledge about setting up a user with OpenSSO and Keytab files.

You will need to create an Active Directory Retain Single Sign-On user (retainsso) that will handle the single sign on, generate a keytab file, update Retain’s kerberos.properties file and configure the client workstation, the steps will be shown below.

To enable the Retain Outlook Plugin with Single Sign-On you will need to follow these steps:

Prerequisites

Complete these prerequisites before beginning.

  • Retain Server must be hosted on Windows.

  • The Retain server must be connected to the same domain as the Single Sign-On user you will be creating.

  • The workstations running Outlook with the Retain plug-in must be connected to the same domain as the Single Sign-On user you will be creating.

  • You will need to know the realm or FQDN of your Exchange server, for this example “exchange2013.qa.gwava.com”.

Create the Single Sign-On User

Create the SSO user:

  1. On the Active Directory Domain Controller server, logged in as a domain admin, open “Active Directory Users and Computers”.

  2. Create a new user, (Actions menu | New | Users) with the following attributes, with your domain information filled in instead of the sample information:

    • First name: retainsso

    • User login name: HTTP/retainsso.exchangeserver.example.com. For Example: HTTP/retainsso.exchange2013.qa.gwava.com

    • Pre-windows logon name: retainsso

    • Set password: Specify an appropriate password

    • Enable: Password never expires

    • Disable: User must change password at next logon

    • Disable: Use Kerberos DES encryption types for this account

    • Disable: This account supports Kerberos AES 128 bit encryption

    • Disable: This account supports Kerberos AES 256 bit encryption

    • Disable: Do not require Kerberos preauthentication

Associate the Single Sign-On User With the Service Principal Name

Associate the Single Sign-On User with the Service Principal Name (SPN)

  1. On the Active Directory Domain Controller server, logged in as a domain administrator, open a command shell.

  2. Enter the following command, with your domain information filled in instead of the sample information: setspn -A HTTP/retainsso.exchange2013.qa.gwava.com@EXCHANGE2013.QA.GWAVA.COM retainsso

  3. View the SPN registration by entering the following command on the command line: setspn -L retainsso

  4. If these steps have completed without error, then the SPN has been successfully setup.

Create the Keytab File

Create the keytab file. For more information see: :

  1. On the Active Directory Domain Controller server, at the command line prompt, enter the following updated with your domain information filled in instead of the sample information: ktpass /out retainsso.keytab /princ HTTP/retainsso.exchange2013.qa.gwava.com@EXCHANGE2013.QA.GWAVA.COM /mapuser retainsso /mapop set /pass Password1 /crypto ALL /ptype KRB5_NT_PRINCIPAL

  2. That command will generate a file with the name retainsso.keytab at the location of command line prompt’s current working directory.

  3. Store the keytab file in a secure location that the Retain Server has full access to or the keytab may be copied to the Retain Server

  4. Verify that the SSO user has been successfully configured by logging onto any machine on the domain with that user.

Create the krb5.ini File

  1. On the Retain Server, create a new file and name it krb5.ini.

  2. Add the following details to the krb5.ini file, with your domain and server information filled in instead of the example domain and server information:

    [libdefaults]
    default_realm = 
       QA.GWAVA.COM
    kdc_timesync = 0
    forwardable = true
    proxiable = false
[realms]
    
       EXAMPLE.COM = {
         kdc = exchange2013.qa.gwava.com
         admin_server = exchange2013.qa.gwava.com
    }
[domain_realm]
    .qa.gwava.com = 
       QA.GWAVA.COM
    qa.gwava.com = 
       QA.GWAVA.COM

    NOTE:The file is case sensitive, so make sure you use the same case as the example above.

  3. Save krb5.ini in the same location as the “.keytab” file.

  4. Provide full File Permissions to the krb5.ini file to the Retain Server.

Configure Retain Server for Single Sign-On

The Retain Server needs to be configured properly for Single Sign-On:

  1. On the Retain Server, Confirm that the Retain Server is in the same Domain from which the Kerberos authentication is done.

  2. The computer name of the Retain Server must match the SPN username. In this example, “retainsso”

  3. Place the keytab and “krb5.ini” files created previously in C:\Windows on the Retain server.

  4. On the Retain server, browse to the kerberos.properties file. By default, the file is found in C:\Program Files\Beginfinite\Retain\RetainWebUI\src\main\webapp\WEB-INF\cfg\kerberos.properties

  5. Edit the file: kerberos.properties.

  6. Set kerberos.Server.Principal.Name to the retainsso User Logon Name from above. For example: HTTP/retainsso.exchange2013.qa.gwava.com

  7. Set kerberos.Keytab.Filepath to the location of the retainsso.keytab file from above. The path should use forward slashes (/) instead of back slashes (\).

  8. Confirm there are no trailing spaces on any line in the kerberos.properties file. Especially at the end of the SPN name.

  9. Save the kerberos.properties file.

  10. Confirm that the Retain Server has access to the directory where “.keytab” and “krb5.ini” are mentioned in the kerberos.properties file.

  11. Restart the Retain Tomcat service. Starting and Stopping the Retain Server

Configure the Client

Each client workstation needs to have Integrated Windows Authentication configured. Outlook and the Retain Outlook Plugin should already be installed.

NOTE:You must perform this procedure for each end-user computer where you want to provide single sign-on access to Retain Web UI.

On the workstation users will be using Single Sign-On:

  1. Open the Internet options control panel.

  2. Click Security

  3. Click Trusted Sites > Sites.

  4. Add the DNS name of the identity applications server. For example: retainsso.exchange2013.qa.gwava.com

  5. Click Add, then click Close.

  6. Click Custom level...

  7. Under User Authentication, select Automatic logon with current user name and password.

  8. Click OK.

  9. In Internet Options, click Advanced.

  10. Under Security, select Enable Integrated Windows Authentication.

  11. Verify that Single Sign-On is working by opening Outlook, connecting to the Retain archive, selecting a local Outlook folder and then back to the Retain archive.