SugarCRM SupportProduct GuidesInstallable ConnectorsHintHint Installation and Administration Guide

Hint Installation and Administration Guide

Overview

Hint is a relationship intelligence service that is available to be purchased and installed on your Sugar instance to make external information available for your contacts, leads, and accounts in Sugar. Data such as social media accounts, work information, and company details are visible for contacts and leads based on their email address and for accounts based on their websites and company names. Users can also quickly import the enriched data into the Sugar database with a single click. This guide walks through the steps to install and configure Hint in an on-site Sugar instance as well as how to uninstall the package. For information on using Hint once it has been installed, please refer to the Hint User Guide.

Prerequisites

Hint can be purchased by contacting your Sugar partner or representative and an admin user must then download the Hint package and install it to your instance using the instructions in this guide. The package will be available for download after you receive your purchase confirmation email. After installing Hint, SugarCRM will automatically upgrade Hint for cloud instances as new versions are released. If your instance is hosted elsewhere, an administrator must install Hint and, as new versions are released, upgrade Hint using Module Loader. The following prerequisites must be met before installing Hint on an on-site Sugar instance:

  • You must be an administrator to access Module Loader as required by this guide.
  • Cron must be enabled because Hint relies on several scheduled jobs to function.
  • Your Sugar instance must be upgraded to at least the minimum supported version of Sugar. For more information on supported platforms, please refer to the Connectors Supported Platforms page.
  • If you would like Hint to connect to Hint services in a region other than the region where your Sugar instance is installed, you must specify the Hint services region before installation. It is not possible to choose a different region after installation.
  • If your server has firewalls set up that block direct access to the internet, you must whitelist the following Hint service URLs in order for Hint to work:
  • When it is installed, the Hint package merges changes to several layout and JavaScript files. If you have other customizations in these files, it is recommended to back them up prior to installing the Hint package. For more information, refer to the Using Hint With Your Sugar Customizations article.

Note: Current and prospective Sugar customers can request an evaluation or demo of Hint from Sugar's home page.

Getting Started with Hint

The following steps are covered on this page and are required before you and your users can begin using Hint:

Downloading Hint

Once you have purchased Hint and received a confirmation email, customers can use the following steps to access and download the Hint package:

  1. Log in to your SugarCRM.com account. For more information on setting up a SugarCRM.com account, please refer to the Managing Your Sugar Subscription article. 
  2. Navigate to your Software Downloads page.
  3. Select "Relationship Intelligence" from the dropdown menu at the top of the page.
  4. Expand the panel that shows your current version of Sugar and click on the appropriate .zip file to download Hint.
    download-mgr

You may now install the .zip file to your Sugar instance using Module Loader. Please refer to the Installing and Upgrading Hint section for further instructions.

Installing and Upgrading Hint

For on-site Sugar instances, an administrator must install Hint and, as new versions are released, upgrade Hint using Module Loader. Customers on Sugar's cloud service will only need to install Hint initially; upgrades will be applied automatically. To get the latest software package, follow the steps in the Downloading Hint section.

Use the following steps to install or upgrade Hint after ensuring that all prerequisites have been met:

  1. If you are upgrading Hint on a Sugar version lower than 8.1.0, or if you are upgrading from Hint 4.1.x on any Sugar version, please uninstall the previous version of Hint before continuing with these steps.
  2. Navigate to Admin > Module Loader.
  3. Click the "Choose File" button to find and select the .zip file you downloaded in the Downloading Hint section.
  4. Click "Upload".
    Hint Install Upload
  5. Once the new version of Hint appears in the lower panel, click its adjacent "Install" button.
    Hint Install Install
  6. Click "Commit" to begin the installation.
  7. Finally, clear your browser's cache before using or configuring Hint.

Note: To ensure that installed fixes take effect after upgrading your Hint installation, all users should clear their browser cache and then log out and back into Sugar. If other integrations are affected by the installation or upgrade of Hint, perform a Quick Repair and Rebuild, which often resolves installation issues.

Choosing the Hint Services Region

By default, Hint is automatically configured to connect with services hosted in the supported region nearest to that of the Sugar instance on which it is being installed. The regions supported by the Hint services are the United States and Europe. If you wish to manually specify which region's Hint services you want Hint to connect to, you can update the system config_override.php file before Hint installation. In particular, you can add the optional hint.hint_install_target_geo property to select a region. See the Core Settings page in the Developer Guide for details on this property.

Note:  Once configured, it is not possible to modify the region Hint connects to. Switching regions requires completely uninstalling and reinstalling Hint, which will cause you to lose all existing system and end-user settings.

Setting the Hint License Type

In most cases, users are automatically assigned a Hint license. On Sugar 10.3.0 and higher, you will see the Hint value in the License Type field on user records; this value is automatically set for users on installation or upgrade of Hint 5.4.0 and higher, including if you have Hint 5.4.0 and then upgrade Sugar to 10.3.0 or higher. However, if you have fewer seats of Hint than you do of Sugar, it will not be possible for every user to be automatically assigned the Hint license. In this scenario, Hint assigns licenses to active users in the order of most recent activity until all Hint seats are assigned. As a result, an admin may need to update user records to redistribute the Hint licenses as needed. To do this, you can either mass update all or a subset of active users or individually update specific users to add the Hint license type after installation. For more information on updating user records, refer to the User Management documentation. For more information on license types, refer to the Understanding User Types, License Types, and Sugar Licenses article.

Admins without the Hint license type can still access Hint configuration in the Hint section of the Admin page. If you remove the Hint license type from a user, that user will no longer have access to Hint (e.g. the Hint panel or Hint Insights dashlet) and will no longer receive notifications for any of their Hint Insights subscriptions. However, their notification settings are preserved and notifications resume if you assign the Hint license type to the user again. Note that the Hint license type cannot be selected alone and must be applied in conjunction with a CRM license type (e.g. Sell or Serve).

Uninstalling Hint

Uninstalling the Hint package removes Hint from your instance if you no longer wish to use the service. Also, for instances running a Sugar version lower than 8.1.0, Hint must be uninstalled prior to upgrading to a newer Hint package.

Uninstalling or upgrading Hint on Sugar versions lower than 8.1.0 will remove certain layout and JavaScript files from the instance. If these files contain customizations made outside of Hint, those customizations will be lost when the uninstall of Hint removes the files. As a workaround, it is recommended to back up these files prior to uninstalling Hint, complete the uninstallation, then restore the files. For more information, refer to the Using Hint With Your Sugar Customizations article.

Hint 5.4.0 and higher includes an Uninstall tool in the Admin page of Sugar instances on versions 10.2.1 and higher. This Uninstall feature uninstalls Hint more cleanly than Module Loader does and as a result, it is recommended to use this tool provided by Hint when possible to complete uninstallation. The provided tool better handles disconnecting from the Hint services and removing all configurations from your Sugar instance, and even allows you to maintain all Hint Insights subscriptions upon reinstallation if desired. It is still possible to use Module Loader, but if you do, Hint Insights notifications may not stop after uninstallation and it will not be possible upon reinstallation of Hint to resume the previously configured notifications.

Use the following steps to uninstall Hint using the provided Uninstall tool on Hint 5.4.0 and higher when installed on Sugar 10.2.1 and higher:

  1. Navigate to Admin > Hint and open the Uninstall page.
    AdminUninstall
  2. Select whether you wish to only uninstall the Hint package or completely uninstall all of Hint. See the Uninstallation Types section below for a description of each option but note that the Uninstall Hint Completely option deletes all Hint settings and cannot be undone.
    Uninstall
  3. Click the Uninstall button and accept the confirmation pop-up that appears to start the process. Uninstallation may take several minutes and will reload the Admin page once complete.

It is not recommended to uninstall Hint using Module Loader on instances where Hint's uninstallation tool is available because the tool provided by Hint completes the process more cleanly. However, on Hint 5.3.4 and lower, or on Sugar 10.2.0 and lower, you can use the following steps to uninstall Hint:

  1. Navigate to Module Loader.
  2. Find the active Hint version in the upper panel of Module Loader and click its adjacent "Uninstall" button.
  3. Choose the row in the table below that applies to you and complete the relevant step on the Ready to Uninstall screen:
    Hint Version Do You Plan to Upgrade? Recommended Action to Take
    4.0.0 and lower Yes Cancel out of this uninstall procedure. Older versions of Hint may not offer the "Do Not Remove Tables" option. You will lose your accumulated Hint data by uninstalling. To avoid this loss of data during an upgrade, please proceed directly to the Installing and Upgrading Hint section now.
    No Proceed with uninstalling Hint. All data associated with Hint will be permanently removed from your instance.
    4.0.1 - 4.1.1 Yes Select "Do Not Remove Tables" to keep the fields added by Hint in Sugar, then proceed with uninstalling Hint.
    No Select "Remove Tables" to permanently delete all data associated with Hint from your instance, then proceed with uninstalling Hint.
    5.0.0 and higher Yes Proceed with uninstalling Hint. All data associated with Hint will remain in your instance. 
    No Proceed with uninstalling Hint. All data associated with Hint will remain in your instance.
  4. Click "Commit" to begin uninstalling Hint. Sugar will take several minutes to complete the uninstall process and then display a confirmation.

If you followed either of these sets of steps to remove Hint altogether, you have completed the process. To install a new version of Hint in place of the uninstalled version, please proceed to the steps in the Installing and Upgrading Hint section.

Uninstallation Types

There are two uninstallation types when using Hint's included Uninstall feature, accessible in the Hint section of the Admin page. It is important to choose the correct option based on if and how you plan to use Hint again in the future. See the sections below for a description of when to use each one.
AdminUninstall

Uninstall Hint Package Only

Choose the Uninstall Hint Package Only option if you may want to install Hint again in the future. This option removes the actual Hint module loadable package (MLP) and disables all active Hint Insights notification subscriptions, whereas uninstallation via Module Loader does not disable notification subscriptions. If you use this option in the provided Uninstall tool, all of your users' notification settings will be preserved and notifications will resume if you choose to reinstall Hint later.

Uninstall Hint Completely

Choose the Uninstall Hint Completely option if you do not intend to install Hint again in the future, or if you want to completely remove all of your users' settings and start from a clean installation of Hint. This option removes the module loadable package (MLP) and also deletes all configuration and Hint Insights notification subscriptions. There is no way to undo this action, so be sure to complete a full backup of your Sugar instance before completing this process. It is also best to put Sugar into maintenance mode before starting; see the Advanced Configuration Options page in the Sugar Administration Guide for more details on doing this.

Admin Configuration

Optionally, an administrator can configure the fields enriched by Hint or shown in the Hint preview panel for leads, contacts, and accounts. Each module's Hint panel may be configured independently. Admins can also configure the Hint logger, turn off Hint notificationsresync with the Hint Insights service, and uninstall Hint in the Hint section added to the Admin page. Note that it is recommended to use the Uninstall tool that is included with Hint to remove Hint instead of doing so via Module Loader. Hint's Uninstall tool better handles disconnecting from the Hint services and removing all configurations from your Sugar instance, and even allows you to maintain all Hint Insights subscriptions upon reinstallation if desired.

The following two sections describe the available Hint fields and how to configure the Hint dashboard panels to meet your organization's needs.

Understanding Hint Fields

Hint adds a new panel to the bottom of record view layouts in the Contacts, Leads, and Accounts modules, which causes the Show More panel to be automatically expanded. The Hint panel in record view displays the fields added by Hint during installation. 

The following custom fields will be added to your modules and their record views. An administrator can add these fields to other layouts (e.g. Mobile, list view, etc.) if desired via Admin > Studio. For more information on modifying layouts, please refer to the Studio documentation.

Display Label Database Name Type Added to Accounts Added to Contacts Added to Leads
Annual Revenue hint_account_annual_revenue_c TextField  
Company Description hint_account_description_c TextField  
Company Facebook hint_account_facebook_handle_c URL
Company Location hint_account_location_c TextField
Company Logo 1 hint_account_pic_c, hint_account_logo_c Image, URL    
Company Size hint_account_size_c TextField
Company Twitter hint_account_twitter_handle_c URL  
Company Website hint_account_website_c TextArea    
Education hint_education_c TextField  
Education Additional 2 hint_education_2_c TextField  
Facebook Link hint_facebook_c URL  
FY End hint_account_fiscal_year_end_c TextField
Industry hint_account_industry_c TextField
Industry Tags hint_industry_tags_c TextField
NAICS Code hint_account_naics_code_label_c TextField
Previous Jobs hint_job_2_c TextField  
SIC Code hint_account_sic_code_label_c TextField  
Twitter Link hint_twitter_c URL  
Year Founded hint_account_founded_year_c TextField

In the database, the Company Logo field is represented by two fields: hint_account_pic_c, which is the actual image field you see, and hint_account_logo_c, which contains the URL location of the image.
The Education Additional field is not listed in Admin > Hint Fields because it is always displayed as the second line of the Education field in the Hint panel. Any configurations applied to the Education field are automatically applied to the Education Additional field for the module.

Hint also uses some of Sugar's stock fields to store enriched data. The following stock fields in the Contacts, Leads, and Accounts modules are populated when downloading Hint's enriched data. If you have modified your layouts to remove these fields, you may want to add them back to your layouts via Admin > Studio. For more information on modifying layouts, please refer to the Studio documentation.

Display Label Database Name Type Populated for Accounts Populated for Contacts Populated for Leads
Account Name account_name TextField    
Annual Revenue annual_revenue TextField    
Avatar picture Image  
Description description TextArea ✔     
Mobile phone_mobile Phone  
Office Phone phone_work Phone  
Other Phone phone_other Phone   ✔  ✔ 
SIC Code sic_code TextField    
Title title TextField  
Twitter Account twitter TextField    
Website website URL   ✔ 

Users without a Hint license can see imported values in these fields if the fields are displayed on their record view. Note that by default, the panel that Hint adds to record view is only visible to Hint users, but the custom fields it contains can be added to other places (e.g. a different panel in record view) to allow non-Hint users to see the data.

Configuring Hint Fields

Administrators can navigate to Admin > Hint Fields to personalize the Hint dashboard panel by showing, hiding, and rearranging the displayed fields, as well as enabling and disabling enrichment for each one. The Hint Fields drawer displays all of the fields found in Studio for the module along with the Hint fields for that module.

On the right-hand side is a list of fields available to be configured. The top section, Enriched Fields, lists all fields that Hint can enrich, including both those added by Hint and stock Sugar fields. The bottom section, Additional Sugar Fields, lists all fields that Hint cannot enrich; you may wish to show these in the Hint panel for informational purposes when viewing the Hint preview from list view. Enabling "Show in Hint" for enriched fields displays them in the Hint dashboard panel and the Hint section of record view. Enabling "Show in Hint Panel" for additional Sugar fields simply displays them in the Hint dashboard panel. The search bar at the top can be used to look for a specific field in either section.
Admin RHS

In the Enriched Fields section, fields marked with an asterisk (*) are fields added by Hint. They can only be shown in the Hint panel if they are enriched, and so disabling enrichment for them also disables the Show in Hint checkbox. There are also some fields with the Show in Hint checkbox hidden; these fields cannot be removed from the view because Hint is designed to always show them. Likewise, fields in the Additional Sugar Fields section with the Show in Hint Panel checkbox disabled can also not be removed.

On the left-hand side is a live-updated view of what the Hint panel will look like as you make your changes. Each module is displayed in its own tab and switching between tabs updates the list of fields on the right as well.
Admin Tabs

To configure the Hint panel for a module, update the checkboxes for each field on the right-hand side. Disabling "Enrich Field" prevents Hint from returning any enriched data for that field. Once you have the desired fields displayed, drag and drop items directly within the layouts to reorder them. Those displayed with a lock icon cannot be moved or hidden because Hint is designed to always show these fields.
Admin DragAndDrop

Once you are satisfied with your changes for each module, click "Save" to preserve all three modules' configurations. To restore the specific tab you are viewing to its default values, see the Restoring Default Settings section.

Restoring Default Settings

If you would like to revert the Hint fields for a specific module to its default state, use the link at the bottom of the tab. Clicking this link immediately restores the current tab to its original state. It is recommended to only restore the default settings if you have not already manually made changes to the configuration without saving. That way, if you restore the defaults and decide you do not want to keep this change, you can simply click "Cancel" to close the drawer and undo the reversion.
Admin RestoreDefaults

Configuring the Hint Logger

The Hint logger writes log entries to the Sugar log to help you debug potential unexpected behavior. The default log level is "Alert" but it can be changed to levels such as "Critical", "Info", or "Debug" in Admin > Hint Configuration. Navigate to Admin > Hint Configuration and select the desired level in the dropdown menu in the Hint logger section and click "Save" to preserve the change. The new log level will be used immediately.

Turning off Hint Notifications

Occasionally, it is useful to turn off all notifications (i.e. email, desktop pop-up, and Hint Insights dashlet) for an entire Sugar instance. One particular example is when you are cloning an instance, such as for troubleshooting purposes. If you clone an instance where users are subscribed to Hint notifications, they will start to receive duplicates of all email notifications - one from the original instance and one from the clone. To avoid this, navigate to Admin > Hint Configuration on the cloned instance to turn off notifications and save this change before enabling cron. This way, users will continue to receive notifications from the production instance and will not receive any duplicates once you enable cron on the clone.

Resyncing With the Hint Insights Service

If you are seeing inconsistent behavior in notifications from the Hint Insights service, you may need to resync with the service. This inconsistency may manifest as changes to preferences and email addresses not taking effect.

To resync, click "Resync with the Hint Insights service" in the Hint section of the Admin page. A popup will appear asking you to confirm that you wish to proceed with the sync. It is important to note that performing a resync will cause any pending email digest stories to be lost and existing news to be cleared from the Hint Insights dashlet.

Notifications of all types will resume after the sync completes.

Last modified: 2021-07-13 14:14:44