Summary: Column mapping tells User Sync which fields in your HR data fill which user attributes in Speakap. This guide walks you through the mapping interface, the required and optional fields, date normalization, and how custom expressions can clean up your data along the way.
1. The core mapping interface
Once a connector is set up, the Column mapping section is where you 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: click the clock icon to open the Change history. It shows when a mapping was modified, by whom, and any comments that were added.
- Version control: you can switch between different mapping configurations or create a new one with the + button.
2. Primary identity fields
The most critical part of your mapping is identifying the user and their basic profile information.
- External ID (XID): this is a required field. The XID is the unique, permanent anchor for the user. It is typically mapped to a field like employeeId.
- Default Role: assigns a standard permission level (for example "Member") to all users processed by this sync. You can check your roles in Speakap under Network Settings, then Roles. If you need the role ID, email technicalimplementations@speakap.nl.
- Employment Start Date: this can be mapped to your HR start date. Speakap supports date normalization so your HR date format matches Speakap's requirements (for example, converting DD/MM/YYYY to YYYY-MM-DD).
3. Profile and contact information
You can map standard identity attributes so user profiles are complete and professional. None of these fields are mandatory. The only mandatory field for a user is their XID, which is usually the HR-IS or payroll system ID, or the employee number.
- Family Name and Given Name: linked to your surname and first name fields.
- Emails: you can add multiple email mappings.
- Primary flag: designate which email is the primary contact (for example work.email) and which is secondary (for example 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 sits in the company structure and what appears on their profile card. None of these fields are mandatory, but they enrich the experience and make it easier to target the right people in Speakap.
- Active Status: use expressions to determine whether a user should be active. For example: internal.status == "Active" ensures only active employees from the HR-IS source are synced.
- Title: mapped to the user's professional job title (for example work.title).
- Department: mapped to the functional department (for example work.department).
- Division: mapped to the geographical or structural division (for example work.site).
5. Advanced field options
By clicking Add another field, you 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
User Sync supports custom expressions within Column mapping. They allow you to:
- Combine fields: merge a first and last name if your HR tool provides them separately.
- Conditional mapping: use "if/then" logic (for example, if email is null, use privateEmail) so no user is left without a contact method.
- Data cleaning: strip unwanted characters or prefixes from employee IDs during the sync.
For more detail, see Guide to Custom expressions in User Sync.
Still stuck?
Email us at technicalimplementations@speakap.nl with your network name and a description of the mapping you are trying to set up, and we'll help you out.