Setting up the Greenhouse integration
This section covers the process of setting up the ChartHop Greenhouse integration app which allows you to migrate your job data between Greenhouse and ChartHop.
Setting up the ChartHop Greenhouse integration app requires the following steps:
- Create a Greenhouse API key
- Install the Greenhouse integration app
- Set up the API connection
- Configure the flow of job data
- Set up the flow of new hire data
- Configure outbound group job openings
ATS integrations are typically done with help from ChartHop's professional services. Contact your implementation specialist before beginning these steps.
In order for ChartHop to access your organization's Greenhouse recruiting data, you need to create an API key to provide to ChartHop.
You use Greenhouse to create this API Key. The user that you use to create the API key must have the Can manage ALL organization’s API Credentials permission in Developer permissions. You can work with your Greenhouse administrator if you have questions.
To create your API key, follow the steps outlined in the Greenhouse API Documentation.
Use the Greenhouse instructions to create your API key and enter the following values when creating the key.
Field name | Value |
API type | Harvest |
Partner | ChartHop |
Description | Leave this blank |
Once you create your Harvest API key, a set of permissions are applied to the connection by default. Leave all options as their default settings.
Once you've created your API key, you can install the Greenhouse integration app.
To install the Greenhouse integration app:
- Navigate to Apps from the settings (gear) menu in the left sidebar.
- Select the All Apps tab.
- Scroll the list down to the Greenhouse app.
- Select Install.
Select Install from the app install page.
To allow ChartHop to access your Greenhouse data, enter your Greenhouse API credentials in the proper fields in the Settings section of the app.
Using the following fields, add both your Greenhouse Domain and Harvest API Key:
Field | Description |
Greenhouse Domain | The subdomain used by your Greenhouse instance. For example, if your domain is called: myorg.greenhouse.io, then your subdomain would be “myorg”. |
Harvest API Key | The Harvest API key generated in Greenhouse. |
Once you establish your API connection, you can configure the type of job data flow that the integration runs.
When setting up your integration, you can choose the primary source of truth when referencing new job data. Selecting ChartHop results in an outbound job data flow where ChartHop is the source of truth, whereas, selecting Remote System (Greenhouse) results in an inbound job data flow where the ATS is the source of truth.
To select your Greenhouse integration’s source of truth:
- Navigate to Apps from the settings (gear) menu in the left sidebar.
- Select the All Apps tab.
- Scroll the list down to the Greenhouse app.
- Select the Greenhouse app.
- From the ChartHop Greenhouse app settings page, scroll down to the Source of Truth section.
- Select one of the two options:
- ChartHop - ChartHop is the source of truth and the integration is configured to run an outbound job data flow.
- Remote System (Greenhouse) - Greenhouse is the source of truth and the integration is configured to run an inbound job data flow.
You can configure the Greenhouse integration app to handle two types of data migrations (job data flows) between ChartHop and Greenhouse. Depending on the type of job data flow you choose, you may enable specific configurations that may either be required or optional and yet, recommended.
These are the required and recommended configurations for each job data flow:
Job data flow type | Configurations |
Outbound, ChartHop to Greenhouse | Required
Recommended
|
Inbound, Greenhouse to ChartHop | Required
Recommended
|
To change the configuration options for your Greenhouse integration:
- Navigate to Apps from the settings (gear) menu in the left sidebar.
- Select the All Apps tab.
- Scroll the list down to the Greenhouse app.
- Select the Greenhouse app.
- From the ChartHop Greenhouse app settings page, scroll down to the Other Options section.
- Select from the following configuration options described in the table below.
After you select the integration’s source of truth, you can select additional options to further customize and configure the integration.
Field | Description |
Run Daily | With this option enabled, the ATS app runs automatically every day. When enabled, regardless of data direction, job-related candidate metrics are pulled on a daily basis every morning. For customers on the inbound job data flow direction, this also causes the inbound job data flow to run on a daily basis every morning. |
Sync On Change | Enables the outbound job data data flow direction. When enabled, changes to open jobs are automatically pushed to Greenhouse as soon as they are made in ChartHop. This option cannot be selected when Reverse Sync is enabled. |
Reverse Sync | When enabled, Greenhouse becomes the system of record, and ChartHop is updated with new open roles from Greenhouse when the inbound job data flow runs. This option cannot be selected when Sync On Change is enabled. |
Reconciliation | When enabled, reconciles Greenhouse role and field data with ChartHop, treating ChartHop as the source of truth. For example, if an open job exists in ChartHop but not in Greenhouse, a matching req is created in Greenhouse. Reconciliations can either happen on an ad-hoc basis or on a daily basis if the Run daily option is enabled. This option cannot be selected when Reverse Sync is enabled. |
Remote Location As Default | When enabled, newly synced records that are not assigned a location are assigned the value Remote Location. |
Reuse Closed Jobs | When enabled, in the outbound job data flow, previously closed jobs in Greenhouse are reopened if a new ChartHop job that matches under the previously closed Greenhouse job is created. |
Match Jobs By Job Code | When enabled, it matches ChartHop Jobs with existing Greenhouse Jobs via the Requisition ID in Greenhouse (if the Requisition ID matches the ChartHop Job Code). If no match is found via Requisition ID (Greenhouse) and Job Code (ChartHop), then the integration continues to attempt to match based on the chosen “Group Job Openings” option (such as based on matching Title). If only matching on job codes is desired, then select “None” as the option in “Group Job Openings”. This option cannot be selected when Reverse Sync is enabled. |
You can use the new hire webhook job data flow to bring new hires from Greenhouse to ChartHop when the candidate is marked as “Hired” in Greenhouse, along with their relevant personal information, such as address, phone number, and email.
New hire webhooks are not processed if the person being hired already exists in ChartHop, even if they aren’t actively in a role. This means that we cannot support (via new hire webhooks):
- Internal transfers
- Re-hires
Only the first new hire webhook for a job in ChartHop is supported.
- For example, if you update an offer packet and rehire the candidate in Greenhouse, the updated information are not processed in ChartHop unless the new hire in ChartHop is removed first.
A new hire webhook is not processed if the job does not exist in ChartHop.
All new hire webhook job data flows are inbound (Greenhouse to ChartHop).
To configure the new hire webhook job data flow, follow the steps below.
In ChartHop:
- Select the All Apps tab.
- Scroll the list down to the Greenhouse app.
- Select the Greenhouse app.
- From the ChartHop Greenhouse app settings page, copy the secret key value under Webhook Setup.
In Greenhouse:
- Enter the required information using the table below:
Field | Value |
Name this webhook | charthop-hire |
When | Candidate has been hired |
Endpoint URL | https://webhook.charthop.com/v1/webhook/app/greenhouse/5a12dddd6f2b8f0e63fc8e64/5b15fbf1bd35a93451fc5df3 |
Secret Key | [Obtained above] |
Error recipient email | |
Disabled | No |
Save the web hook when you are done.
ChartHop offers a few ways to group job openings under one job in Greenhouse. As an example, ChartHop jobs can be grouped under the same Greenhouse job as different openings.
This configuration is only available for outbound (ChartHop to Greenhouse) job data flows.
To configure your group job openings, follow these steps below:
- Navigate to Apps from the settings (gear) menu in the left side bar.
- Select the All Apps tab.
- Scroll the list down to the Greenhouse app.
- Select the Greenhouse app.
- From the ChartHop Greenhouse app settings page, scroll down to Group Job Openings.
- From the Group Job Openings section, you can select between the following grouping types:
- Title - Matching on Job Title groups all roles opened in ChartHop under the Greenhouse job that has the same title.
- Title and Location - Matching on Job Title AND Location groups all roles opened in ChartHop under the Greenhouse Job with the same title and location.
- None - When this is selected, a new Greenhouse Job is created for each ChartHop job, and no ChartHop job is created as openings underneath existing Greenhouse Jobs.
Note that these openings still show up as separate roles in ChartHop and are only grouped under the same opening on the Greenhouse end.
