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)

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.

---

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.

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.

---

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

{
  "protocol": "sftp",
  "host": "sftp.yourcompany.com",
  "port": "22",
  "username": "compass_sync_user",
  "password": "provided_by_IT",
  "remotePath": "/employee_data/"
}

1. Click Sync Now to test the connection

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.

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.

---

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

{
  "baseUrl": "https://service4.ultipro.com/personnel/v1",
  "customerApiKey": "your-api-key",
  "basicAuth": "your-basic-auth"
}

1. 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

{
  "subdomain": "your-company",
  "accessToken": "",
  "refreshToken": "",
  "tokenExpiresAt": "",
  "fields": "firstName,lastName,jobTitleName,status,hireDate"
}

1. Click Sync Now to test the connection

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.

---

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

{
  "accessToken": "",
  "refreshToken": "",
  "tokenExpiresAt": "",
  "fields": "displayName,jobTitle"
}

1. Click Sync Now to test the connection

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.

---

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

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.

---

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

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.

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.

---

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

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).

---

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.

This action is permanent. Removing an integration deletes the integration configuration and all related data (participants, fields, and logs). This cannot be undone.

---

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.