Start Free Trial   Support

Bullhorn CRM Advanced Settings

Before Connecting

Begin by providing your BullhornCRM account credentials in the following:

  • DataCenterCode: Set this to the data center code which responds to your data center. Refer to the list here.

If you are uncertain about your data center code, codes like CLS2, CLS21, etc. are cluster IDs that are contained in a user's browser URL (address bar) once they are logged in.

Example: https://cls21.bullhornstaffing.com/BullhornSTAFFING/MainFrame.jsp?#no-ba... indicates that the logged in user is on CLS21.

Authenticating with OAuth

BullhornCRM uses the OAuth 2.0 authentication standard.

To authenticate using OAuth, you will need to create and configure a custom OAuth app. See Using OAuth Authentication for more information.

Contacting Bullhorn

Considerations when Connecting to BullhornCRM

Unlike many other data sources, BullhornCRM doesn't allow users to create their own custom OAuth applications or edit their CallbackURL directly.

Instead, the user must contact BullhornCRM and request that they create/change the user's OAuth information on BullhornCRM's end.

If a user needs to change their CallbackURL, waiting for a new one from BullhornCRM may be a time-consuming process.

It is highly recommended that users consider using an OAuth verifier code to connect instead. See Custom Credentials for more details.

Using OAuth Authentication

OAuth requires the authenticating user to interact with BullhornCRM using the browser. The provider facilitates this in various ways as described below.

Important note: At the moment there is a bug in the BullhornCRM API. See this link.
This error occurs when you already are logged in the browser you're using for authentication. You should use another browser to avoid the error.

Custom Credentials

In order to connect using Custom Credentials, you will need to register an app to obtain the OAuthClientId and OAuthClientSecret. For this, you must contact the Bullhorn team, to provide you with the credentials (ClientId and ClientSecret). OAuth is something only available to Bullhorn partners. You can find additional details here.

When to Create a Custom OAuth App

Web Applications

You need to create a custom OAuth app in the web flow.

Desktop Applications

Creating a custom OAuth app is required. This is because your OAuth credentials are tied to your account, and therefore cannot be embedded.

Headless Machines

In the headless OAuth flow, users need to authenticate via a browser on another machine. You must create a custom OAuth app in order to connect.

Creating a Custom OAuth App

See Creating a Custom OAuth App for a procedure.

Custom Credentials 

When to Use a Custom OAuth App

 You must create a custom OAuth app to connect to the BullhornCRM.

Desktop Authentication with a Custom OAuth App

 Follow the steps below to authenticate with the credentials for a custom OAuth app. See Creating a Custom OAuth App.

Scenario 1: Authenticate with a Verifier Code

Making any changes to your OAuth app (such as the CallbackURL) requires reaching out to BullhornCRM directly, which can be a time-consuming process.

As such, it's highly recommended that you instead use an OAuthVerifier to connect. To obtain a verifier, you will need an OAuth Authorization URL.

Retrieving an OAuth Verifier Code

Construct your authorization URL as follows:
https://<authurl for your data center>/oauth/authorize?client_id=<your OAuth client id>.

For example, if you had data center "CLS5", the authentication URL would be "https://auth.bullhornstaffing.com/oauth/authorize?client_id=your_client_id".

Please refer to the list here to determine the authentication URL for your data center.

Next, retrieve the OAuth verifier code as follows:

  1. Open your authorization URL in a browser. Log in and grant permissions to the provider. You are then redirected to the callback URL, which contains the verifier code.
  2. Save the value of the verifier code.

Get and Refresh the OAuth Access Token

After setting the following, you are ready to connect:

  • OAuthVerifier: Set this to the OAuth Verifier code obtained previously.
  • DataCenterCode: Set this to the respective data center your account is connected with. Find the list of the data centers here. For example, CLS33.
  • OAuthClientId: Set this to the client Id assigned when you registered your app.
  • OAuthClientSecret: Set this to the client secret assigned when you registered your app.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
The provider then completes the OAuth process:
  1. The process finalizes with the access token returned from the BullhornCRM API.
  2. Refreshes the access token when it expires.
  3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Scenario 2: Authenticate with a Custom CallbackURL

You also have the option of requesting a custom callback URL (for example, http://localhost:33333) from BullhornCRM. If you have been provided with a custom CallbackURL, you can set the following to connect to data:

  • CallbackURL: Set this to the custom callback URL provided by BullhornCRM.
  • DataCenterCode: Set this to the respective data center your account is connected with. Find the list of the data centers here. For example, CLS33.
  • OAuthClientId: Set this to the client Id assigned when you registered your app.
  • OAuthClientSecret: Set this to the client secret assigned when you registered your app.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
The provider then completes the OAuth process:
  1. The process finalizes with the access token returned from the BullhornCRM API.
  2. Refreshes the access token when it expires.
  3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Web Authentication with a Custom OAuth App

When connecting via a Web application, you need to register a custom OAuth app with BullhornCRM. See Creating a Custom OAuth App. You can then use the provider to get and manage the OAuth token values.

Get an OAuth Access Token

Set the following connection properties to obtain the OAuthAccessToken:

  • OAuthClientId: Set this to the Client Id provided by Bullhorn.
  • OAuthClientSecret: Set this to the Client Secret provided by Bullhorn.

You can then call stored procedures to complete the OAuth exchange:

  1. Call the GetOAuthAuthorizationURL stored procedure. Set the AuthMode input to WEB and set the CallbackURL input to the Redirect URI.

    The stored procedure returns the URL to the OAuth endpoint.

  2. Open the URL, log in, and authorize the application. You are redirected back to the callback URL.
  3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB. Set the Verifier input to the "code" parameter in the query string of the callback URL.

Refresh the OAuth Access Token

You can set InitiateOAuth to REFRESH to automatically refresh the OAuth access token when it expires, or you can call the RefreshOAuthAccessToken stored procedure to refresh the token manually.

Automatic Refresh

To refresh the token with InitiateOAuth, set the following on the first data connection:

  • OAuthAccessToken: Set this to the access token returned by GetOAuthAccessToken.
  • InitiateOAuth: Set this to REFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
  • OAuthSettingsLocation: Set this to the path where the provider will save the OAuth values, to be persisted across connections.
  • OAuthClientId: Set this to the Client Id provided by Bullhorn.
  • OAuthClientSecret: Set this to the Client Secret provided by Bullhorn.
  • OAuthRefreshToken: Set this to the refresh token returned by GetOAuthAccessToken.

On subsequent data connections, set the following:

  • InitiateOAuth
  • OAuthSettingsLocation

Manual Refresh

You can use the RefreshOAuthAccessToken stored procedure to manually refresh the OAuthAccessToken. Call the stored procedure after the ExpiresIn parameter value returned by GetOAuthAccessToken has elapsed. You need the following connection properties to be set:

  • OAuthClientId: Set this to the Client Id provided by Bullhorn.
  • OAuthClientSecret: Set this to the Client Secret provided by Bullhorn.

You can then call RefreshOAuthAccessToken with the following parameter set:

  • OAuthRefreshToken: Set this to the OAuthRefreshToken returned by GetOAuthAccessToken.

Headless Machines

Using OAuth on a Headless Machine

To create BullhornCRM data sources on headless servers or other machines on which the provider cannot open a browser, you need to authenticate from another machine. Authentication is a two-step process.

  1. Instead of installing the provider on another machine, you can follow the steps below to obtain the OAuthVerifier value. Or, you can install the provider on another machine and transfer the OAuth authentication values, after you authenticate through the usual browser-based flow.
  2. You can then configure the provider to automatically refresh the access token from the headless machine.
You can follow the headless OAuth authentication flow using the OAuth credentials for your custom OAuth app.
 

Using the Credentials for a Custom OAuth App

Create a Custom OAuth App

You might want to create a custom OAuth app to change the information displayed when users log into BullhornCRM to grant permissions to the provider.

See Creating a Custom OAuth App for a procedure. You can then follow the procedures below to authenticate and connect to data.

Obtain a Verifier Code

Set the following properties on the headless machine:

  • DataCenterCode: Set this to the data center code which responds to your data center. Refer to the list here.
  • InitiateOAuth: Set this to OFF.
  • OAuthClientId: Set this to the Client Id provided by Bullhorn.
  • OAuthClientSecret: Set this to the Client Secret provided by Bullhorn.

You can then follow the steps below to authenticate from another machine and obtain the OAuthVerifier connection property.

  1. Call the GetOAuthAuthorizationURL stored procedure with the CallbackURL input parameter set to the exact Redirect URI.
  2. Open the returned URL in a browser. Log in and grant permissions to the provider. You are then redirected to the callback URL, which contains the verifier code.
  3. Save the value of the verifier code. You will set this in the OAuthVerifier connection property.
  4. Save the REST URL. You will set this in the RestUrl property.

On the headless machine, set the following connection properties to obtain the OAuth authentication values:

  • DataCenterCode: Set this to the data center code which responds to your data center.
  • RestUrl: Set this to the URL returned by the GetOAuthAccessToken stored procedure.
  • OAuthVerifier: Set this to the verifier code.
  • OAuthSettingsLocation: Set this to persist the encrypted OAuth authentication values to the specified file.
  • InitiateOAuth: Set this to REFRESH.

After the OAuth settings file is generated, set the following properties to connect to data:

  • DataCenterCode: Set this to the data center code which responds to your data center.
  • RestUrl: Set this to the URL returned by the GetOAuthAccessToken stored procedure.
  • OAuthSettingsLocation: Set this to the file containing the encrypted OAuth authentication values. Make sure this file gives read and write permissions to the provider to enable the automatic refreshing of the access token.
  • InitiateOAuth: Set this to REFRESH.

Transfer OAuth Settings

Follow the steps below to install the provider on another machine, authenticate, and then transfer the resulting OAuth values.

On a second machine, install the provider and connect with the following properties set:

  • DataCenterCode: Set this to the data center code which responds to your data center.
  • RestUrl: Set this to the URL returned by the GetOAuthAccessToken stored procedure.
  • OAuthSettingsLocation: Set this to a writable text file.
  • InitiateOAuth: Set this to GETANDREFRESH.
  • OAuthClientId: Set this to the client Id assigned when you registered your app.
  • OAuthClientSecret: Set this to the client secret assigned when you registered your app.
  • CallbackURL: Set this to the Redirect URI. Note: A different callback url must be explicitly requested from the Bullhorn staff. For example, http://localhost:33333/.

Test the connection to authenticate. The resulting authentication values are written, encrypted, to the path specified by OAuthSettingsLocation. Once you have successfully tested the connection, copy the OAuth settings file to your headless machine. On the headless machine, set the following connection properties to connect to data:

  • RestUrl: Set this to the URL returned by the GetOAuthAccessToken stored procedure.
  • DataCenterCode: Set this to the data center code which responds to your data center.
  • InitiateOAuth: Set this to REFRESH.
  • OAuthSettingsLocation: Set this to the path to your OAuth settings file. Make sure this file gives read and write permissions to the provider to enable the automatic refreshing of the access token.

Creating a Custom OAuth App

You must create a custom OAuth app to connect to the BullhornCRM.

The only way to create an app is to contact the Bullhorn support team, and they will provide you with the app's credentials (ClientId and ClientSecret). You can find more information about how to register here.

In addition, the CallbackUrl or Redirect Uri will default to a page on bullhorn.com.

In order to utilize setting InitiateOAuth to GETANDREFRESH, Bullhorn staff must be contacted and a separate CallbackUrl must be requested.

If a separate Callback Url cannot be specified, the "code" parameter from the redirect page on Bullhorn will need to be taken and passed as an input to either:

  • The Verifier input of GetOAuthAccessToken if executing it manually.
  • The connection property OAuthVerifier when setting InitiateOAuth to GETANDREFRESH.

Fine-Tuning Data Access

You can use the following properties to gain greater control over BullhornCRM API features and the strategies the provider uses to surface them:

  • IncludeCustomFields: Whether or not custom fields will be included. When off, performance will be higher, but the custom fields cannot be retrieved or modified.
  • IncludeCustomTables: Whether or not custom tables will be included. When off, performance will be higher, but the custom tables cannot be retrieved.
  • ListLayouts: A list of tables you want to list layouts for. For example: ListLayouts=Candidate,JobOrder;.
  • UseDisplayNames: Set this to true to use field labels for column names.

Customizing the SSL Configuration

By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.

Connecting Through a Firewall or Proxy

HTTP Proxies

To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.

In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.

Other Proxies

Set the following properties:

  • To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
  • To tunnel the connection, set FirewallType to TUNNEL.
  • To authenticate, specify FirewallUser and FirewallPassword.
  • To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

Troubleshooting the Connection

To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.

  • Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
  • Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
  • The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. If you are using a self-signed certificate, there is only one certificate in the chain.

    To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.