In this help doc we’ll review causes of disconnection between your site and Bullhorn and how to avoid them and how to get your site reconnected to Bullhorn quickly.
Disconnections From Bullhorn
Occasionally, Matador may become disconnected from Bullhorn. These are caused primarily by short-term Bullhorn downtime due to planned maintenance, and often a non-issue.
Most of the times that a disconnection occurs, Matador is able to recover the connection automatically. Matador includes special routines that enables it to reconnect to Bullhorn when a disconnection occurs, but only if all the necessary pieces of a solid connection are intact.
Sometimes, however, this is not possible. If your site is unable to automatically reconnect to Bullhorn after three attempts, Matador will send your administrator an email requesting their intervention, and send it daily thereafter until the site is connected.
Causes of Disconnections & How to Avoid Them
There are three common and a few uncommon causes of disconnections. Many are easily avoidable once you know how they’re caused.
The “Auto login by Cookie” problem
There is a Bullhorn feature that will automatically login you into the Bullhorn app But this is not what we want to happen when trying to connect to the Bullhorn API and can be a common cause for a disconnection that a user can accidentally encounter if they are authorizing Matador from a web browser previously logged into the Bullhorn ATS. It is thankfully very easy to fix.
The problem rears its head when you are using a browser that is or was logged into the Bullhorn ATS with a user and password and you still have the login cookie saved. When you connect your Matador-powered website to Bullhorn, the Matador connection will authorize with the API user and password but the connection will somehow be tied the cookie’s logged in user’s data.
Usually, this can be recovered upon automatically, but during a first authorization with the API user, you must accept an API terms of service and this bug skips that critical step, so the next time your site disconnects and tries to automatically reconnect with the API user and password, the site may be unable to if the API user terms haven’t been accepted.
To avoid this, do the following:
- Either sign in to Bullhorn and then log out from the menu. Expired logins still have the cookie, but an on-purpose log out will delete the cookie, or,
- Connect your Matador site to Bullhorn in a Private or Incognito Browsing Window, and,
- For either method, always click on “Test Auto Reconnect” after completing the Bullhorn Connection Assistant to make sure automatic reconnection works.
To resolve this, do the following::
- Most times, you can resolve this by following the Simple Reconnect Routine below.
- Some times, you may need to follow the Reset Connection Routine below.
Expired API User Password
API usernames at Bullhorn are special: they are not subject to automatic password expiration like a typical user account. For that reason, the API user password should never expire!
That said, we’ve found users “check” their API username and password by logging into the ATS with those credentials. While innocent and intended only to make sure they work, the users’ unknowingly strip the API user of its special status, beginning a countdown to the expiration of the API user password.
When the password finally expires, Matador can remain connected until an outage occurs, but will then be unable to reconnect due to the bad password.
To avoid this, do the following:
- Always reset/change the API user password using the user management screens as a logged in admin user.
- Never log into the ATS with your API username and password.
To resolve this, do the following:
- Update the API User password by using an admin level user in Bullhorn and the users screen in Bullhorn.
- Update and save the new password into the Bullhorn Connection Assistant.
- Use the Simple Reconnect Routine below.
Site Migration
At this time, Matador is unable to detect when a site operator copies a site from a staging or development environment into a production or live environment. Because Matador determines its connection status based on the presence of saved connection credentials, this means that a migrated site will think it is connected when it is not.
Especially if the migrated site has not seen its API Whitelist URI set properly, this may mean the site is not connected even though Matador may say it is.
To avoid this, do the following:
- You can’t avoid this, but you can be aware of it and fix it before it causes you issues!
- Whenever you migrate from a staging to a live environment, always follow the resolve steps below.
To resolve this, do the following:
- If this is the first time migrating to this URL, use the Reset Connection Routine below.
- If this is not the first time migrating to this URL, use the Simple Reconnect Routine below.
Site URL Protocol Mismatch
WordPress, and not Matador has a setting allowing the site operator to set the Site URL. Access this in the General WordPress settings. If your site is resolving (via the DNS) to an https:// protocol but the WordPress settings for Site URL has an http:// protocol, your Matador Connection will fail.
Matador sends it authentication requests to Bullhorn asking to be redirected to the WordPress URL at the API endpoint, but if the DNS redirects the process to a different protocol or adds the www before the URL, etc, this will fail. Bullhorn expects an exact URL match for whitelist.
To avoid this, do the following:
- Go to your website without the www or without entering http or https.
- After your homepage loads, take note of the exact URL of the site.
- Make sure that url is what is being used for the Site URL setting of WordPress.
To resolve this, do the following:
- Updated the Site URL setting in WordPress
- Use the simple reconnect routine to reconnect to Bullhorn.
Note: this url mismatch could be the cause of a number of other errors throughout your site and cause your site to perfrom worse in search engine ranking, so this is a good idea to even if you are not a Matador user.
Less Common Causes
Less common causes can be the reason for a disconnection:
- API User Username cancelled/deactivated
- API User Password changed
- Whitelist URIs changed
- Client ID/Client Secret being removed from your account
- Your Bullhorn account being suspended/cancelled.
We’ve seen it all!
- One of our users was implementing another Bullhorn API solution and erroneously instructed the tech at Bullhorn to cancel all other keys for security, forgetting that other keys were being used by Matador, and breaking their site.
- Several of our users were implementing another Bullhorn API solution and changed their password because they forgot it, and breaking their site.
- Once, a marketing member of a staff was unaware that the recruiting team had begun migrating away from Bullhorn and they were wondering why jobs were no longer updating. You need a Bullhorn account to be connected to Matador!
To avoid these, do the following:
- Treat your Bullhorn credentials as precious and don’t mess with them.
- Since Fall 2018, Bullhorn supports multiple API users and you should have one user per integration.
- Remember that Matador saves credentials, so if you choose to use the same credentials for multiple integrations, you can reference yours from Matador.
To resolve these, do the following:
- Try to reconnect using the Simple Reconnect Routine.
- If that doesn’t work, follow the Reset Connection Routine.
Connection Routines
There are two routines you may need to use to reconnect your site. We’ll discuss both in the following sections.
Simple Reconnect Routine
The Simple Reconnect Routine is a simple set of steps that resolves most connection issues. Do the following:
- Open your Matador site in a Private or Incognito Browsing Window
- Log in to WordPress Admin
- Go to Matador Jobs, then Settings
- Click on the Button “Bullhorn Connection Assistant”
- If there are any errors at the top, you may need to go straight to the “Reset Connection Routine”
- Click on “Deauthorize Site”
- Click on “Authorize Site”
- Click on “Test Auto Reconnect”
Due to a change in the Bullhorn API, “Test Auto Reconnect” routines on Matador Jobs and Matador Jobs Pro versions 3.7.8 and earlier will now no longer work, and in fact, do more harm than good. Skip this step on versions of 3.7.8 and earlier and upgrade to 3.8.0 upon its release. If you are on version 3.8.0 or later, however, make sure you do the “Test Auto Reconnect” as it helps ensure you did not create a “cookie bug.”
If you didn’t get any errors, congrats you are up and running!
Reset Connection Routine
If your problem still persists and/or you are advised to start with the Reset Connection Routine, you will need to follow these steps:
- Open your Matador site in a Private or Incognito Browsing Window
- Log into WordPress Admin
- Go to Matador Jobs, then Settings
- Click on the Button “Bullhorn Connection Assistant”
- Using a text editor of any kind to hold your credentials, copy-and-paste all your credentials to the file. We will soon be deleting these from your site, so make sure you get them all.
- Click “Reset Connection Assistant”
- Now follow the steps on screen. Any issues that may require Bullhorn support help will be brought to your attention.
- Once you finish, click “Test Auto Reconnect” on the summary screen.
Due to a change in the Bullhorn API, “Test Auto Reconnect” routines on Matador Jobs and Matador Jobs Pro versions 3.7.8 and earlier will now no longer work, and in fact, do more harm than good. Skip this step on versions of 3.7.8 and earlier and upgrade to 3.8.0 upon its release. If you are on version 3.8.0 or later, however, make sure you do the “Test Auto Reconnect” as it helps ensure you did not create a “cookie bug.”
“But I Didn’t Get An Email!”
If you’ve been directed to this page by a member of our support team after days or even weeks of your site being disconnected, you might ask “why didn’t I get that email you mentioned alerting me to this issue?”
Well, it may have been blocked by your mail system.
Depending on the security settings of your email system, emails from within your domain but originating from outside your primary email domain may be flagged as spam or fraudulent. This means mail from your website, including from Matador may never be seen.
While this outside the scope of Matador support, you should make sure to set up mail validation so that email sent from your website is deemed valid by your email system. While there are several protocols, DKIM or Domain Key Identified Mail is the easiest to set up. Ask your webhost for advice on this.
If you haven’t set this up and/or don’t know how, you may want to make your admin email address for Matador an email outside of your domain, like at GMail or Yahoo.