Administration Guide

1. Overview

harmon.ie for SharePoint (previously known as Mainsoft SharePoint® Integrator for Lotus Notes®) integrates content from Microsoft® SharePoint sites into Lotus Notes. The product is available in two packages:

As an integrated sidebar panel, installable as a plug-in for Lotus Notes 8.x (Standard Configuration).
As a standalone sidebar application that works with Lotus Notes 6.5.x, Lotus Notes 7.x, or Lotus Notes 8.x (Basic Configuration).

This document is intended to be a resource for Domino® administrators, guiding them on how to install harmon.ie, and familiarize them with product configuration options.

1.1. Product components

harmon.ie consists of two components:

1.1.1. harmon.ie sidebar

This is the main component of harmon.ie and it provides most of its functionality:

Access SharePoint documents and e-mail, along with their metadata.
Add SharePoint documents into Lotus Notes applications, such as Mail and Calendar.
Quickly locate content stored on one or more SharePoint sites using search, favorites, history, and back/forward buttons.
Create new documents, and modify existing documents on the SharePoint site.
Upload Lotus Notes e-mail messages and attachments to SharePoint, with preserved e-mail headers.
Access SharePoint calendars from Lotus Notes.
Prompt Lotus Notes users to check in documents and fill in metadata.
Initiate a Sametime® or Office Communicator chat with the author, most recent editor, or person who has checked out a SharePoint document.
View people profile from SharePoint My Site

1.1.2. The SharePoint button in Notes Mail template

The installation of this component is optional.

harmon.ie adds a SharePoint button to the Notes Mail action bar, using a new Mail template. The SharePoint button allows users to replace e-mail attachments with SharePoint links, and save e-mails or attachments directly to SharePoint from the Notes Mail application.

2. System requirements

These are the required software components:

For the integrated sidebar panel:

Lotus Notes version 8.x (Standard Configuration).

For the standalone sidebar application:

Lotus Notes version 6.5.x or 7.x, or Lotus Notes 8.x (Basic Configuration).

For both packages:

Windows XP Professional SP2 or later.
Windows Vista Business, Enterprise or Ultimate Edition.
Windows 7.

harmon.ie can be used to integrate content from Windows SharePoint Services (WSS) version 3.0, Microsoft Office SharePoint Server (MOSS) 2007 and SharePoint 2010.

For more information regrading SharePoint configuration requirements, read the knowledge base article: SharePoint configuration requirements for harmon.ie.

harmon.ie requires specific user permissions to enable all product features. The following Domino permissions are required: Read, Write, Create, Delete documents and Create folders.

3. Installation instructions

This section explains how to install the product for multiple users - either a pilot group or the entire organization.

In order to understand how to install harmon.ie for a single client, refer to this download page.

3.1. Sidebar installation for multiple users using the widget catalog

This section describes how to use Notes widget deployment technique to automate harmon.ie sidebar panel installation for multiple Notes users. For more information on Notes widget catalog, read: How to use a Notes widget to deploy a new plug-in to an existing Notes installation.

This process requires Domino server 8.0.1 or greater. If you are working with Domino 8.0.1, you should install a hot-fix as described in the Note to release 8.0.1 users section in this IBM article. There is no widget catalog support for Notes 8.0.0. Follow the instructions in Enabling user-initiated update with EUM to centrally install the sidebar for multiple users.

In order to use Notes widget deployment to provision harmon.ie sidebar to your users, follow these steps:

Create the widget catalog if it doesn’t already exist on your Domino server.
Create an NSF-based update site and import harmon.ie feature into it.
Create harmon.ie sidebar widget in the widget catalog.
Test the created widget.
Provision harmon.ie sidebar widget to your users.

3.1.1. Creating the widget catalog

To create the widget catalog, if it doesn’t already exist on your Domino server, follow these steps:

From Lotus Notes, click File > Application > New.
In the application Server field, specify the Domino server on which to create the application.
In the Title field, specify the application title, for example Widgets catalog.
In the File name field specify an application name, for example toolbox.nsf.
In the template Server field, specify the server on which the template resides.
Click Show Advanced Templates and select the Widget Catalog template (toolbox.ntf).
Click to enable Inherit future design changes, and click OK.
Assign ACLs to control access rights to the catalog application for administrators, power users, and end users. Administrators must be granted the [Admins] role in the catalog Access Control List (ACL).
Open the widgets catalog application and select View > Agents, highlight the Toolbox Sweeper/ToolSweeper agent, and click Enable. When prompted, specify the server on which the widget catalog resides.

For more information, read Creating the widget catalog in the IBM documentation.

3.1.2. Creating an NSF-based update site

Importing the update site into the NSF-based update site is the recommended method for deploying features and plug-ins using widgets. The NSF-based update site provides a central database for housing features for user deployment and provisioning. In this section, you learn how to import the harmon.ie feature into an NSF-based update site that will reside on your Domino server.

From Lotus Notes, click File > Application > New.
Click Show Advanced Templates and specify the Eclipse Update Site template (updatesite.ntf) as the template.
Specify a title and NSF file name (for example, UpdateSite.nsf) and click OK. Make sure to create the application on the Domino server.
Import harmon.ie update site into the open NSF-based update site, by doing the following:
1. Download a zipped harmon.ie update site according to your client version, and extract it to a local folder.
2. Click Features in the left pane navigator and then click the Import Local Update Site button.
3. As prompted, browse to the folder where you placed the downloaded harmon.ie update site, select its site.xml file, and click OK.

The update site available from harmon.ie Web site is not licensed and is intended for evaluation purposes. To obtain a licensed update site for production purposes, please contact support@mainsoft.com.

You may sign the update site with your own certificate. To learn how, read: Signing custom or third-party features and plug-ins for install and update.

3.1.3. Creating harmon.ie sidebar widget in the catalog

To add the sidebar widget to the catalog, do the following:

Download the mainsoft-extension.xml file (Right-Click > Save Target As…).
Open the downloaded mainsoft-extension.xml file in an XML editor and modify the url attribute, to point to the harmon.ie update site site.xml file in the NSF-based update site you created in the previous step. Make sure to save the modified file in ASCII encoding. For example: url="nrpc://NSF-based-update-site-server-name/UpdateSite.nsf/site.xml"
From Lotus Notes, open the Widgets preference page by clicking File > Preferences > Widgets.
Enable the Show Widgets Toolbar and the My Widgets sidebar panel option (this option is typically disabled by default when not using policies).
Verify the Catalog server and Catalog name (e.g. toolbox.nsf) values are not empty, and point to the location of the widget catalog.
Click OK to display the My Widgets sidebar panel and toolbar and connect to the widget catalog.
Open the widget catalog from the My Widgets sidebar panel by clicking Catalog > Browse in the My Widgets options menu.
Create the harmon.ie widget as follows:
1. In the widget catalog, click the All Widgets view option.
2. Click Add Widget to Catalog, and enter a widget title, for example "harmon.ie".
3. Click Category and type the new catalog category name, for example: SharePoint. In the Description field, you may enter a brief description.
4. Click Attach and select the mainsoft-extension.xml file that you edited earlier, and then click Save and Close.

The version number used in the mainsoft-extension.xml file refers to latest version of harmon.ie evaluation package. If you are installing a different package, you should use the version number available in the site.xml file on the harmon.ie update site.

3.1.4. Testing harmon.ie sidebar widget

We recommend testing the feature deployment widget before making it available to your users.

Drag the new widget from the widgets catalog view to your My Widgets sidebar panel.
Respond to any feature install prompts that appear. When you install a new feature you are prompted to restart the client.
Upon restart, note the addition of the harmon.ie widget in the My Widgets sidebar panel and a new harmon.ie sidebar panel.
Test the functionality of the harmon.ie sidebar panel.

3.1.5. Provisioning harmon.ie sidebar widget to users

To provision the sidebar widget to your users, do the following:

Configure desktop policy settings document with the widget catalog information:
1. Open the Domino Administrator client, and click People & Groups People > Policies > Settings to open the Settings view.
2. Click Add Settings and choose Desktop.
3. Click the Widgets tab, and in the Widget catalog server field, specify the server on which the widget catalog resides.
4. In the Widget catalog application name field, specify the catalog name, for example toolbox.nsf.
5. In the Catalog categories to install field, specify the catalog category in which the harmon.ie widget resides, for example SharePoint.
6. Specify the policy name and save the document.
Make sure to assign this policy to the users you wish to provision the sidebar widget.
Install the widget from the catalog to the users' client system by doing the following:
1. From Lotus Notes, go to your My Widgets sidebar panel, and click the Catalog > Update Widgets options menu.
2. Allow the local catalog to be updated or replicated on its regular schedule. Be aware that the new widget will be added to your users when the local catalog is updated.

A local copy of the catalog is created on the user’s client system and periodically updated based on a 24 hour (default) replication schedule.

3.2. Bundling the integrated sidebar with the Lotus Notes installation package

If you are about to roll-out the Notes client, you can bundle harmon.ie sidebar panel with the Lotus Notes client.

In order to create a combined installation package, follow these instructions:

Open the Notes install manifest (deploy\install.xml) and add the harmon.ie sidebar feature:

<installfeature default="true"
description="harmon.ie for sharePoint"
id="com.mainsoft.sharepoint.sidebar.feature" name="harmon.ie for sharePoint"
required="true" show="true" version="2.0.2.13905">
<requirements>
     <feature download-size="40000" id="com.mainsoft.sharepoint.sidebar.feature"
     match="greaterOrEqual" shared="true" size="40000"
     url="jar:${installer.root}/updateSite.zip!/"
     version="2.0.2.13905"/>
</requirements>
</installfeature>

The version number used is an example. If you are installing a different version, you should use the version number available in the site.xml file on the harmon.ie update site. For a reference to the attributes in this code snippet, and for more information about this procedure read Customizing the Notes install manifest for new or third-party Eclipse features in the IBM Lotus Domino Administrator help.

Sign the feature and plug-in JAR files that are located under the features and plugins folders, under harmon.ie update site. Details about how to sign the JAR files are available in this IBM help topic.
Add harmon.ie sidebar feature and plug-in JAR files to the correct features and plugins subdirectories in the Notes install kit’s updateSite.zip and ensure that the update site manifest (site.xml) correctly lists the contents of those subdirectories.

Complete instructions on how to customize the Notes install kit to add and remove Eclipse features are available in this IBM help topic.

3.3. Installing the standalone application for multiple users

Download the product installer file. You may silently install the standalone package by running the following from the command prompt:

HarmonieSharePointNotesSetup.exe /S /D={install_dir} /language={lang}

The /S parameter directs the installer to run silently and unattended.
The /D parameter specifies the installation directory.
The /language parameter specifies the default interface language. Possible values are: en (for English), de (for German), or fr (for French). This parameter takes effect only when the /S parameter is set. When this parameter is not set, English (en) is used as the default interface language.
The /force parameter forces the installation to start. For example, if Lotus Notes Basic Configuration is used, while the Standard Configuration of Lotus Notes 8.x is installed, you need to start the installation with this parameter.

3.4. Installing the SharePoint button

This section explains how to install the SharePoint button for a pilot group or for the entire organization.

The SharePoint button is visible only to users who have harmon.ie sidebar installed on their machine. For the others, the SharePoint button is hidden.

3.4.1. SharePoint button installation for a pilot group

To install the SharePoint button from the Domino server to specific users, usually a pilot group:

Download the Mainsoft Mail template that applies to your users' Notes version.
Sign the template with your production ID file and place the template file on the Domino server.

Open the Domino Administrator console window, and enter the following commands:

tell router quit

load convert mail/johndoe.nsf * mail<X>_Mainsoft_V<X.x>.ntf

load router

3.4.2. SharePoint button installation for the entire organization

The recommended way to centrally install the SharePoint button for the entire organization is to replace the default Mail template with harmon.ie Mail template.

If the organization uses a custom Mail template, you will need to merge the two template files first. For details on the differences between the harmon.ie Mail template and the default Mail template, read the Customizing the Mail template appendix in this document.

To replace the Mail template for the entire organization:

Download the Mainsoft Mail template that applies to your Notes version.
Sign the template with your production ID file and place the template file on the Domino server next to the standard Mail template.
Shut down the server by entering the exit command in the Domino server console.
Backup and delete the mail<x>.ntf template file, where <x> is the Notes version.
Change the name of harmon.ie template to match the standard Mail template. For example, rename mail8_Mainsoft_V8.0.2.ntf to mail8.ntf. Then, restart the server
When the server is started, change the database properties of the harmon.ie Mail template as follows:
1. From the Domino Administrator, open harmon.ie Mail template, and choose File > Database/Application > Properties to open the Database window.
2. Click the Design tab.
3. Replace the name of the harmon.ie Mail template with the standard Notes template name, according to the following table:

harmon.ie Template Name	Notes Template Name
StdR6Mail_Mainsoft_SPI	StdR60Mail
StdR7Mail_Mainsoft_SPI	StdR70Mail
StdR8Mail_Mainsoft_SPI	StdR8Mail
StdR85Mail_Mainsoft_SPI	StdR85Mail

By default, database designs are automatically refreshed at night. You can manually update database designs if you do not want to wait until the next day for changes to take effect. To manually refresh the Mail database design for all Lotus Notes databases, open the Domino Administrator console from the Domino server, and use the load design command.

4. Centralized provisioning of preferences

This section details how to use the Domino policy-based system administration to centrally provision harmon.ie preferences for its users. These preferences are stored in a standard desktop policy settings document, which then can be assigned to users either as organizational policies or as explicit policies.

harmon.ie also provides a Windows Registry-based provisioning of SharePoint sites and harmon.ie preferences. For more information read: Provisioning harmon.ie for SharePoint

4.1. Centralized configuration of SharePoint sites

Central configuration of SharePoint sites is available for Lotus Notes 8.x only. harmon.ie also provides a Windows Registry-based provisioning of SharePoint sites. For more information read: Provisioning harmon.ie for SharePoint

You can use the Accounts configuration in the Desktop policy settings to integrate SharePoint sites into the Domino policy infrastructure.

To configure a SharePoint site in a Desktop policy settings document:

From the Domino Administrator, select the People & Groups tab and open the Settings view.
Click Add Settings and select Desktop.
Go to the Accounts tab, and add a new account for harmon.ie:
1. Give a name for the account.
2. Specify SharePoint as the account Protocol.
3. Specify the Server Address of the SharePoint site, in this format:
  http:// <sp-site> [?useWindowsAuth=true] [?BrowserAuthentication=true] [&hideSubSites=<true/false>] [&useOWA=<true/false>] [&defaultSocialServer=true]

Server address parameters:

URL to the SharePoint site you wish to configure.
(optional) The useWindowsAuth query parameter, which lets you configure harmon.ie to connect to the configured site with the user’s Windows credentials. This option is only available when running on a Windows operating system.
(optional) The BrowserAuthentication query parameter, which lets you configure harmon.ie to connect to the configured site by prompting the user to enter his credentials via a browser. This option is recommended in case of connecting to Office 365 SharePoint sites.
(optional) The hideSubSites query parameter, which lets you configure the visibility of sub-sites and workspaces. By default, sub-sites and workspaces are displayed. If you do not specify the hideSubSites parameter, each user will be able to set its value in harmon.ie configuration.
(optional) The useOWA query parameter, which lets you configure the ability to open Office documents in the SharePoint Office Web Applications. This parameter should be set only if the SharePoint site was pre-configured to use Office Web Applications for Office documents.
(optional) The defaultSocialServer query parameter, which lets you configure the site as harmon.ie social server. For more information regrading harmon.ie social feature, please reference the product documentation.

Here is an example for a server address:

https://demo.mainsoft.com?useWindowsAuth=true

You can configure multiple sites using this procedure.

4.2. Using Managed Settings

With Domino 8.5, you can use the Managed Settings section of a desktop policy settings document to configure some of the preferences of the behavior of harmon.ie.

harmon.ie also provides a Windows Registry-based provisioning of preferences. For more information read: Provisioning harmon.ie for SharePoint

To use Managed Settings, do the following:

Create a desktop policy settings document.
On the Custom Settings tab, open the Managed Settings tab, and click Edit list… to specify the relevant values according to the table below.
Click Add/Modify Value>>, and save the document.
Assign this desktop policy to users.

Item	Values	Plug-in name	Notes
PromptToReplaceAttachmentsWithLinks	Yes	com.mainsoft.sharepoint.sidebar	Forces users to be prompted to replace e-mail attachments with SharePoint links. This feature requires the SharePoint button to be installed.
PromptForContentType	True	com.mainsoft.sharepoint.sidebar	Forces users to choose SharePoint content type during documents upload.
WarnOnMissingRequiredProperties	True	com.mainsoft.sharepoint.sidebar	Forces users to be warned when documents' required properties are not filled in.
AutoCheckInDocuments	Ask or Always	com.mainsoft.sharepoint.sidebar	Specifying Ask forces users to be prompted to check in their documents. Always automatically checks in the document without prompting the users.

5. Appendices

5.1. Customizing the Mail template

If you need to modify the Lotus Notes Mail template to add harmon.ie features, follow these procedures:

From the Domino Designer, open your Notes Mail template (mail<x>.ntf) and harmon.ie Mail template (mail<x>_Mainsoft_V<x>.ntf).
Copy the SPI_MainSubForm_2_0 subform from harmon.ie Mail template to your Notes template. The subform is located under the Shared Code/Shared Elements > Subforms node in the application navigation tree, and should be copied to the equivalent node in your Mail template.
Copy the SPI_DownloadDocumentAgent_2_0 and the SPI_ReplaceAttachmentsWithLinks_2_0 agents from harmon.ie Mail template to your Notes template. The agents are located under the Shared Code/Code > Agents node in the application navigation tree, and should be copied to the equivalent node in your Mail template.
Copy the SPI_ScriptLibrary_2_0 script library from harmon.ie Mail template to your Notes template. The script library is located under the Shared Code/Code > Script Libraries node in the application navigation tree, and should be copied to the equivalent node in your Mail template.
Sign the agents, the script library and the subform you copied with your production ID.
Insert the SPI_MainSubForm_2_0 subform into each of the mail forms: Message (or Memo for Notes 6/7), Reply, and Reply with History.
1. Open the relevant mail form (e.g. the Message form).
2. Right-click at the beginning of the form to insert the subform, and choose the Insert Resource… action. Make sure to insert the subform at the beginning of the form for it to be available in all the form modes.
3. Choose the SPI_MainSubForm_2_0 subform from the current database.
4. Repeat this operation for all mail forms (e.g. the Reply and Reply with History forms).

In your Mail template, insert code into the Send and Send and File… actions of the Message (or Memo for Notes 6/7) form. Add the following code before the MEMO_SEND and MEMO_SEND_FILE variables initialization:

FIELD SPI_SendCanceled := @Unavailable;
@Command([RunAgent];"SPI_ReplaceAttachmentsWithLinks_2_0");
@If( SPI_DontSwitchForm = 1; FIELD SPI_DontSwitchForm:=@DeleteField; @UpdateFormulaContext);
@If(SPI_SendCanceled; @Return(""); "");

You can use the code of the Send and Send and File… actions in harmon.ie Mail template as a reference.