Article summary: Column mapping is the "translation engine" of Speakap User Sync. It takes the raw data from your HR system and maps it to specific user attributes within Speakap. This guide provides a deep dive into available fields, normalization logic, and configuration best practices.
1. The core mapping interface
Once a connector is established, the Column mapping section allows you to define which HR attributes represent Speakap's core identity fields. You can create multiple mapping versions and view their change history to track modifications over time.
- Revision History: By clicking the clock icon, you can view the Change history (as seen in screenshots), showing when a mapping was modified, by whom, and any relevant comments.
- Version Control: You can easily switch between different mapping configurations or create a new one using the + button.
2. Primary identity fields
The most critical part of your mapping involves identifying the user and their basic profile information.
- External ID (XID): This is a required field. This is the unique, permanent anchor for the user. As shown in the screenshots, this is typically mapped to a field like employeeId.
- Default Role: Assigns a standard permission level (e.g., "Member") to all users processed by this sync. You can check your roles in Speakap when you navigate to Network Settings - Roles. You can request the ID from your customer success manager or Speakap’s support team.
- Employment Start Date: This can be mapped to your HR start date. Speakap allows for Date Normalization to ensure your HR date format matches Speakap’s requirements (e.g., converting DD/MM/YYYY to YYYY-MM-DD).
3. Profile and contact information
You can map standard identity attributes to ensure user profiles are complete and professional. None of these fields are mandatory, but optional. The mandatory field we need of a User is their XID (mostly the HR-IS/ Payroll System ID or employee number)
- Family Name & Given Name: Linked to surname and first name fields.
-
Emails: You can add multiple email mappings.
- Primary Flag: You can designate which email is the primary contact (e.g., work.email) and which is secondary (e.g., home.privateEmail).
- Labels: Assign custom labels like "Work" or "Personal" to these fields for clarity in settings.
4. Organizational and functional mapping
These fields determine where a user resides within the company structure and what information appears on their profile card. None of these fields are mandatory, but optional. It will enrich the experience and improve targeting the right people in Speakap.
- Active Status: Use expressions to determine if a user should be active. For example in the screenshot you can see: internal.status == "Active" which ensures only active employees from the HR-IS source are synced.
- Title: Mapped to the user's professional job title (e.g., work.title).
- Department: Mapped to the functional department (e.g., work.department).
- Division: Mapped to the geographical or structural division (e.g., work.site).
5. Advanced field options
By clicking Add another field, administrators can access a wide range of optional attributes to further enrich the user experience:
| Field Category | Available Options |
| Identity | Nick name, Formatted name, User type, Locale |
| Contact | Phone numbers, SMS, Login (Username) |
| Organization | Manager, Organization, Cost center |
| Personal | Birthday, Honorific prefix/suffix, Middle name |
| Technical | Timezone, Password, Activity Control Exempt |
6. Custom Data Manipulation
Speakap User Sync supports Custom Expressions within column mapping. This allows you to:
- Combine Fields: Merge a first and last name if your HR tool provides them separately.
- Conditional Mapping: Use "if/then" logic (e.g., if email is null, use privateEmail) to ensure no user is left without a contact method.
- Data Cleaning: Strip unwanted characters or prefixes from employee IDs during the sync process.
Check out the article about custom expressions for more details on this part.