Article summary: Custom expressions provide the logical power behind Speakap’s User Sync. They allow administrators to 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 intervention.
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 (e.g., seasonal workers vs. 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 be used to choose between two data points if one is missing or to 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 (e.g., "Management").
- Field Names: Ensure the field names in your expression exactly match the column headers in your HR export file.
Testing: Use the Dry Run feature within the mapping settings to verify that your expression matches the expected number of users before applying changes.