Upgrade Hub and Interact

Click this icon on the toolbar to view and download a PDF version of this guide.

Upgrading Hub and Interact is a simple process that uses dedicated tools. You need to run the upgrade tools in the following order, starting with the version you are currently using:

• Upgrade from 4.0 to 4.1.
• Upgrade from 4.1 to 4.2.
• Upgrade from 4.2 to 4.3.
• Upgrade from 4.3 to 4.4.
• Upgrade from 4.4 to 4.5.
• Upgrade from 4.5 to 4.6.
• Upgrade from 4.6 to 4.7.

After you have completed the upgrade, advise your users to log into Hub and clear the cache by pressing CTRL + F5. This will refresh all web pages and ensure that any user interface changes are updated.

Upgrade Hub and Interact 4.0 to version 4.1

It is recommended that you schedule the upgrade to take place outside of working hours.

Prerequisites

• Version 4.0 of Hub and Interact is installed.

• Everyone is logged out of the IMS Server.

• You have backed up all relevant databases. Although the databases are not impacted by the upgrade, it is recommended that databases are backed up before performing any upgrade.

The upgrader automatically stops any running websites as part of the upgrade process. You do not need to manually stop them.

Upgrade steps

1. Download the Blue Prism Interact and Hub Upgrader for version 4.0 to 4.1 from the Blue Prism Portal.
2. Run the upgrader and follow the instructions.

3. Once the upgrader has completed, log in to Hub and open the plugin repository.

   The repository will show that there are plugins ready to update with details of the currently installed and available versions displayed.

4. Select the All check box and click Complete updating.

   The new versions of the selected plugins are installed and the upgrade to version 4.1 is complete.
   

5. Repeat the process on all machines on which Hub is installed.

Upgrade Hub and Interact 4.3 to version 4.4

Upgrade Hub and Interact 4.4 to version 4.5

Upgrade Hub and Interact 4.5 to version 4.6

As part of this upgrade:

• The Windows Authentication feature is installed in IIS and applied to the Authentication Server website.
• New queues are created in RabbitMQ – you will need to manually remove the old queues.

• The Blue Prism API URL is removed from the web server configuration file – this prevents Control Room from being able to communicate with Blue Prism. To continue using Control Room, you will need to re-enter this URL by logging into Hub as an administrator and entering the URL in the API configuration section on the Environment management page.

  You must enter the full URL including the protocol, such as, http:// or https://. For example: https://bpapi.yourdomain.com

It is recommended that you schedule the upgrade to take place outside of working hours.

Prerequisites

• Version 4.5 of Hub and/or Interact is installed.

• Everyone is logged out of Authentication Server.

• The user account performing the upgrade has sysadmin level access to the databases.

• You have backed up all relevant databases.

• 2.5 GB of free disk space on the server where Hub and/or Interact are installed – This is required for the backup that is created until the installation process is complete. Remove any backups from any previous upgrades.

The upgrader automatically stops any running websites as part of the upgrade process. You do not need to manually stop them.

Upgrade steps

1. Stop all the Application Pools for the Hub and Interact sites.

2. Stop the following three Windows services on the web server:

   • Blue Prism - Audit Service Listener
   • Blue Prism - Log Service
   • Blue Prism - Submit Form Manager

3. Open RabbitMQ and delete all the queues that start with the following:

   • BPC.*
   • Connect.*
   • ImsServer.*
   • Interact.*

   Alternatively, you can use the following PowerShell script to carry out this step. You must run this script on the server hosting RabbitMQ, and replace the folder path in the first line of the code with the path to the sbin folder for your implementation.

   Copy

   $rmqsbindir = "C:\Program Files\RabbitMQ Server\rabbitmq_server-3.8.17\sbin"
   set-location $rmqsbindir
   $queues = ./rabbitmqctl list_queues
   foreach ($queue IN $queues)
       {
       $queuenozero = $queue.TrimEnd("0"," ")
       $queuetrimmed = $queuenozero.TrimEnd()
       if ($queuetrimmed -like 'BPC.*' -or $queuetrimmed -like 'Connect.*' -or $queuetrimmed -like 'ImsServer.*' -or $queuetrimmed -like 'Interact.*')
           {
           ./rabbitmqctl delete_queue $queuetrimmed
           }
       }

4. Download the Blue Prism Interact and Hub Upgrader for version 4.5 to 4.6 from the Blue Prism Portal.

5. Unzip the installer on the machine where Hub and Interact 4.5 are installed. It contains two files:

   • Blue Prism Interact and Hub Upgrader.exe – The upgrader executable.
   • BluePrismHubAndInteractUpdate4.6.bin – The binary file needed to upgrade to 4.6.

   These files must be saved in the same directory.

6. Double-click the upgrader executable to start the upgrader wizard, and on the Welcome to the Hub and Interact Upgrader screen, click Next.
7. On the End-User License Agreement screen, read the End-User License Agreement and, if you agree to the terms, select the check box and click Next.
8. On the Ready for Upgrade to 4.6 screen, click Next to upgrade Hub and Interact to 4.6.

9. On the Completed the Blue Prism Hub and Blue Prism Interact upgrade screen:

   • When the upgrade completes successfully, click Finish.

   • If the installation failed, the View Log option will give you details of the error that was encountered. For more information, see Troubleshooting upgrades.

10. Repeat the process on all machines on which Hub and/or Interact is installed.
11. Check that the services and application pools stopped in steps 1 and 2 have restarted. If they have not, restart them.
12. If you are using the Blue Prism API, log into Hub as an administrator and enter the API URL on the Environment management page.

The plugins are automatically updated to the latest version as part of the upgrade process.

Upgrade Hub and Interact 4.6 to version 4.7

This upgrade updates Blue Prism Hub, Blue Prism Interact, and the supporting sites to use the following .NET components:

• .NET Desktop Runtime 6.0.9 or 6.0.10

• ASP.NET Core Runtime 6.0.9 or 6.0.10 (Windows Hosting Bundle)

• .NET Framework 4.8 – Installed by default on Windows Server 2022.

This upgrade also enforces SSL encryption requirements. For more information, see Prerequisites.

It is recommended that you schedule the upgrade to take place outside of working hours.

Prerequisites

• Version 4.6 of Hub and/or Interact is installed.

• Everyone is logged out of Authentication Server.

• You have backed up all relevant databases. Although the databases are not impacted by the upgrade, it is recommended that databases are backed up before performing any upgrade.

• 2.5 GB of free disk space on the server where Hub and/or Interact are installed – This is required for the backup that is created until the installation process is complete. Remove any backups from any previous upgrades.

• SQL Server must be configured to use SSL encryption. If your organization does not already use SSL encryption (you have been running your environment without certificates for your SQL Server, or you have been using a self‑signed certificate), your organization should obtain a certificate from a trusted certificate authority and import it into SQL Server to enable this. For more information, see Microsoft's documentation.

  If you have not previously used SSL encryption for your SQL Server, you will need to update the connection strings in the application settings files for the Blue Prism applications before running the upgrader. For more information, see Update application settings.

  Certificates from trusted certificate authorities should be used for Production environments. However, a self-signed certificate could be used for Proof of Concept, or Development environments. It is important that the fully qualified domain name (FQDN) used by SQL Server matches the FQDN defined in the certificate. If these do not match, a connection to the database will not be established and your installation will not function correctly. For information on using and configuring self-signed certificates, see Self-signed certificates in the Blue Prism Hub installation guide.

  To import the certificate into SQL Server:

  1. From the Windows task bar, open SQL Server Configuration Manager.

  2. In the SQL Server Configuration Manager, expand SQL Server Network Configuration and right-click Protocols for <SqlServerInstanceName>, and then click Properties.

  3. In the Protocols for <SqlServerInstanceName> Properties dialog, select the Certificate tab, and then select or import the required certificate.

  4. Click Apply.

The upgrader automatically stops any running websites as part of the upgrade process. You do not need to manually stop them.

Update application settings

You only need to update the appsettings.json files for the Blue Prism applications if you have not previously been using SSL encryption for your SQL Server. You can update the application settings using the script that Blue Prism has created, or manually.

To update the application settings using the script:

1. Import a certificate into SQL Server. For more information, see Prerequisites.
2. If you do not already have the Blue Prism Data Protector, download it from the Blue Prism Portal and save it to your Hub and/or Interact web server. You can remove it once this procedure is complete.
3. If you do not already have the application settings script (update‑connectionStrings.ps1), download it from the Blue Prism Portal and save it to your Hub and/or Interact web server.

4. Open PowerShell as an administrator and run the update‑connectionStrings.ps1 script. When prompted, enter the following information:

   1. installationDirectory – Type the directory path for where Hub is installed and press Enter. For example, if the default installation location was used, the path will be C:\Program Files (x86)\Blue Prism.

   2. sqlSource – Type the SQL Server name that was used during the creation of the SSL certificate and press Enter.

   3. dataProtectorPath – Type the full path to the Blue Prism Data Protector and press Enter. For example, if you save it directly onto the C: drive, enter C:\BluePrismDataProtector.Console.exe.

   4. interactInstallationDirectory – Type the directory path for where Interact is installed and press Enter. For example, if the default installation location was used, the path will be C:\Program Files (x86)\Blue Prism. If you have not installed Interact, do not enter any information and press Enter.

   The script runs and updates the connection strings in the application settings with the new value for SQL Server.

5. Repeat the process on all machines on which Hub and/or Interact is installed.

To update the application settings manually:

1. Import a certificate into SQL Server. For more information, see Prerequisites.
2. If you do not already have the Blue Prism Data Protector, download it from the Blue Prism Portal.
3. Open PowerShell as an administrator in the folder where BluePrismDataProtector.Console.exe is located. You are going to use this tool to update the connection strings in the appsettings.json files. For more information on using the tool, see Blue Prism Data Protector Tool.

4. On the Hub and Interact web servers, navigate to the following files and find the sections indicated in the code snippets below:

   The file paths shown below are the default installation locations. If you installed your applications to a different folder, you should navigate to that folder.

   C:\Program Files (x86)\Blue Prism\Audit Service\appsettings.json

   Copy

   "ConnectionStrings": {
           "AuditServerConnection": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\Audit Service Listener\appsettings.json

   Copy

   "ConnectionStrings": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\Authentication Server\appsettings.json

   Copy

   "ConnectionStrings": {
           "IdentityServerConnection": <Replace the string here>
   "Storage": {
        "Type": "Database",
         "ConnectionString": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\Email Service\appsettings.json

   Copy

   "Database": {
           "ConnectionString": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\File Service\appsettings.json

   Copy

   "Storage": {
           "Type": "Database",
           "ConnectionString": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\Hub\appsettings.json

   Copy

   "Data": {
         "Connect": {
           "ConnectionName": "Connect",
           "ConnectionString": <Replace the string here>
           
         "BluePrismDecision": {
           "ConnectionName": "BluePrismDecision",
           "ConnectionString": <Replace the string here>        
   
   "DistributedCache": {
     "Type": "Database",
     "DefaultExpirationMinutes": 0,
     "SqlServer": {
       "ConnectionString": <Replace the string here>
       
   "Storage": {
     "Type": "Database",
     "ConnectionString": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\IADA\appsettings.json

   Copy

   "Database": {
           "ConnectionString": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\Interact\appsettings.json

   Copy

   "InteractDatabases": {
         "InteractConnectionString": <Replace the string here>
         
   "DistributedCache": {
     "Type": "Database",
     "DefaultExpirationMinutes": 0,
     "SqlServer": {
       "ConnectionString": <Replace the string here> 

   C:\Program Files (x86)\Blue Prism\Interact Remote API\appsettings.json

   Copy

   "InteractRemoteDatabases": {
           "InteractConnectionString": <Replace the string here>
           
   "InteractRemoteStorage": {
       "Type": "Database",
       "ConnectionString":    <Replace the string here>

   C:\Program Files (x86)\Blue Prism\License Manager\appsettings.json

   Copy

   "Database": {
           "ConnectionString": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\Notification Center\appsettings.json

   Copy

   "Database": {
           "ConnectionString": <Replace the string here>

   C:\Program Files (x86)\Blue Prism\Submit Form Manager\appsettings.json

   Copy

   "SubmitFormManagerDatabases": {
           "InteractConnectionString": <Replace the string here>

5. For each of these files in turn:

   1. Use the Blue Prism Data Protector Tool to decrypt the connection string and copy to a temporary text file, for example:

      Copy

       "InteractDatabases": {
            "InteractConnectionString": "CfDJ8MILtsx8cQBOrqrAatl5A1aLmLP1GodoFWTnhvaHwh0ryabXaXW2i-KTfsq2XTYuAzct_ZXIFS3ILFv4Zu5ozmtvHv9aOLCxZjQJEUm7Ytwx8dK1Zqapywv2s5TCoi4X_9MGselkrRmbknBuQ_zWE93ozrNlBUVCQNHVedkyjTTPmPnxyeIgJJdoZRbkKOupnSrJwTt95SCmvo2SLLhZZFR5e2s24smn72PKNGrga8fksbIDpalDFwRc-i6_kkEinp5qA-FBFfIbVZzBD5ZN1dyuaC2jM7V4dxKt5tea1NP-_vauczgCLBp88WdmNEe0Ew"

      Becomes:

      Copy

      "InteractDatabases": {
            "InteractConnectionString": "Data Source=existed-name-without-certificate; Initial Catalog=Interact; User Id=sa; Pass=Pass***; Max Pool Size=500; Encrypt=False; MultiSubnetFailover=True" 

      The examples in step 4 above show the extract from the appsettings.json file to illustrate the location of the settings. The decryption and encryption is only carried out on the connection string setting, not on the settings also shown in these code examples.

      Only the Data Source in the connection string needs to be updated. The other parameters in the connection string setting should be left unchanged. The upgrade script will make any changes that are required when run, such as updating the Encrypt parameter.

   2. In the copied connection string, replace the value for the Data Source parameter with the name from the certificate, for example:

      Copy

      "InteractDatabases": {
            "InteractConnectionString": "Data Source=name-with-certificate; Initial Catalog=Interact; User Id=sa; Password=Pass***; Max Pool Size=500; Encrypt=False; MultiSubnetFailover=True" 

      The certificate name can be found in SQL Server Configuration Manager.

      1. In SQL Server Configuration Manager, expand SQL Server Network Configuration, right-click Protocols for <SqlServerInstanceName>, and then click Properties.
      2. In the Protocols for <SqlServerInstanceName> Properties dialog, select the Certificate tab. The certificate name is shown in the Issued To field – this displays in the format: short name followed by the common name (which is usually the FQDN). Either name can be used as the Data Source, however, if both names are present, it is recommended that the common name (FQDN) is used.
      3. Optionally, for additional clarity, click View, and select Subject Alternative Name. The names are shown in the text area below the fields.

   3. Use the Blue Prism Data Protector Tool to encrypt the new connection string and overwrite the string in the appsettings.json file with this new value.

   For information on decrypting and encrypting the connection strings, see Blue Prism Data Protector Tool.

6. Open IIS Manager and restart the appropriate Application Pool to ensure it uses the new connection string.

7. Repeat the process on all machines on which Hub and/or Interact is installed.

Upgrade steps

1. Blue Prism Hub and Blue Prism Interact 4.7 require .NET Core 6.0 and .NET Framework 4.8. If you do not have these versions, you will need to update your Hub and/or Interact web server.

   Step	Details	Video
   1	Download the following components and store them in a temporary location, for example, C:\temp: ASP.NET Core Runtime 6.0.9 or 6.0.10 (Windows Hosting Bundle) https://dotnet.microsoft.com/download/dotnet/6.0 – Select the version you require. Under ASP.NET Core Runtime, select Hosting Bundle. .NET Desktop Runtime 6.0.9 or 6.0.10 https://dotnet.microsoft.com/download/dotnet/6.0 – Select the version you require. Under .NET Desktop Runtime, select the appropriate download. .NET Framework 4.8 https://support.microsoft.com/en-us/topic/microsoft-net-framework-4-8-offline-installer-for-windows-9d23f658-3b97-68ab-d013-aa3c3e7495e0 This is installed by default on Windows Server 2022. You only need to install the .NET Framework if you are using Windows Server 2016 Datacenter or Windows Server 2019.	The video above acts as a visual guide only. The version of .NET contained in this video may be different to the actual version required.
   2	To install the .NET dependencies, run each of the following commands using the PowerShell command prompt, waiting until each completes, before running the next command: For Windows Server 2016 and Windows Server 2019: Copy start-process "C:\temp\dotnet-hosting-6.0.0-win.exe" /q -wait start-process "C:\temp\windowsdesktop-runtime-6.0.0-win-x64.exe" /q -wait start-process "C:\temp\ndp48-x86-x64-allos-enu.exe" /q -wait For Windows Server 2022 (.NET Framework is already installed by default): Copy start-process "C:\temp\dotnet-hosting-6.0.0-win.exe" /q -wait start-process "C:\temp\windowsdesktop-runtime-6.0.0-win-x64.exe" /q -wait Ensure the file name and file path match the files that were stored in step 1.
   3	Restart your server before installing Blue Prism Hub to ensure the components are fully installed and registered.

   To watch this installation step, see our .NET installation video.

2. Download the Blue Prism Interact and Hub Upgrader for version 4.6 to 4.7 from the Blue Prism Portal.

3. Unzip the installer on the machine where Hub and Interact 4.6 are installed. It contains two files:

   • Blue Prism Interact and Hub Upgrader.exe – The upgrader executable.
   • BluePrismHubAndInteractUpdate4.7.bin – The binary file needed to upgrade to 4.7.

   These files must be saved in the same directory.

4. Double-click the upgrader executable to start the upgrader wizard, and on the Welcome to the Hub and Interact Upgrader screen, click Next.

   The upgrader checks that the prerequisite software from step 1 is installed. If it is not, the Prerequisites screen displays and you will need to close the installer and perform step 1.

5. On the End-User License Agreement screen, read the End-User License Agreement and, if you agree to the terms, select the check box and click Next.
6. On the Ready for Upgrade to 4.7 screen, click Next to upgrade Hub and Interact to 4.7.

7. On the Completed the Blue Prism Hub and Blue Prism Interact upgrade screen:

   • When the upgrade completes successfully, click Finish.

   • If the installation failed, the View Log option will give you details of the error that was encountered. For more information, see Troubleshooting upgrades.

8. Repeat the process on all machines on which Hub and/or Interact is installed.

The plugins are automatically updated to the latest version as part of the upgrade process.

Upgrade Interact API VBO

The Interact API VBO is used within the Blue Prism interactive client, and it is updated independently to utilize any new features within the Interact API Service that are available when Interact is upgraded. The latest version of the VBO is available in the Interact API Service release zip file on the Blue Prism Portal.

To upgrade the VBO, you only need to update the Utility - Interact VBO:

1. Download the Interact API Service release file from the Blue Prism Portal.
2. Unzip the Interact API Service release file.

3. In the Blue Prism interactive client and select File > Import > Release/Skill.

   The Choose the input file screen displays.

4. Click Browse and select the extracted Interact API Release.bprelease file, then click Next.

   The Resolve Import Conflicts screen displays.

5. In the Resolution column:

   1. Leave the setting for Utility - Interact API as Overwrite the existing business object.

   2. Change the settings for all the other components to Don't import this business object.

6. Click Next.

   The Process logging overview screen displays.

7. Ensure that only Utility - Interact API is listed for import. If:

   • Other components are listed, click Back and change the settings as detailed in step 5 above.
   • It is the only component, click Next to complete the import.

8. Click Finish.

Troubleshooting upgrades

Following an upgrade, when I attempt to log into Interact or Hub, I am seeing an error related to SignalR about overloading the web server in IIS.

This error is very rare but if it does occur, reload the site and restart the application pools in IIS.

I canceled an installation during the upgrade process and I am now seeing errors.

It is recommended that installations are not canceled during the upgrade process. However, although errors may be seen, the rollback operation will complete successfully.