Skip to content
PynPyn

IntegrationsHiBob

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.

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.

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 Email 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.

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.

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.

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.

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.