Troubleshoot a Hub installation

The following sections seek to provide guidance if specific issues are experienced either during the install or when verifying that the installation has been successful.

Message Broker connectivity

To verify the connectivity between the Web Server and the Message Broker check that the RabbitMQ Management Console is accessible through a web browser.

There could be several reasons that connectivity fails:

  • Verify Network Connectivity – Ensure that all relevant devices are connected to the same network and are able to communicate.
  • Firewall – Check that the firewalls on the servers themselves or within the network are not preventing communication.

The RabbitMQ Management Console communicates, by default, on port 15672. The message broker queues use a different port, 5672, by default. The firewall should be checked for TCP access on all ports. This is especially true of the IT organization has specified non-default ports.

Database connectivity

The Test connection to proceed button within the installer checks the following:

  • If the database exists:
    • That it can be connected to.
    • That the account has the rights to read, write and edit the database.
  • If the database does not exist:
    • That the account has the right to create the database.

If these requirements cannot be met, the installation will stop.

There are a number of checks that can be performed when a connection cannot be made to a SQL Server over the LAN:

  • Verify Network Connectivity – Ensure that all relevant devices are connected to the same network and are able to communicate.
  • SQL Credentials – Verify the SQL credentials and that the user has appropriate permissions on the SQL Server.
  • Firewall – Check that the firewalls on the servers themselves or within the network are not preventing communication.
  • SQL Browser Service – Ensure the SQL Browser Service on the SQL Server is enabled to allow for a SQL Instance to be found. For SQL Server Express this service is typically disabled by default.
  • Enabling TCP/IP Connectivity – Where remote connectivity is required for SQL, check that TCP/IP connectivity is enabled for the SQL Instance. Microsoft provide articles specific to each version of SQL that provide instructions to Enable the TCP/IP Network Protocol for SQL Server.

If when running the installer the installation process fails with database errors, see below, then test that the Web Server has a SQL connectivity to the database. This could be due to any of the reasons potentially listed above.

Another potential reason for failure is that the account used to create the databases within the installer has insufficient privileges to create the databases.

Finally, if the installation is a re-installation after a removal of the software. Then if the same database names have been used, the original databases should be backed up and dropped before re-installing.

Web server

During the installation process the installer will check that all prerequisites are installed. It is recommended that if the prerequisites are not installed, that the installer is canceled, the prerequisites installed, and the installer process restarted.

For further information, see Prerequisites.

File service

If the File service fails to locate the imagery for Authentication Server and Hub then this is caused by an uninstallation and reinstallation of the Blue Prism products. This issue will not occur for first-time installations.

During the removal process, the databases are not removed and so if the reinstallation uses the same database names then the original paths to the file services and URLs will still be used.

To overcome this, after the removal process has been run, either delete or clean the databases so that any previous paths have been deleted or use alternatives database names during the reinstallation.

Windows Authentication

The account used when running the installation must have the relevant SQL Server permissions to carry out the installation, that is, membership in either the sysadmin or dbcreator fixed server roles. For more information, see Hub software requirements and permissions.

If Windows Authentication is chosen during the installation process, it is recommended that a Windows service account is used that has the necessary permissions to execute the tasks and processes during normal operation. The Windows service account will need:

Assigning a Windows service account to the application pool

By default, the application pools are created with the identity ‘ApplicationPoolIdentity’. After the installer has completed, the Windows service account will need to be allocated to manage the application pools. To do this:

  1. On the web server, open Internet Information Services (IIS) Manager.
  2. In the Connections panel, expand the host and select Application Pools.
  3. Review the Identity column values.

    The identity for an application pool should match the specific Windows service account.

  4. For any application pools that have ApplicationPoolIdentity in the Identity column, right-click the row and select Advanced Settings....

    The Advanced Settings dialog displays.

  5. Select the Identity setting then click the ... (ellipsis) button:

  6. In the Application Pool Identity dialog, select Custom account and then click Set....

    The Set Credentials dialog displays.

  7. Enter the credentials for the required Windows service account and click OK.
  8. Repeat for any applications pools that need changing.
  9. Restart the RabbitMQ Service.
  10. Restart all application pools.
  11. Restart IIS.

If there are issues with the Audit Service, make sure that the Windows service account has access to the Audit Service Listener as well as the Audit Database.

Assigning the Windows service account as an owner on certificates

The Windows service account needs to be granted permissions to the BluePrismCloud certificates. To do this:

  1. On the web server, open the Certificate Manager. To do this, type Certificates in the search box on the Windows taskbar, and then click Manage Computer Certificates.
  2. In the navigation pane, expand Personal and click Certificates.
  3. Follow the steps below for both the BluePrismCloud_Data_Protection and BluePrismCloud_IMS_JWT certificates:

    1. Right-click the certificate and select All Tasks, and click Manage Private Keys....

      The Permissions dialog for the certificate displays.

    2. Click Add, then enter the service account and click OK.

    3. With the service account selected in the Group or user name list, ensure that Full control is selected in the Permissions for {account name} list.

    4. Click OK.

      The service account now has access to the certificate.

Hub shows an error on starting

If a user logs into the Authentication Server, selects Hub and the following message displays:

An error occurred while starting the application

This means that the IIS sites need to be restarted. This error affects systems that are installed on a single server and occurs if RabbitMQ starts up after the IIS sites. Therefore, it is recommended that the IIS sites have a startup delay set on them to allow RabbitMQ to start up first.

If this error occurs, it can be resolved in the following way:

  1. On the server, open Internet Information Services (IIS) Manager and stop all the Blue Prism sites. For a list, see Hub websites.
  2. Restart the RabbitMQ Service.
  3. Restart all Blue Prism application pools.
  4. Start the Blue Prism sites that were stopped in step 1.

To delay the IIS sites service startup:

  1. On the server, open Services.
  2. Right-click World Wide Web Publishing Service and select Properties.
  3. On the General tab, set Startup type to Automatic (Delayed Start).
  4. Click OK and close the Services window.

Not able to configure SMTP settings in Hub

If you are unable to configure SMTP settings in Hub this is normally related to the startup order of the services.

The web server must start up after the RabbitMQ services have all started. If the web server services start before the RabbitMQ service is ready, then going into the SMTP settings in Hub will result in a ‘something went wrong’ message.

Updating the Customer ID after installation

If you need to enter or update your Customer ID after installation, you will need to update the License Manager appsettings.json configuration file. Once the configuration file has been updated, the License Manager must be restarted in Internet Information Services (IIS) Manager.

To update your Customer ID in the appsetting.json file:

  1. Open Windows Explorer and navigate to C:\Program Files (x86)\Blue Prism\LicenseManager\appsettings.json.

    This is the default install location – adjust this if you have used a custom location.

  2. Open the appsettings.json file in a text editor.
  3. Locate the License:CustomerId section of the file and enter your new Customer ID, for example:

    Copy
    "License": {
        "CustomerId": "your-Customer-ID-here"
    }
  4. Save the file.

To restart License Manager:

  1. Open Internet Information Services (IIS) Manager.

  2. In the list of connections, select Blue Prism - License Manager.

    This is the default site name – if you have used a custom site name, select the appropriate connection.

  3. Click Restart from the Manage Website controls.

    The License Manager restarts.

Updating the Blue Prism API URL after installation

To use the Control Room plugin, connection to the the Blue Prism API is required. If have not enter the Blue Prism API URL during the installation, or you need to change the URL, you will need to update the appsettings.json configuration file. Once the configuration file has been updated, Hub must be restarted in Internet Information Services (IIS) Manager.

To update the API URL in the appsetting.json file:

  1. Open Windows Explorer and navigate to C:\Program Files (x86)\Blue Prism\Hub\appsettings.json.

    This is the default install location – adjust this if you have used a custom location.

  2. Open the appsettings.json file in a text editor.
  3. Locate the RemoteUrlConfiguration:BluePrismApiUrl section of the file.
  4. Change the "BluePrismApiUrl" element value to be the URL of your API installation. This example uses "https://blueprism-api.com":

    Copy
    "RemoteURLConfiguration": {
        "BluePrismApiUrl": "https://blueprism-api.com"
    }
  5. Save the file.

To restart Hub:

  1. Open Internet Information Services (IIS) Manager.

  2. In the list of connections, select Blue Prism - Hub.

    This is the default site name – if you have used a custom site name, select the appropriate connection.

  3. Click Restart from the Manage Website controls.

    The Hub application is restarted and configured to allow requests from the Control Room plugin to be sent to the API.