HiBob field mapping
A token in a message, such as principal.preferredName or principal.managerName, reads a field on the employee’s profile in Pyn. When HiBob is connected, Pyn can fill those profile fields from Bob. Whether a field has a value depends on what your Bob tenant holds, what the connected Bob account can view, and which other sources are connected. Use the tables to trace a token back to the Bob field to fill in, or to correct, in Bob.
Tokens and the Bob fields behind them
Section titled “Tokens and the Bob fields behind them”Select Insert token in the editor toolbar, or type @, and the list shows each token by its name under principal (the enrolled employee) and recipient (the person receiving the message). Each row is a token Pyn can fill from Bob, not one that always has a value: when the profile field is empty, the token shows its fallback. Every principal token below with a recipient twin in the list reads the same field for the recipient.
| Token | Profile field it reads | Bob field id |
|---|---|---|
principal.preferredName (listed as Preferred Name) |
Preferred Name, else the first word of Display Name | root.displayName |
principal.firstName |
First word of Display Name | root.displayName |
principal.preferredFullName |
Preferred Name and surname, else Display Name | root.displayName |
principal.legalName |
Legal Name | root.fullName |
principal.jobTitle |
Job Title | work.title |
principal.department |
Department | work.department |
principal.location |
Location | work.site, else address.city |
principal.startDate, principal.startDate.dayAfter, principal.startDate.nextBusinessDay, principal.nextAnniversary |
Start Date | work.startDate |
principal.tenure |
Tenure Date, else Start Date | work.originalStartDate, else work.startDate |
principal.birthday, principal.nextBirthday |
Birthday | personal.shortBirthDate |
principal.managerName, principal.managerPreferredName, principal.managerEmail |
The Manager’s Display Name and Primary Email Address | work.reportsTo picks the manager; their own root.displayName and root.email fill the values |
principal.hrbp.name, principal.hrbp.preferredName, principal.hrbp.preferredFullName, principal.hrbp.email |
The HRBP’s name and email | employee.hrbp picks the HRBP; their own root.displayName and root.email fill the values |
principal.buddy.name, principal.buddy.preferredName, principal.buddy.preferredFullName, principal.buddy.email, principal.buddy.startDate.nextBusinessDay |
The Buddy’s name, email and start date | Your buddy custom field picks the buddy; their own root.displayName, root.email and work.startDate fill the values |
Bob has no preferred name field that Pyn reads, so the preferred-name tokens show the first word of Bob’s Display name, unless another source supplies a preferred name.
These tokens in the list have no HiBob source: date.reference, which is the enrollment’s reference date, and recipient.surveyLink.
For any other profile field, such as Probation End Date or a Bob custom field that Pyn support has mapped, select Insert token, then Employee Field…, and choose the field. In a Raw HTML email, principal.email reads root.email, principal.personalEmail reads home.privateEmail, principal.endDate reads internal.terminationDate and principal.country reads address.country. See Tokens for every token and its fallback.
Profile fields HiBob can fill
Section titled “Profile fields HiBob can fill”The first column is the field’s label on the employee profile in Pyn. Each row is a field Pyn can fill from Bob, not one every profile has: a field stays empty when Bob has no value or the connected account cannot view it, and another source can supply it instead. The Bob field id is the name Bob’s API uses for the field.
| Pyn field | Field in Bob | Bob field id | Notes |
|---|---|---|---|
| Display Name | Display name | root.displayName |
Falls back to Full name, then First name and Last name. |
| Legal Name | Full name | root.fullName |
Falls back to First name and Last name (root.firstName, root.surname). |
| Primary Email Address | root.email |
The work address messages go to. Also used to match records. | |
| Personal Email Address | Personal email | home.privateEmail |
Used to match a pre-hire who has no work address. |
| Job Title | Job title | work.title |
|
| Department | Department | work.department |
The value as Bob shows it, not its list id. |
| Location | Site | work.site |
Falls back to the Address city (address.city). |
| Primary Country | Country | address.country |
From the address. |
| Postal Code | Postal code | address.postalCode |
From the address. |
| Time Zone | None | Worked out from country and postal code; see below. | |
| Birthday | Date of birth | personal.shortBirthDate |
Day and month only. |
| Start Date | Start date | work.startDate |
|
| Tenure Date | Original start date, else Start date | work.originalStartDate, work.startDate |
Counts from Bob’s original start date when it has one, otherwise the same as Start Date. |
| Termination Date | Termination date | internal.terminationDate |
|
| Probation End Date | Probation end date | internal.probationEndDate |
|
| Original Start Date in HiBob | Original start date | work.originalStartDate |
A HiBob-only property. Feeds Tenure Date. |
| Active status | Lifecycle status, then Status | internal.lifecycleStatus, internal.status |
A lifecycle status containing “leave” is On Leave. Otherwise a Status of Active, or none, is Active, and anything else is Inactive. |
| Manager | Reports to | work.reportsTo |
Matched to the manager’s Bob record. See Manager below. |
| HRBP | HRBP | employee.hrbp |
Matched to the HRBP’s Bob record. |
| Buddy | Your buddy field | A custom field | Bob has no standard buddy field. Pyn support sets which custom field holds it. |
| Custom fields | The field you choose | Any field id | Read as text, yes/no, a date or a number. Pyn support maps each one for you. |
Pyn does not read these from Bob: Preferred Name, Avatar Image, Secondary Email Address, Employment Type, Business Unit, Division, Team and Mentor. Bob’s employment type and contract fields are not mapped to Employment Type; Pyn support can map either one as a custom field instead. Any other custom field in Bob, such as a “Manager ID” field, is ignored unless it is mapped.
Manager
Section titled “Manager”Pyn takes the id inside Reports to and finds the Bob employee with that id. When Bob returns no id, Pyn uses the manager’s Employee ID from Bob (work.reportsToIdInCompany) and matches it to the person with that Employee ID (work.employeeIdInCompany) in the same Bob company. The manager must be in the sync too, so the connected Bob account needs view access to their record.
Time zone
Section titled “Time zone”Pyn reads no time zone from Bob. It works one out from Primary Country and Postal Code: the postal code for the United States, Canada and Australia, and the country alone where it has a single time zone. For other countries with more than one time zone, Pyn uses the person’s Slack time zone where they have one; otherwise Time Zone stays empty, and a step scheduled in the recipient’s time zone sends in the workspace time zone instead.
How the sync runs
Section titled “How the sync runs”A change in Bob reaches Pyn, and the tokens in the next message sent, within about an hour. A run where nothing changed in Bob is recorded under History as “Successfully integrated to HiBob. No employee changes found”. Pyn reads from Bob only and never writes back.
Leavers stay in the sync, so their termination dates arrive. A person who disappears from Bob’s results is marked Removed and becomes Terminated.
Troubleshooting
Section titled “Troubleshooting”| What you see | What to check |
|---|---|
| A token shows its fallback, such as “Manager” or “department” | The profile field behind it is empty. Open the person in Employees and check the field, then the rows below. Other connected sources can also fill some fields; the profile’s Sources tab lists every record behind a person. |
| A field is filled in Bob but empty in Pyn | Open the HiBob integration under Installed and select Advanced. Fields in Report lists what Bob returned and for how many people. A missing field means the service user’s permission group, or your own account if you signed in with Connect with HiBob, cannot view it. Bob leaves such a field out without an error. |
| Manager is empty | Reports to is empty in Bob, the permission group cannot view it, or the manager is not visible to the service user. A custom field holding a manager id is not read. |
| Location shows a city | The person has no Site in Bob, so Pyn used the address city. |
| A Bob custom field is missing | Custom fields are read only once Pyn support maps them. |
| A change in Bob has not arrived | Wait for the next hourly refresh and check History on the integration. |
Related
Section titled “Related”- Tokens for every token, its fallback and its formatting.
- HiBob to connect Bob and grant the permissions Pyn needs.
- HRIS fields to compare HiBob with the other sources.
- Employee properties for every Pyn field.
- Fix a missing manager, time zone or email to put a value right.