MS Outlook Plug-in Installation Guide

MS Outlook Plug-in will reach end of support on June 28, 2024. For more details, please refer to the Outlook & Word Plug-ins Will Reach End of Support June 2024 SugarClub post.

Overview

The Sugar Plug-in for Outlook allows you to archive emails to Sugar®, synchronize contacts, meetings, calls, and tasks, as well as create new Sugar records. The plug-in is available for use with all supported versions of Sugar and must be installed on each computer running Outlook where the plug-in is desired.

This documentation describes how to install the Sugar Plug-in for Microsoft Outlook. For a list of platform requirements and supported environments, please refer to the Plug-ins Supported Platforms page. For additional articles about working with and troubleshooting the Sugar Plug-in for Microsoft Outlook, please refer to the Knowledge Base.

Prerequisites

It is recommended that you uninstall any previous full versions of Sugar Plug-in for Outlook before you upgrade to the latest version.
Note: If the free trial version of Sugar Plug-in for Microsoft Outlook is already installed on your machine, you can upgrade to the full version of Sugar Plug-in for Microsoft Outlook instead of performing a fresh install.
When installing the plug-in, you must log into the computer as a full administrator on that local machine. Attempting to install the plug-in from a non-admin user of the computer may not be successful.
The Sugar Plug-in for Outlook requires several libraries to function. The most commonly needed libraries are included in the installation package. For more information, please refer to the Necessary Libraries section of this page.
The Windows Management Instrumentation service must be enabled on your machine with the Startup Type set to "Automatic".

Uninstalling Sugar Plug-in for Outlook

If you have a previous version of the Sugar Plug-in for Outlook installed on your machine, please uninstall the old version prior to installing the new version.

Uninstalling via Windows Control Panel

Use the following steps to uninstall the Sugar Plug-in for Microsoft Outlook via the Windows control panel:

Close your Microsoft Outlook client as well as other Microsoft Outlook-related windows and programs.
In the Windows Control Panel, click "Add or Remove Programs" or "Programs and Features" depending on your version of windows.
On the following window, select "Sugar Outlook" then click the "Uninstall" or "Remove" button depending on your version of windows.
A pop-up message will display asking for confirmation. Click "Yes" to proceed.
A pop-up message will display asking if you wish to keep the settings.
Note: Click "Yes" if you are upgrading the plugin so you do not lose your plug-in settings. Click "No" to completely remove the plugin and all of its data permanently.
Once the Outlook plug-in is removed, close the previous window (e.g. Programs and Features).

Note: If the previous version is not removed prior to installing the new version of the Outlook plug-in, then "SugarOutlook" may appear multiple times in the "Add/Remove Programs" or "Programs and Features" window.

Uninstalling via Command Line

Use the following steps to uninstall the Sugar Plug-in for Outlook via the command line:

Launch the DOS command window and navigate to the folder where the Outlook plug-in installer resides.
Run the following command from the command line: msiexec /x data.package.msi /quiet.
- By default, this will remove the Outlook plug-in configuration from the registry during uninstall. You can also run msiexec /x data.package.msi /quiet KEEP_CONFIG=0 to remove the plug-in settings during uninstall.
- If you are upgrading the plug-in and wish to keep the old Outlook plug-in configuration, run the following command instead: msiexec /x data.package.msi /quiet KEEP_CONFIG=1.
Enter exit to close the command window.

Downloading Sugar Plug-in for Outlook

To download the appropriate Sugar Plug-in for Outlook file, log into your Sugar instance, navigate to the Downloads tab in your user profile, and click on the "Sugar Plug-in for Outlook" link. The installation file will save to a location on your computer and work with all supported versions of Outlook.
DownloadsTab SugarPluginforOutlook2.2.0

Installing Sugar Plug-in for Outlook

Installing via Setup Wizard

Once you have downloaded the installation file, you can install the Sugar Plug-in for Outlook via the Setup Wizard using the following steps:

Navigate to the folder where you saved the downloaded file and extract the contents of the zip file.
Click the setup.exe file to run the installation.
Note: A Security Warning pop-up window may appear. Click "Run" to proceed with the installation.
On the Welcome step of the setup wizard, click "Next" to proceed with the installation process.
A warning message will display indicating that this version of the plug-in is only available for use with Sugar 7.x and higher. Do not proceed with the installation if you are using a version of Sugar that is lower than 7.0.0.0. Otherwise, click "Next" to proceed.
On the License Agreement step, select "I Agree" and then click "Next".
On the Select Installation Folder step, leave the installation directory set to the default path, select "Just me", and click "Next".
On the Confirm Installation step, click "Next" to start the installation on your computer.
Once the installation has completed successfully, click "Close" to exit.
Finally, open up your Outlook mail client and confirm that the Sugar options (e.g. "Archive to Sugar" and "Sync to Sugar") appear under the Home tab on the Outlook ribbon:

Note: If you do not see the Sugar options, the installation may not have completed properly and you should try uninstalling and re-installing the plug-in. For advanced troubleshooting, please refer to the Troubleshooting Installation section.

You may now open Outlook and proceed with Connecting Sugar Plug-in for Outlook.

Installing via Command Line

Use the following steps to install the Sugar Plug-in for Outlook via the command line:

Download the appropriate installation file to your desktop.
Launch the DOS command window and navigate to the unzipped installation directory.
Run the following command from the command line:
- For x64 (64-bit) platform : msiexec /i data.package.msi /quiet OFFICE_BITNESS=x64 ALLUSERS=1
- For x86 (32-bit) platform : msiexec /i data.package.msi /quiet OFFICE_BITNESS=x86 ALLUSERS=1
Enter exit to close the command window.

Connecting Sugar Plug-in for Outlook

After installing the plug-in, you will need to configure the Outlook Plug-in to connect to your Sugar instance so that they can communicate with each other. Open the Outlook application then click on the prompt in the SugarCRM side panel to open the connection settings. The steps to connect the Outlook Plug-in to a Sugar instance varies depending on whether your instance uses SugarIdenitity or not. For more information, refer to the Logging in WIthout SugarIdentity or Logging in With SugarIdentity section below depending on your situation.
260-connection-settings

Logging in Without SugarIdentity

The following steps cover connecting the plug-in to a Sugar instance that does not use SugarIdentity:

In the Connection section under the General tab, enter your Sugar instance URL then click "Connect".
Note: Be sure to begin the URL with "https://".
If you have entered a valid Sugar URL, a login dialog box will appear. Enter your Sugar username and password then click "OK". If the connection is successful, you will see a success message.

Note: The Sugar Plug-in for Outlook is not supported for Sugar instances using single sign-on (SSO) unless the instance uses SugarIdentity.

Logging in With SugarIdentity

The Sugar Plug-in for Outlook can connect to a Sugar instance that uses SugarIdentity via standard login and single sign-on. Please note that the plug-in supports single sign-on for instances that are SugarIdentity-enabled and use LDAP or SAML.

Standard Login

The following steps cover connecting the plug-in to a SugarIdentity-enabled instance (not using LDAP/SAML):

In the Connection section under the General tab, enter your Sugar instance URL then click "Connect".
Note: Be sure to begin the URL with "https://".
In the login window that appears, enter your Sugar username and password then click "Log In".
A user consent window will appear requesting access to your Sugar account. Click "Allow Access" to grant access for the connection to occur.

If the connection is successful, you will see a success message.

Single Sign-On Authentication With SugarIdentity

The following steps cover connecting the plug-in to a SugarIdentity-enabled instance that uses LDAP/SAML:

In the Connection section under the General tab, enter your Sugar instance URL then click "Connect".
Note: Be sure to begin the URL with "https://".
In the login window that appears, enter your LDAP or identity provider (e.g. Okta) login credentials then click "Log In" or "Sign In".
A user consent window will appear requesting access to your Sugar account. Click "Allow Access" to grant access for the connection to occur.

If the connection is successful, you will see a success message.

Necessary Libraries

The Sugar Plug-in for Outlook requires several libraries to function. The setup.exe file will install two of the necessary libraries if needed. Please note that running data.package.msi will not install the Outlook plug-in.

The required libraries are the following:

Microsoft Visual Studio Tools 2010 and higher for Office SE Runtime (included in setup.exe installer)
Microsoft .NET Framework 4.8 and higher (must be installed separately if not already present on your computer)
Microsoft Visual C++ 2010 Redistributable (must be installed separately if not already present on your computer)

Installing Visual Studio Runtime Library

The Visual Studio Runtime library (VSTOR) is typically installed automatically when installing the Sugar Plug-in for Outlook. However, if you do not have the necessary Visual Studio Runtime library (VSTOR), then the library can be installed from the Sugar Plug-in for Outlook installation file using the following steps:

Navigate to the folder where the Sugar Plug-in for Outlook file is unzipped.
Select the VSTOR40 folder then double-click on vstor40_x64.exe (for x64 platform) or vstor40_x86.exe (for x86 platform).
Next, click "Extract All" in the dialog box.
Use the extracted vstor40_x64.msi or vstor40_x86.msi file to install the latest version of VSTOR runtime. From the command line, depending on your platform, run the following command: msiexec /i vstor40_x64.msi /quiet.

Troubleshooting Installation

The following sections cover steps you can take to troubleshoot installation issues with the Sugar Plug-in for Outlook.

Updating the Required Libraries

If you have trouble with the Sugar Plug-in installing properly, your computer may have outdated versions of the required libraries installed. To resolve this, you will need to complete the following steps:

In the Windows Control Panel, click "Add/Remove Programs" or "Programs and Features" depending on your version of windows.
Select "Microsoft Visual Studio 2010 Tools for Office Runtime" then click the "Uninstall" or "Remove" button depending on your version of windows.
Re-run setup.exe to install the Sugar Plug-in for Outlook which will replace these libraries with updated versions.

Enabling the Installation Logger

If installation problems arise, an administrator user of the machine where the plug-in is being installed can enable detailed logging to capture installation data into a log file. To do so, launch the setup.exe file via command line with the "/I" option (e.g. C:\Users\username\Downloads\Sugar_Plugin_for_Outlook\setup.exe /l). This will create a new file in the installation folder that contains the log information. If issues persist, you may include the log file with your request for assistance from Sugar Support.

Configuring Outlook to Trust the Plug-in

If you are confident that installation was successful but you do not see the SugarCRM options in Outlook, you may need to tell Outlook that the plug-in is safe to run. In some cases, add-ins are mistakenly disabled by Outlook, but users can set Outlook to "Always enable this add-in" for the Sugar Plug-in for Outlook. For most versions of Outlook, navigate to File > Options > Add-ins and then click the "Go" button next to "Manage: COM Add-ins".

260-com-addins-go

For more information and steps to complete, please refer to Microsoft's documentation.