How to Upgrade Smart Previews for SharePoint O365

 

Prerequisite Operations

Before you run an upgrade operation for Smart Previews, perform the actions described below.

Database Backup

In a production environment, back up any production Smart Previews databases before continuing.

Collect Required Information

To save time, gather the following information to use during the upgrade procedures below.

Most of this information can be found from the web admin console. See below.

  • On your Smart Previews Web Admin Console page (shown above): Record the path of your current transfer folder.
    Note the example below:



  • Under Manage databases in the farm:Record the "Configuration database" string.

  • In the Windows Services console, note the accounts listed for either:
    • Smart Previews Indexing Monitoring Service
    • Smart Previews Preview Generation Service


  • Under the <SmartPreviews_Install_root>/Previews Components/Previews CEWS/ directory, open the file CewsWindows.exe.config and note the "PreviewDataRepository" value:

Configure Environment Variables

If you are upgrading from Smart Previews v3.1 or older, note the changes to the way passwords are encrypted.

Smart Previews does not encrypt passwords stored in configuration by default.

To secure passwords, configure the following environment variables before installing the product:

  • BAInsightSecurityEncriptionKey 
    • The value of this environment variable is used as encryption key for the Rijndael AES Encryption algorithm.
    • Example: RgUkXp2s5v8y/B?E(H+KbPeShVmYq3t6
  • BAInsightSecuritySaltKey
    • The value of this environment variable is used as a salt key for the Rijndael algorithm.
    • Example: TjWnZr4u7x!A%D*G-KaPdRgUkXp2s5v8
Note 1: If you want to change your encryption and / or salt keys later, you must completely reinstall and reconfigure the product.

Note 2: If you use more BA Insight products that use this encryption mechanism, the same keys are used for all such products.
If you don't know this information, please contact BA Insight Support Team.

Note 3: If you install Smart Previews in a multi-server environment, you need to set up the same environment variables on all the servers running Smart Previews.

Note 4: The priority of reading the values from the environment variables is User Environment Variables and then, if user variables are not set, the System Environment Variables are checked.
If you want to have multiple user accounts running multiple BA Insight products that use this encryption mechanism, you can either set up the environment variables for each of the users, or set up the system environment variables.
Note that System environment variables are accessible for all users and this may not align with your security policy.

Upgrade the Import Server

Uninstall the Import Server

  1. Navigate to the Services page on your server.
  2. Stop the following Smart Previews Services:
    • Smart Previews Indexing Monitoring Service
    • Smart Previews Preview Generation Service
  3. Control Panel > Programs > Uninstall a program and uninstall Smart Previews Import Server.

Install the Import Server

  1. Open a Command Prompt as an administrator and run the following command:
       msiexec /i "path\ImportServer.msi"
  2. Follow the instructions in the installation wizard.
  3. During the installation, the following information is required:

Parameter

Description

<Install Directory>

Specify the path to the Smart Previews Import Server install location.

BA Insight recommends that you use the following location:

  • C:\Program Files (x86)\BA Insight\Smart Previews Import Server\.

<Service Account>

  • The Import Server service account runs as this user.

  • If possible, use a domain admin account.

  • If not, the account you use must be a local admin on the server.

  • Specify the domain, user name, and password for this user.

Configure the Databases

Note: If a database upgrade is required, you are prompted to upgrade the database.

Proceed to upgrade before continuing.

  1. Go to Smart Previews Web Admin Console site from IIS Manager and select Connect to existing Configuration Database.


  2. Provide the Database Server Name and the Database Name.

Upgrade the Fast Proxy Service

Uninstall the Fast Proxy Service

  1. Navigate to the Services page on your server. Stop the Smart Previews Fast Proxy service.
  2. Navigate to the Previews Components folder.
  3. Open the FAST Proxy folder.
  4. Right-click the unregisterproxy.bat file and select "Run as administrator" from the sub-menu that opens.

Install the Fast Proxy

  1. Navigate to where your Smart Previews upgrade package is and extract the contents of Previews Components.zip.
  2. Navigate to the Fast Proxy folder from Previews Components.
  3. Edit the file BA_insight.FastProxyService.exe.config.
  4. Locate the applicationSettings\BAInsight.FastProxyService.Properties.Settings\ConfigurationDbConnectionStringsection and add the:
    1. Data Source: Add the server name as the value.
    2. Initial Catalog: Add the Configuration Database name as the value.
  5. Locate the applicationSettings\BAInsight.FastProxyService.Properties.Settings\FastIncomingFolder and replace %LocalLow% with the path of the BA-Insight Fast Proxy Incoming folder.
  6. Run registerproxy.bat as an administrator.
    1. During the installation, an admin account is required.
    2. The user name must be filled in using the following format: Domain_Name\User_Name.
    3. You must also specify a password for this user.
  7. Start the service.

Upgrade the Previews CEWS Service

Uninstall the Previews CEWS service

  1. Navigate to the Services page on your server.
  2. Stop the Smart Previews CEWS service.
  3. Navigate to the Previews Components directory.
  4. Open the Previews CEWS folder.
  5. Right-click the unregistercews.bat file and run as administrator.

Install the Previews CEWS service

  1. Navigate to the Previews CEWSfolder from Previews Components.
  2. Edit the CewsWindows.exe.config file.
  3. Locate the system.serviceModel\services\service\host\baseAddressesand add/replace the server name (servername).
  4. Locate the applicationSettings\BAInsight.LongitudeCews.Properties.Settings\PreviewDataRepositoryand replace %LocalLow% with the path of the BA-Insight Fast Proxy Incoming folder.
  5. Run registercews.bat as an administrator.
    1. During the installation, an admin account is required.
    2. The user name must be filled in using the following format: Domain_Name\User_Name.
    3. You must also specify a password for this user.
  6. Start the service.

Upgrade Smart Previews Hybrid

Before you uninstall your Smart Previews instance, perform the following steps:

  1. Open your IIS server.
  2. Collect the following information
    1. Application Pool Idenity
      • domain\username


    2. From Site Bindings
      • Port
      • Host Name (blurred out below)


      • Certificate
        • Note the SSL certificate used for the hybrid site (blurred out below):


  3. Navigate to your Smart Previews Hybrid installation folder.
  4. Make a copy of your existing Web.config file.

Uninstall Smart Previews Hybrid

  1. Go to the Control Panel > Programs > Uninstall a program.
  2. Right-click BA Insight Smart Previews Hybrid and select Uninstall.

Install Smart Previews Hybrid

Open a command prompt as an administrator and run the following command:

msiexec /i "path\ SmartPreviewsHybrid.msi"

During the installation, the following information is required:

Field

Description

<InstallDir>

Specify the path where the Smart Previews site will be installed.

BA Insight recommends that you use this location: C:\BA Insight\Smart Previews Hybrid\

<Port>

This port is used to run the website for Smart Previews.

For this reason, make sure the port is not used by another service.

<Certificate FriendlyName>

Specify the certificate friendly name that is used to set the SSL binding for this site.

The installer tries to access the local certificate store and look for this certificate.

The certificate must be installed in the Local Certificate Store, under Personal.

This friendly name must be associated with a certificate that is imported with a private key (.pfx) file.

<ServiceAccount>

Specify the User Name and the Password that is required to run the Smart Previews site.

This user must have Read and Write permissions to the Smart Previews Configuration Database.

The User Name must be filled in using the following format: Domain_Name\User_Name

You must also specify a password for this user.

Configure Smart Previews Hybrid

Web.config file settings migration

DO NOT reuse your old web.config file when doing a product update or upgrade.

The new web.config file contains new information.

Existing web.config settings can be preserved by using the following steps:

  1. Open your existing web.config file
  2. Open the new web.config file
  3. In your existing web.config file, copy your (modified from original) settings.
  4. Overwrite the CloudServiceAddress (around line 138) with the value from your old web.config file copy.

  1. Navigate to the Smart Previews Hybrid web site folder and open the web.config file.
    1. Locate the appSettings\CloudServiceAddress section.
    2. Replace the sample address with your Smart Previews Web Resources URL including preview proxy service as in the following example:
      https://[SmartPreviewsAddress]/Services/PreviewProxyService.svc
  2. Navigate to the Configuration page for Smart Previews Hybrid site:
    https://[SmartPreviewsAddress]/Pages/Configure.aspx
    1. Complete it with the information from the below table:

Field

Description

<Certificate Friendly Name>

  • Specify the certificate friendly name that is used to validate or secure the requests coming from the Smart Previews Web Resources web site.

  • The certificate must be installed on a local computer under the Trusted Root Certification Authorities folder.

  • Make sure that the certificate is imported using a private key.

Note: Since the request and responses must be encrypted and decrypted with the same certificate, make sure that you specify the same certificate in the Smart Previews Web Resources Configuration page.

  • For information on how to generate a self-signed certificate, go to How to Create a Self-Signed Certificate.

<Database Connection String>

  • This is the connection string for the Smart Previews Configuration database.

    • For example: Server=servername;Database=ConfigurationDatabaseName;Trusted_Connection=True;

<Preview Generation Service Address>

  • Specify the Previews Generation Service Address.

  • For example: http://<servername>:1238/PreviewGeneratorService

<Fetchers>

Repackage the Apps with Environment-Specific Settings

Procedure:

  1. Download the App Repackager if you haven't already.
  2. Follow the "AppRepackager - User guide for Smart Preview.docx" instructions in the App Repackager to update the files:
    1. BAInsight.AppRepackager.webconfig.exe
    2. BAInsight.AppRepackager.webconfig
    3. Smart Preview Web Resources .zip file
    4. SmartPreviewHybridCloud.app
  3. You need the information listed below to use the App Repackager.
  4. All of this information is stored in the web.config file for your Azure App service.
    • Use the App Service editor on the Azure Portal to open the file.
      1. Client ID
      2. Client Secret
      3. Azure Web App domain
      4. Azure Web App app URL

Publish the Smart Preview Web Resources to the Azure Web App

Procedure:

  1. Unzip the file "SmartPreviewsFrontEnd.zip" after modifying it with the App Repackager application.
  2. Using an FTP client, publish the extracted files to your Azure Web app.
    1. The FTP access credentials can be found in the "PublishSettings" file downloaded after provisioning the Azure Web App.
    2. Publish the root of the .zip folder to the wwwroot folder in the Azure site.


  3. Once the FTP transfer is complete, it may take several minutes before the Azure app is available.
    1. You can test the Azure app by navigating to the following Azure Web App URL:
         https://<your preview app name>/azurewebsites.net
  4. You see an empty or blank page.

Publish the SharePoint Online App to your SharePoint Online App Catalog

  1. Navigate to your SharePoint Online Admin Center>App Catalog.
  2. Open "SharePoint Apps".


  3. Click "Upload" and upload the SmartPreviewHybridCloud.app that you updated with the App Repackager.

    When upgrading, you must upload a .app file with the same name. If you modify the file name prior to uploading, ensure you keep a note so that the same file name can be used on upgrade.

Upgrade the Enrichment Component

Note: If Previews are generated with the SharePoint 2013/2016 perform this step, else skip it.

Open a SharePoint Management Shell as administrator and run the following:

Upgrade
Copy 
$endpoint = "http://servername:1237/ContentProcessingService"   $ssa = Get-SPEnterpriseSearchServiceApplication –Identity $ssaName - wa silentlycontinue          
   $config = New-SPEnterpriseSearchContentEnrichmentConfiguration
   $config.Endpoint = $endpoint
   $config.DebugMode = $true
   $config.Timeout = 30000
   $config.InputProperties
 = "IsDocument", "body", "Author", "Filename", 
"FileType","MimeType","FileExtension","OriginalPath", 
"url","ContentType","contentclass","LastModifiedTime","Size", 
"escbasecrawlurl"   $config.SendRawData = $True
   $config.MaxRawDataSize = 71680
   $config.FailureMode = "Warning"   Set-SPEnterpriseSearchContentEnrichmentConfiguration –SearchApplication $ssa –ContentEnrichmentConfiguration $config

 

For Users Upgrading Connectivity Hub

If you are upgrading Connectivity Hub from version 2.0 to 2.1 or later, run the following script against your Smart Previews database before the upgrade to keep previews and content indexed synchronized.

The script can be found in the following Connectivity Hub installation directory:

  • <ConnectivityHubInstallDir>\DatabaseCreationScript\UpdateSmartPreviewsDatabases.sql

Before running the script, replace the following tokens:

  • #SmartPreviews_Configuration_DB#

    • Put configuration database name here.

  • #SmartPreviews_PreviewCache_DB#

    • Put preview cache database name here.

    • If your installation of Smart Previews uses multiple preview cache databases, run the script for each preview cache database separately.

  • #SmartPreviews_UserProfile_DB#

    • Put user profiles database name here.

The script below is provided for reference.

Run the script which is deployed by the Connectivity Hub installer.

Copy
Example Script
DECLARE @batchSize int = 1000;
 
DECLARE @ids TABLE(Id int);
DECLARE @lastId int = 0;
 
USE #SmartPreviews_Configuration_DB# -- Put Configuration database name here.
 
PRINT 'Updating [ProcessedDocuments] table.'
WHILE @lastId = 0 OR EXISTS(SELECT 1 FROM @ids)
BEGIN
    DELETE FROM @ids;
    INSERT INTO @ids
        SELECT TOP(@batchSize) ProcessedDocumentId
        FROM ProcessedDocuments
        WHERE DocumentUri LIKE 'spworks://%' AND ProcessedDocumentId > @lastId
        ORDER BY ProcessedDocumentId;
 
    SELECT @lastId = MAX(Id) FROM @ids;
     
    UPDATE ProcessedDocuments
        SET DocumentUri = REPLACE(REPLACE(REPLACE(REPLACE(DocumentUri, '&id=&', '&'), '&subid=&', '&'), '&fid=&', '&'), '&fsubid=&', '&'),
            UriHash = CONVERT(binary(16), HASHBYTES('MD5', REPLACE(REPLACE(REPLACE(REPLACE(DocumentUri, '&id=&', '&'), '&subid=&', '&'), '&fid=&', '&'), '&fsubid=&', '&')))
        WHERE ProcessedDocumentId IN (SELECT Id FROM @ids);
END
 
USE #SmartPreviews_PreviewCache_DB# -- Put PreviewCache database name here.
 
PRINT 'Updating [DocumentContainer] table.'
SET @lastId = 0;
WHILE @lastId = 0 OR EXISTS(SELECT 1 FROM @ids)
BEGIN
    DELETE FROM @ids;
    INSERT INTO @ids
        SELECT TOP(@batchSize) DocumentContainerId
        FROM DocumentContainer
        WHERE DocumentUri LIKE 'spworks://%' AND DocumentContainerId > @lastId
        ORDER BY DocumentContainerId;
 
    SELECT @lastId = MAX(Id) FROM @ids;
     
    UPDATE DocumentContainer
        SET DocumentUri = REPLACE(REPLACE(REPLACE(REPLACE(DocumentUri, '&id=&', '&'), '&subid=&', '&'), '&fid=&', '&'), '&fsubid=&', '&')
        WHERE DocumentContainerId IN (SELECT Id FROM @ids);
END
 
USE #SmartPreviews_UserProfile_DB# -- Put UserProfiles database name.
 
PRINT 'Updating [ResearchNotebooks] table.'
SET @lastId = 0;
WHILE @lastId = 0 OR EXISTS(SELECT 1 FROM @ids)
BEGIN
    DELETE FROM @ids;
    INSERT INTO @ids
        SELECT TOP(@batchSize) ProcessedDocumentId
        FROM ResearchNotebooks
        WHERE DocumentUri LIKE 'spworks://%' AND ProcessedDocumentId > @lastId
        ORDER BY ProcessedDocumentId;
 
    SELECT @lastId = MAX(Id) FROM @ids;
     
    UPDATE ResearchNotebooks
        SET DocumentUri = REPLACE(REPLACE(REPLACE(REPLACE(DocumentUri, '&id=&', '&'), '&subid=&', '&'), '&fid=&', '&'), '&fsubid=&', '&')
        WHERE ProcessedDocumentId IN (SELECT Id FROM @ids);
END
 
PRINT 'Crawl URLs have been updated.'

How to Validate Your Upgrade is Successful

Go to your search center and run a query to view the documents that have kept the generated previews.

Check your previews.