Troubleshooting – runtime resources

Commonly misconfiguration of start-up command is the main reason for a runtime resource failing to start such as incorrect use of switches or settings.

Before trying to start a runtime resource using the command line, verify that if the Blue Prism client is launched on the device, that it is possible to login to Blue Prism using the default connection. By default – the runtime resource will use the same connection settings when started via the command line.

Using the client to validate that a connection can be achieved will help to validate that the appropriate network connections can be established and that the appropriate configuration has taken place.

Configurable settings can prevent connections

There are a number of configurations that can restrict whether runtime resources can connect.

Require secure inbound instructional connections

If this settings is enabled, only runtime resources that are correctly configured to use the /sslcert start-up command will be able to connect to the Blue Prism environment.

Allow anonymous public runtime resources

If this setting is disabled, only runtime resources that are configured with appropriate details to authenticate against the environment as part of the start-up command will be able to connect.

The configuration required differs depending on the mode users authenticating against Blue Prism are required to use:

• Single sign-on for Blue Prism – The start-up command will need to include an /sso switch, and the user context that the runtime resource runs as will need to be configured with appropriate Blue Prism permissions.
• Blue Prism native authentication – The start-up command will need to include the /user “username” “password” parameters, and the user credentials specified will need to match a valid Blue Prism user configured with appropriate permissions.

There are a number of situations where a runtime resource can be started, but subsequently fails to successfully accept connections. It is useful to review the dialog within the runtime resource dialog and within Control Room. Also review the system and application specific event logs on the runtime device.

General issues

The following issues may occur both for any runtime resource.

Runtime resource does not receive connections or an operation was attempted on something that is not a socket

Situations where the runtime resource appears to be online, but where it is not contactable from Control Room, are indicative of scenarios where the network communication cannot be established. Common reasons for this are:

• The runtime resource is not online
• Firewalls (or similar) are preventing the communication
• The network is not operating as expected

Runtime resource appears online in some Control Rooms but not others

Situations where the runtime resource appears to be online, but independent Control Room installations show different information about whether the runtime can be contacted are indicative of network connectivity issues.

Each Blue Prism Server and Control Room attempts to directly connect to each runtime resource, therefore if a given Control Room cannot connect to a runtime resource but others can, it suggests a network or device configuration issue is preventing the Control Room from establishing the connection.

Blue Prism may also forcibly prevent a connection if the runtime is connected to one environment (such as Production: Finance), but the Control Room is connected to a different environment (such as Production: Ops)

Issues when the /sslcert switch is being used

The following issues are only relevant to runtime resources that are configured to use a certificate to encrypt inbound instructional communications such as through use of the /sslcert switch.

Unable to find the requested SSL certificate

Unable to find the requested SSL certificate – ensure that it is installed in the local certificate store and is valid

In order to address errors that state that the certificate cannot be found, it is necessary to ensure that the certificate has been installed on the local machine (within the computer account) and that the thumbprint has been set correctly.

This message is commonly received when a hidden character is present at the beginning of the thumbprint. It is therefore strongly recommended that a utility such as notepad is used to delete any non-visible characters from the beginning of the thumbprint.

The remote certificate is invalid according to the validation procedure

Commonly where there are validation issues with the certificate it is expected that the runtime resource will be able to start, and it may be seen to accept connections, but those connections are likely to cease within a short time frame as shown. Likewise the Control Room user interface is likely present a message such as:

Error establishing a secure connection – The remote certificate is invalid according to the validation procedure

To address this type of issue is necessary to ensure that:

• The address used by Blue Prism to contact the runtime resource matches the name on the certificate.
• The certificate has not been revoked.
• The certificate has been trusted by the device on which Control Room is running.

Unable to accept incoming connection – the credentials supplied to the package were not recognized

Commonly this error is coupled with a message in Control Room that states:

Unable to accept incoming connection because the certificate (/sslcert) cannot be used for inbound connections. Ensure the logged in user has permission to read the certificate private key.

This is indicative of situation where the user context used to start the runtime resource does not have sufficient rights to configure the listener correctly. It is most commonly found where the applied local security policy of the device results in user accounts being run in admin approval mode.

To diagnose and resolve this issue, start the runtime resource from an elevated command prompt. For example: start command prompt as an administrator and use it to launch a runtime resource using the same switch configuration.

To address this issue it is necessary to ensure that:

• The Windows Logs (System) have been reviewed for further information.
• The private keys for the certificate specified using the /sslcert switch are available on the device.
• The starting user of the runtime resource has read access to the private keys.

The steps below provide instructions to configure access to the private keys for a given certificate:

1. Open the certificates interface on the specified device (e.g. Manager Computer Certificates, or via the Certificates snap-in for MMC).
2. Find the appropriate certificate, access the context menu and select to Manage Private Keys.
3. Grant read permissions to the user that is responsible to starting the runtime resource.

When on a device that enforces Admin Approval Mode it is necessary to ensure that the user is explicitly named as having permission to the key (rather than being granted permission through membership of an administrators group).