# 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) | {% 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 us through Intercom 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 Follow the instructions for your specific integration type below. #### SFTP SFTP integrations pull participant data from CSV files placed on your organization's SFTP server. **What to ask your IT team:** * SFTP host address (e.g., `sftp.yourcompany.com`) * Port number (usually `22`) * Username and password for the SFTP account * Folder path where CSV files will be placed **To configure:** 1. Enter your SFTP connection details in the credentials JSON field: json ```json { "protocol": "sftp", "host": "sftp.yourcompany.com", "port": "22", "username": "compass_sync_user", "password": "provided_by_IT", "remotePath": "/employee_data/" } ``` 2. Click **Sync Now** to test the connection {% hint style="info" %} **CSV file requirements:** Your CSV files must have a header row with an **Email** column. Standard comma-delimited format is expected. Blank lines are ignored and whitespace is trimmed automatically. {% endhint %} {% hint style="info" %} **Duplicate emails in CSV files:** If the same email address appears in multiple files, files are processed oldest-first and the most recent file's data takes precedence. {% endhint %} *** #### UKG UKG integrations pull participant data directly from the UKG Personnel API. **What to ask your IT team:** * UKG base URL (may vary depending on your UKG environment) * Customer API key * Basic authentication credentials **To configure:** 1. Enter your UKG API credentials in the credentials JSON field: json ```json { "baseUrl": "https://service4.ultipro.com/personnel/v1", "customerApiKey": "your-api-key", "basicAuth": "your-basic-auth" } ``` 2. Click **Sync Now** to test the connection *** #### BambooHR BambooHR integrations connect through OAuth 2.0, which means you authorize the connection with one click rather than entering credentials manually. **What to ask your IT team:** * Your BambooHR subdomain (e.g., `your-company` from `your-company.bamboohr.com`) * Which employee fields should be synced (e.g., first name, last name, job title, department, hire date) * An admin who can approve the authorization when prompted **To configure:** 1. In the **Authorization** section at the top of the Connection tab, enter your BambooHR subdomain 2. Click **Authorize** — this will redirect to BambooHR where your admin needs to approve access 3. After approval, you'll be redirected back to Compass with your tokens populated automatically 4. Review the `fields` value in the credentials JSON — this controls which employee fields are pulled from BambooHR. Edit the comma-separated list to include the fields you need: json ```json { "subdomain": "your-company", "accessToken": "", "refreshToken": "", "tokenExpiresAt": "", "fields": "firstName,lastName,jobTitleName,status,hireDate" } ``` 5. Click **Sync Now** to test the connection {% hint style="info" %} **Choosing your fields:** Only the fields listed in the `fields` value are synced. Include any fields you'll need for workflow filtering or survey respondent data — for example, department, location, or employment status. {% endhint %} *** #### Microsoft Entra ID Entra ID integrations (formerly Azure AD) also connect through OAuth 2.0. **What to ask your IT team:** * Which Entra ID user attributes should be synced (e.g., display name, job title, department) * An admin who can approve the authorization and may need to grant API permissions in your Azure AD tenant **To configure:** 1. Click **Authorize** — this will redirect to Microsoft where your admin needs to approve access 2. After approval, you'll be redirected back to Compass with your tokens populated automatically 3. Review the `fields` value in the credentials JSON — this controls which user attributes are pulled from Entra ID: json ```json { "accessToken": "", "refreshToken": "", "tokenExpiresAt": "", "fields": "displayName,jobTitle" } ``` 4. Click **Sync Now** to test the connection {% hint style="info" %} **Azure AD permissions:** Your IT admin may need to grant API permissions in your Azure AD tenant before the authorization will succeed. If the Authorize button fails, this is the most common cause. {% endhint %} *** ### 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 respondents. *** ### 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. #### What if my OAuth tokens expire (BambooHR or Entra ID)? The system automatically refreshes tokens using the stored refresh token. If automatic refresh fails, go to the **Connection** tab and click **Authorize** to re-authorize the connection. #### What email column does SFTP expect in the CSV? Your CSV file should have a column named **Email** (or a similar email-like column name, such as "EmailAddress"). The system uses email addresses to identify and match participants. #### 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. #### What fields should I include in BambooHR or Entra ID? Include any employee fields you'll use for workflow filtering or that you want attached to survey respondents — common examples include department, location, job title, hire date, and employment status. Only the fields listed in the `fields` value in your credentials are synced. #### 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 #### Connection Errors | Issue | Likely Cause | Resolution | | ---------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | SFTP connection error | Incorrect credentials or server unreachable | Verify host, port, username, password, and remote path with your IT team. Confirm the SFTP server is accessible. | | UKG connection error | Incorrect API key, auth credentials, or base URL | Verify all three values with your IT team. Confirm the correct UKG environment URL. | | BambooHR authorization fails | Wrong subdomain or admin didn't complete approval | Verify the subdomain. Re-click Authorize and ensure an admin completes the approval in the BambooHR redirect. | | Entra ID authorization fails | Azure AD tenant blocked authorization or insufficient API permissions | Your IT admin may need to grant API permissions in the Azure AD tenant. Re-click Authorize and ensure the admin completes the consent flow. | #### Data Issues | Issue | Likely Cause | Resolution | | ----------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Sync succeeds but no participants created (SFTP) | CSV missing an identifiable email column | Check your CSV file — ensure one column is named "Email" or similar. | | Sync succeeds but no participants created (API types) | API returned no records or email field not mapped | Verify the `fields` list includes the correct field names. Confirm employee records have email addresses. | | 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. | --- # Agent Instructions: 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: ``` GET https://docs.talentmap.com/knowledge-base/step-5-analyze-interpret-and-report/compass-admin/integrations-connecting-your-hr-data-source.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.