Summary: Custom expressions provide the logical power behind Speakap's User Sync. They let you create sophisticated rules for filtering users, assigning groups, and mapping dynamic profile data based on specific conditions in your HR source file.
1. Understanding expressions
Expressions are logical statements used within Column mapping, Group mapping, and Role mapping to determine how data is interpreted. By using operators (like "equals" or "contains"), you can automate complex organizational requirements without manual work.
2. Common logical operators
To build an expression, you use standard logical symbols to compare HR data fields to specific values.
| Function | Operator | Example Expression | Meaning |
| Equals | == | Department == "WW" | All users in department "WW". |
| Does not equal | != | Department != "WW" | All users except those in department "WW". |
| Greater than | > | externalId > 100 | All users with an ID number higher than 100. |
| Less than | < | externalId < 100 | All users with an ID number lower than 100. |
| Greater/Equal to | >= | externalId >= 100 | All users with an ID of 100 or higher. |
| Less/Equal to | <= | externalId <= 100 | All users with an ID of 100 or lower. |
3. Advanced functional expressions
Sometimes simple comparisons aren't enough. Speakap supports advanced functions to search within text strings or handle numerical ranges.
- Contains value (includes): used to search for a specific word within a larger field.
- Example: includes('Jobtitle', "bedrijfsleider") and Department == "WW"
- Meaning: targets everyone in department "WW" whose job title includes the word "bedrijfsleider".
- Exclusion (not): used to invert a rule.
- Example: Division == "WR" and not(startsWith(externalId, "0004"))
- Meaning: targets everyone in division "WR" except those whose employee ID starts with "0004".
- Starts with (startsWith): targets users based on the beginning characters of a string.
- Example: use this to filter batches of employees by ID prefixes (for example, seasonal workers versus permanent staff).
4. Handling ranges and multiple conditions
You can combine multiple logical checks using and or or to target precise user groups.
- Numerical ranges: to target a specific block of cost centers or IDs.
- Example: externalID >= 4000 and externalID <= 4900
- Meaning: select everyone with a department code between 4000 and 4900 inclusive.
5. Dynamic data selection (Ternary logic)
Expressions can choose between two data points if one is missing, or set a preference, such as email addresses or system languages.
- Email fallback: ensures a user always has an email address mapped.
- Expression: 'E-mail work' ? 'E-mail work' : 'E-mail private'
- Meaning: use the "Work Email" column; if that is blank, use the "Private Email" column instead.
- Language selection: dynamically sets the invitation and interface language based on a user's cost center.
- Expression: ('Primary Costcenter' >= 4000 and 'Primary Costcenter' <= 4899) or ('Primary Costcenter' >= 4900 and 'Primary Costcenter' <= 4999) ? "fr-FR" : "en-GB"
- Meaning: users in cost centers 4000-4999 receive a French interface email; everyone else receives an English one.
6. Best practices for building expressions
- Quotes: always wrap text values (strings) in double quotes (for example "Management").
- Field names: make sure the field names in your expression exactly match the column headers in your HR export file.
- Testing: use the Dry run within the mapping settings to verify that your expression matches the expected number of users before applying changes. See Using the Dry run to validate and apply sync changes.
Still stuck?
Email us at technicalimplementations@speakap.nl with your network name and the expression you are trying to build, and we'll help you out.