SugarCRM SupportProduct GuidesPlug-insMS Excel Plug-inMS Excel Plug-in Installation Guide

MS Excel Plug-in Installation Guide

Overview

Sugar's Plug-in for Microsoft Excel enables Sugar® users to create, delete, update, and view Sugar data using an Excel spreadsheet. This documentation explains how to install the plug-in, which is available for use with all supported versions of Sugar. 

To learn how to use the plug-in, please refer to the MS Excel Plug-in User Guide.

Prerequisites

You must install the Plug-in for Microsoft Excel on the computer where you want to use it. 

  • Windows PC : The Sugar Plug-In for Microsoft Excel must be installed to a Windows-based computer.
  • Microsoft Excel : You must have a supported version of Microsoft Excel installed on the computer where you want to use the plug-in. For the latest list of supported software versions, please refer to the Plug-Ins Supported Platform page.
  • Windows administrator account : A person installing software should use the computer's administrator account, which lets you make changes that will affect other users. If the administrator user is not the same profile that will be using the plug-in (e.g. the administrator user for the computer is not the primary user of the PC), then be sure to install the plug-in for all users of the machine. This is typically the default setting. 
  • Microsoft .NET Framework 4 : You must have the Microsoft .NET Framework 4.0 or later installed on the computer where you want to use the plug-in.
  • Uninstall older plug-in versions (if needed) : You must first uninstall any older versions of the Sugar Plug-In for Microsoft Excel before installing an updated version. 

Checking for the Required Libraries

The Sugar Plug-in for Excel requires several supporting library components that must exist on your computer before installing the plug-in:

  • Microsoft Office Primary Interop Assemblies
  • Microsoft Visual Studio Tools for Office SE Runtime
  • Microsoft .NET Framework

The installer will scan your computer for these items and install the first two the libraries if the scan does not find them. Most Microsoft PCs already have the .NET Framework installed, but in the case that yours does not, you must install this in advance of the installation process. To determine if you have the Microsoft .NET framework installed and updated to the correct version, follow these steps:

  1. Open your computer's Control Panel and select "Add or Remove Programs" or "Programs and Features," depending on your version of Windows.
  2. Scroll through the list of installed programs until you reach listings beginning with "Microsoft." Check the program list for "Microsoft .NET Framework x.x."
  3. Confirm that the framework's version is 4.0 or later.

If you do not have Microsoft .NET Framework 4.0 or later installed, go to http://www.microsoft.com/net/Download.aspx to download and install the latest version.

Uninstalling Previous Versions

If you have a previous version of the Sugar Plug-in for Excel installed on your machine, please uninstall the old version before installing the new version. If you do not remove the previous version, then "SugarExcel" may appear multiple times in the Control Panel's Programs list. Use the following steps to uninstall a previous version of the Sugar Plug-in for Microsoft Excel:

  1. Quit Microsoft Excel and close any related windows and programs.
  2. In the Windows Control Panel, click "Add or Remove Programs" or "Programs and Features," depending on your version of Windows.
  3. On the following window, select "Sugar Excel" then click the "Uninstall" or "Remove" button, depending on your version of Windows.
  4. A pop-up message will display asking for confirmation. Click "Yes" to proceed.
  5. A pop-up message will display asking if you wish to keep the settings.
    • Click "Yes" if you want to save the deleted plug-in's user settings (most common when upgrading an existing user's plug-in).
    • Click "No" if you would like to delete the data during the uninstallation (most common when updating the plugin for a different Sugar user). 
  6. After removing the plug-in, close the Control Panel's windows.

Warnings

  • If you install the Excel plug-in as a standard Windows user (i.e. non-administrator) the installation may fail.
  • If SAML authentication is enabled in the Sugar application, Sugar Plug-in for Microsoft Excel cannot connect to Sugar.

Steps to Complete

The steps below will go through how to access and install the zip file required to download and install Sugar Plug-in for Excel.

  1. Confirm the Microsoft Excel version on your computer.
  2. Download the Sugar plug-in for Excel file.
  3. Install the Sugar plug-in for Excel.
  4. Connect the installed plug-in with Sugar.

Finding Your Version of Microsoft Excel

You may know which version of Microsoft Office you use (e.g. Office 2010, Office 365, etc.), but you also need to know if your Office suite contains the 32-bit or 64-bit version of Excel. This section explains how to find the exact version of your Excel software.

Note: A 64-bit computer can (and often does) run a 32-bit Excel application, so it is best to check this before running the installation.

First, launch Microsoft Excel and create a new document. Each version of Excel will have a slightly different layout. Look for the "About" or "About Excel" option. The following list briefly addresses where to find this option in the supported versions of Excel:

  • Microsoft Office 2010 : File (tab) > Help 
  • Microsoft Office 2013 :  File (tab) > Account > About Excel
  • Microsoft 365 : File (tab) > Account > About Excel

A window should appear displaying the required information. In the example shown here, the version is Microsoft Office Standard 2010, and its bit version is 64-bit (i.e. Excel 2010 64-bit):


about

Downloading Sugar Plug-in for Excel

You can download the appropriate Sugar Plug-in for Excel file by logging into your Sugar instance and clicking the Downloads tab in your user profile. The installation file (e.g. Sugar Plug-in for Excel 2.0.0) will save to a location on your computer and will work with all supported versions of Excel.
EPI DownloadsTab

Installing Sugar Plug-in for Excel

Installing via Setup Wizard

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

  1. Navigate to the folder where you saved the downloaded file and extract the contents of the zip file.
  2. In the new window, click on the x64 (for 64-bit Excel application) or x86 (for 32-bit Excel application) folder depending on your bit version of Excel.
  3. Click the setup.exe file to run the installation. If your computer is not configured to display file extensions, then the file will appear as "setup" without the .exe extension.
    Note: A Security Warning pop-up window may appear. Click "Run" to proceed with the installation.
    setupfile
  4. On the Welcome step of the setup wizard, click "Next" to proceed with the installation process.
  5. On the License Agreement step, select "I Agree" and then click "Next".
  6. On the Select Installation Folder step, leave the installation directory set to the default path, select "Just me", and click "Next".
    EPI Install SelectInstallFolder
  7. On the Confirm Installation step, click "Next" to start the installation on your computer.
  8. Once the installation has completed successfully, click "Close" to exit.
  9. Now, open up your Excel application to connect the Excel plug-in to your Sugar instance. 

Installing via Silent Install

Use the following steps to run a silent install for Sugar Plug-in for Excel:

  1. Download the appropriate installation file to your desktop.
  2. Launch the DOS command window and navigate to the unzipped installation directory.
  3. 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
  4. Enter exit to close the command window.

Connecting Sugar Plug-in for Excel

You must configure the Excel plug-in to connect to your Sugar instance so that they can communicate with each other. After installing the Sugar Plug-in for Microsoft Excel, open Excel and view the navigation ribbon's Home tab. If the installation succeeded, the SugarCRM group will appear in the rightmost segment of the tab:
ribbon

Note: If you do not see the SugarCRM menu, please refer to the Troubleshooting section of this page.

Follow these steps to enter your Sugar credentials and log in:

  1. Click on the SugarCRM menu in the Excel ribbon and click on "Settings".
    settings1
  2. In the default Connection tab, enter the credentials and web address you use to log into your Sugar instance and click "Test Settings".
    test-settings
    Note:
    The URL field must begin with "https://".
    • If the test is successful, a Success message will appear. Click "OK" and then click "Login" to connect to the Sugar instance.
    • If the test is not successful, an alert will inform you if the failure is due to a mistyped URL or improper credentials. Click "OK" to adjust the settings and then click "Test Settings" again. When a success message appears, click "OK" and then click "Login" to connect to the Sugar instance.

Now when you click on the SugarCRM menu in the Excel ribbon, you should be given more options such as "Refresh Reports", "Select Reports", "Query Wizard", "Insert" etc. For more information on using the Sugar Plug-in for Excel, please refer to the MS Excel Plug-in User Guide.

Troubleshooting

The following sections contain ideas that may help drive frequent customer inquiries to quick resolutions.

Installation Failure

If you have satisfied the prerequisites for installation and the installation process completed without error but you do not see the SugarCRM menu in Excel's ribbon, check if Excel has disabled the plug-in.

  1. Navigate to File > Options > Add-ins.
  2. The default view shows active Excel add-ins. Look for an add-in named "Excalibur"in the list.
    • If you do not see the Excalibur (/SugarExcel/Excalibur.vsto) file listed in the active add-ins list, enable it:
      • Beneath the active file list, find the "Manage..." dropdown. Select "Disabled items" and then click "Go".
      • In the Disabled Items window, look for "Excalibur", select it, and click "Enable".
    • If you see the Excalibur (/SugarExcel/Excalibur.vsto) file listed in the active add-ins list, disable and then re-enable it: 
      • Beneath the active file list, find the "Manage..." dropdown. Select "COM Add-ins" and then click "Go". 
      • In the COM Add-Ins window, remove the checkbox next to Excalibur and click the OK button.
      • Return to File > Options > Add-ins.
      • Select "COM Add-ins" from the "Manage..." dropdown and then click "Go". 
      • In the COM Add-ins window, re-select the checkbox next to Excalibur and click the OK button.

You should now see the SugarCRM item in Excel's ribbon.

Installation Error

During the installation process, you are prompted with a message similar to, "Microsoft Excel 2010 32bit(x86) was not detected on this machine. Please confirm you are using the proper setup of plugin."
wrongbitinstall

You may have downloaded the incorrect Sugar Plug-in file. Please review the steps to confirm your Excel version, download the correct version, and re-install according to the Install Sugar Plug-in for Excel section of this page.

Connection Error

After entering your login credentials and Sugar instance URL in the settings window, you see a message that says "Unable to Connect to the URL provided."
unabletoconnect

Click "OK" to close the error message and confirm that you entered the correct URL:

  • Confirm that the instance URL begins with "https://" and not "http://".
  • Confirm that your Sugar instance's server is up and running by navigating to Sugar and reloading any page. If the page refreshes in the typical amount of time, then the server is working normally. If it fails to load or takes much longer than usual, check with your Sugar administrator to resolve the server connection issue.
  • Does the instance URL redirect you to another destination address? If so, please enter the final destination address into the SugarCRM Excel Add-In Settings window and try to connect again.

Last modified: 2020-01-23 14:28:53