> For the complete documentation index, see [llms.txt](https://docs.talentmap.com/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talentmap.com/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/integrations-connecting-your-hr-data-source.md). # Integrations: Connecting Your HR Data Source Instead of manually uploading a CSV participant file each survey cycle, you can connect your HR data source to Compass so that employee data syncs automatically. Once connected, participant lists are pulled daily and routed to the correct surveys based on filter rules you define. *** ## Overview The Integrations feature connects Compass to your organization's HR system so participant data stays up to date without manual uploads. Compass supports four integration types: | Integration Type | Data Source | Connection Method | | ---------------------- | ----------------------------- | -------------------------------------- | | **SFTP** | CSV files on your SFTP server | Credentials (host, username, password) | | **UKG** | UKG personnel system | API key | | **BambooHR** | BambooHR HR platform | OAuth 2.0 (authorize with one click) | | **Microsoft Entra ID** | Microsoft Entra ID (Azure AD) | OAuth 2.0 (authorize with one click) | | Integration | What it pulls from | How it connects | What your IT team provides | Where to get help | | ---------------------- | -------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **SFTP** | CSV files on your organization's SFTP server | Credentials (host, username, password) | SFTP host address, port number, username and password, folder path where CSV files will be placed | Your IT team for credentials and approvals; TalentMap support through the chat icon in Compass or for Compass questions | | **UKG** | The UKG Personnel API | API key | UKG base URL, customer API key, basic authentication credentials | Your IT team for credentials and approvals; TalentMap support through the chat icon in Compass or for Compass questions | | **BambooHR** | BambooHR HR platform | OAuth 2.0 (authorize with one click) | BambooHR subdomain, which employee fields should be synced, an admin who can approve the authorization | Your IT team for credentials and approvals; TalentMap support through the chat icon in Compass or for Compass questions | | **Microsoft Entra ID** | Microsoft Entra ID (Azure AD) | OAuth 2.0 (authorize with one click) | Which Entra ID user attributes should be synced, an admin who can approve the authorization and may need to grant API permissions in your Azure AD tenant | Your IT team for credentials and approvals; TalentMap support through the chat icon in Compass or for Compass questions | {% hint style="info" %} **One integration per organization.** Each organization can have one active integration at a time. If you need to switch integration types, you'll need to remove the existing one first. {% endhint %} *** ## Before You Begin * **You'll need your IT team.** Regardless of integration type, your IT department will likely need to provide credentials, approve access, or configure permissions on their end. * **Admin access required.** Integrations are only available to users with a TalentMap Admin or Site Admin role. * **Plan your filters first.** Think about which employee fields you'll need for routing participants to the right surveys (e.g., Department, Location, Status). This will determine what data you pull from your source system. {% hint style="info" %} **DIY clients:** If you're setting up an integration for the first time, we recommend an initial setup conversation with TalentMap's product team to make sure everything is configured correctly. Contact TalentMap support through the chat icon in Compass or email to schedule this. {% endhint %} *** ## Step 1: Navigate to Integrations Go to **Admin → Integration** for your organization. If no integration has been set up yet, you'll see an empty state page with an **Add Integration** button.
*** ## Step 2: Add a New Integration 1. Click **Add Integration** 2. Select your integration type from the four options (SFTP, UKG, BambooHR, or Entra ID) 3. Click **OK**
*** ## Step 3: Configure your connection Open the page for your integration type and follow the instructions there: * [SFTP Integration](/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/integrations-connecting-your-hr-data-source/sftp-integration.md) * [UKG Integration](/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/integrations-connecting-your-hr-data-source/ukg-integration.md) * [BambooHR Integration](/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/integrations-connecting-your-hr-data-source/bamboohr-integration.md) * [Microsoft Entra ID Integration](/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/integrations-connecting-your-hr-data-source/microsoft-entra-id-integration.md) *** ## Step 4: Verify Your First Sync After clicking **Sync Now** with valid credentials, the **Connection Response** panel will show either **Success** or an error message. Once a sync succeeds, three new tabs become available: * **Workflow**: where you route participants to surveys * **Notifications**: where you set up email alerts * **Log**: where you track sync history {% hint style="info" %} **Tabs greyed out?** The Workflow, Notifications, and Log tabs only unlock after your first successful sync. If they're greyed out, run **Sync Now** on the Connection tab first. {% endhint %} *** ## Step 5: Configure Your Workflow The Workflow tab is where you control how participant data flows from your HR source into specific surveys. 1. Go to the **Workflow** tab 2. Your **Source** node (representing all synced participant data) is already on the canvas 3. Click **Add Filter** to create a filter rule (e.g., Department EQUALS "Engineering") 4. Click **Add Survey** to add a target survey 5. **Connect the nodes** by drawing edges: Source → Filter → Survey 6. Click a **filter node** to configure its rules 7. Click a **survey node** to select which survey it targets 8. Click **Save** to save your workflow 9. Click **Run Now** to test the full pipeline with live data
{% hint style="info" %} **How it works:** When a sync runs, participant data is pulled from your source, then each participant is evaluated against your filter rules. Matching participants are automatically added to (or updated in) the target survey. {% endhint %} {% hint style="info" %} **Survey must be open.** Only surveys with an "Open" status appear in the survey selection. If you don't see an expected survey, check that it's currently open. {% endhint %} *** ## Step 6: Set Up Notifications 1. Go to the **Notifications** tab 2. Enter the email address where you'd like to receive sync status alerts 3. Set the **days without sync** threshold (default: 1 day). You'll receive a warning if no participant data arrives within this window 4. Click **Save**
*** ## Step 7: Monitor Your Syncs The **Log** tab shows a history of all sync executions, grouped by run. Each group displays the date, execution ID, and a count of actions taken. * **Expand** a log group to see individual actions (participants created, updated, or fields detected) * **Search** to find specific participants, action types, or dates * **Copy to Clipboard** on any log group to get a plain-text summary you can share with your team
{% hint style="info" %} **Daily syncs:** Integrations run automatically once per day at 12:00 UTC. You can also run manual syncs at any time using **Sync Now** (Connection tab) or **Run Now** (Workflow tab). {% endhint %} *** ## Running a Manual Sync You can trigger a sync manually from two places: | Location | Button | What It Does | | ------------------ | -------- | --------------------------------------------------------------- | | **Connection tab** | Sync Now | Tests connection, saves credentials, and runs the full workflow | | **Workflow tab** | Run Now | Saves the current workflow and runs the full workflow | Both options run the complete pipeline: pull data from source → update participant records → apply workflow filters → create or update survey participants. *** ## Removing an Integration To remove an integration, click the **Deactivate** button in the integration header. {% hint style="info" %} **This action is permanent.** Removing an integration deletes the integration configuration and all related data (participants, fields, and logs). This cannot be undone. {% endhint %} *** ## Frequently Asked Questions ### Can my organization have more than one integration? No. Each organization supports one active integration at a time. If you need to switch to a different HR data source, remove the existing integration first and create a new one. ### Can I change the integration type after it's been created? No. The integration type is set at creation and cannot be changed. To switch types, remove the existing integration and create a new one. ### What happens if my data source is unavailable during a scheduled sync? The sync will fail and an error will be logged in the Log tab. If notifications are configured, you'll receive an error email. The scheduler will try again at the next scheduled sync time (daily). Other organizations' integrations are not affected. ### What happens to participants if they're removed from my HR source? Participants are not automatically deleted from Compass when they disappear from the source. They simply won't receive further updates. If you need to remove participants, do so manually in Compass. ### When does the daily sync run? The default schedule is **12:00 UTC** daily. This is configured at the system level and cannot be changed per-integration. ### How are participants identified and matched? All integration types match participants by **email address**. When a sync runs, the system checks whether a participant with that email already exists in Compass. If so, their record is updated; if not, a new participant is created. ### I set up a workflow but participants aren't appearing in my survey. What's wrong? Check the following: * Verify nodes are connected on the Workflow canvas (Source → Filter → Survey) * Check that your filter rules match the actual values in your participant data * Confirm the target survey is currently open * Review the Log tab for any errors during the most recent sync *** ## Troubleshooting ### Data Issues | Issue | Likely Cause | Resolution | | --------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- | | Filter criteria dropdown is empty | No participant fields detected yet | Run at least one sync first. Fields are detected from the source data during sync. | | Notification emails not received | Email not configured or email sending disabled | Check the Notifications tab for a saved email address. Also check your spam folder. | *** ## Related Articles * [Participant Information File](/knowledge-base/step-3-pre-survey-communication-and-setup/participant-information-file.md) * [Adding New or Updating Participants](/knowledge-base/survey-design-and-deployment/import-participants/adding-new-or-updating-participants.md) * [Permissions](/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/users/permissions.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.talentmap.com/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/integrations-connecting-your-hr-data-source.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.