---
title: HiBob 字段映射
description: 连接 HiBob 后，Pyn 可以从 HiBob 填充的消息令牌和员工资料字段、每个字段背后的 Bob 字段、还有哪些其他来源可以提供它，以及某个值不显示时该检查什么。
sidebar:
  order: 1
area: integrations
feature: hibob
appPath: /settings/integrations/installed
lastVerified: 2026-11-15
version: "2026-11-06"
audience: admin
related:
  - flows/steps/reference-tokens
  - integrations/hibob
  - integrations/hris-fields
  - directory/employees/reference-employee-properties
  - directory/employees/fix-missing-details
translation:
  source: integrations/hibob/field-mapping.mdx
  sourceSha: 2642a82ed96efd584f86db853f16c51104e71d57
---

消息中的令牌，例如 `principal.preferredName` 或 `principal.managerName`，读取的是该员工在 Pyn 中资料上的一个字段。连接 HiBob 后，Pyn 可以从 Bob 填充这些资料字段。一个字段是否有值，取决于你的 Bob 租户持有什么、所连接的 Bob 账户能查看什么，以及还连接了哪些其他来源。用下面的表格把令牌追溯到需要在 Bob 中填写或更正的 Bob 字段。

## 令牌及其背后的 Bob 字段

在编辑器工具栏中选择 **Insert token**，或输入 `@`，列表会在 **principal**（已注册的员工）和 **recipient**（收到消息的人）下按名称显示每个令牌。每一行都是 Pyn 可以从 Bob 填充的令牌，而不是总有值的令牌：资料字段为空时，令牌显示它的回退值。下面每个在列表中有 `recipient` 对应项的 `principal` 令牌，为收件人读取同一个字段。

| 令牌 | 读取的资料字段 | Bob 字段 id |
| --- | --- | --- |
| `principal.preferredName`（列为 **Preferred Name**） | **Preferred Name**，否则为 **Display Name** 的第一个词 | `root.displayName` |
| `principal.firstName` | **Display Name** 的第一个词 | `root.displayName` |
| `principal.preferredFullName` | **Preferred Name** 加姓氏，否则为 **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`，否则为 `address.city` |
| `principal.startDate`、`principal.startDate.dayAfter`、`principal.startDate.nextBusinessDay`、`principal.nextAnniversary` | **Start Date** | `work.startDate` |
| `principal.tenure` | **Tenure Date**，否则为 **Start Date** | `work.originalStartDate`，否则为 `work.startDate` |
| `principal.birthday`、`principal.nextBirthday` | **Birthday** | `personal.shortBirthDate` |
| `principal.managerName`、`principal.managerPreferredName`、`principal.managerEmail` | **Manager** 的 **Display Name** 和 **Primary Email Address** | `work.reportsTo` 确定经理；经理自己的 `root.displayName` 和 `root.email` 填充值 |
| `principal.hrbp.name`、`principal.hrbp.preferredName`、`principal.hrbp.preferredFullName`、`principal.hrbp.email` | **HRBP** 的姓名和邮箱 | `employee.hrbp` 确定 HRBP；其自己的 `root.displayName` 和 `root.email` 填充值 |
| `principal.buddy.name`、`principal.buddy.preferredName`、`principal.buddy.preferredFullName`、`principal.buddy.email`、`principal.buddy.startDate.nextBusinessDay` | **Buddy** 的姓名、邮箱和入职日期 | 你的伙伴自定义字段确定伙伴；其自己的 `root.displayName`、`root.email` 和 `work.startDate` 填充值 |

Bob 没有 Pyn 读取的常用名字段，所以常用名令牌显示 Bob 的 Display name 的第一个词，除非另一个来源提供了常用名。

列表中这些令牌没有 HiBob 来源：`date.reference`，即注册的参考日期，以及 `recipient.surveyLink`。

对于其他任何资料字段，例如 **Probation End Date** 或 Pyn 支持团队已映射的 Bob 自定义字段，选择 **Insert token**，然后选择 **Employee Field…**，再选择该字段。在 Raw HTML 电子邮件中，`principal.email` 读取 `root.email`，`principal.personalEmail` 读取 `home.privateEmail`，`principal.endDate` 读取 `internal.terminationDate`，`principal.country` 读取 `address.country`。每个令牌及其回退值见[令牌](https://support.pyn.ai/zh-cn/flows/steps/reference-tokens/)。

## HiBob 可以填充的资料字段

第一列是该字段在 Pyn 员工资料上的标签。每一行都是 Pyn 可以从 Bob 填充的字段，而不是每份资料都有的字段：Bob 没有值或所连接账户无法查看时，字段保持为空，并且可以由另一个来源提供。Bob 字段 id 是 Bob 的 API 用来指代该字段的名称。

| Pyn 字段 | Bob 中的字段 | Bob 字段 id | 说明 |
| --- | --- | --- | --- |
| **Display Name** | Display name | `root.displayName` | 回退到 Full name，再到 First name 和 Last name。 |
| **Legal Name** | Full name | `root.fullName` | 回退到 First name 和 Last name（`root.firstName`、`root.surname`）。 |
| **Primary Email Address** | Email | `root.email` | 消息发往的工作地址。也用于匹配记录。 |
| **Personal Email Address** | Personal email | `home.privateEmail` | 用于匹配还没有工作地址的待入职者。 |
| **Job Title** | Job title | `work.title` | |
| **Department** | Department | `work.department` | 值按 Bob 显示的样子读取，而不是其列表 id。 |
| **Location** | Site | `work.site` | 回退到地址中的城市（`address.city`）。 |
| **Primary Country** | Country | `address.country` | 来自地址。 |
| **Postal Code** | Postal code | `address.postalCode` | 来自地址。 |
| **Time Zone** | 无 | | 由国家和邮政编码推算；见下文。 |
| **Birthday** | Date of birth | `personal.shortBirthDate` | 只有日和月。 |
| **Start Date** | Start date | `work.startDate` | |
| **Tenure Date** | Original start date，否则为 Start date | `work.originalStartDate`、`work.startDate` | Bob 有原始入职日期时从它起算，否则与 **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` | HiBob 专有的属性。为 **Tenure Date** 提供数据。 |
| **Active status** | Lifecycle status，然后是 Status | `internal.lifecycleStatus`、`internal.status` | 包含 "leave" 的生命周期状态为 **On Leave**。否则，Status 为 Active 或为空时是 **Active**，其他任何值是 **Inactive**。 |
| **Manager** | Reports to | `work.reportsTo` | 匹配到经理的 Bob 记录。见下文[经理](#经理)。 |
| **HRBP** | HRBP | `employee.hrbp` | 匹配到 HRBP 的 Bob 记录。 |
| **Buddy** | 你的伙伴字段 | 一个自定义字段 | Bob 没有标准的伙伴字段。由 Pyn 支持团队设置哪个自定义字段持有它。 |
| 自定义字段 | 你选择的字段 | 任意字段 id | 按文本、是/否、日期或数字读取。由 Pyn 支持团队为你逐个映射。 |

Pyn 不从 Bob 读取这些字段：**Preferred Name**、**Avatar Image**、**Secondary Email Address**、**Employment Type**、**Business Unit**、**Division**、**Team** 和 **Mentor**。Bob 的雇用类型和合同字段不会映射到 **Employment Type**；Pyn 支持团队可以改为把其中任一个映射为自定义字段。Bob 中的其他任何自定义字段，例如 "Manager ID" 字段，除非被映射，否则会被忽略。

### 经理

Pyn 取 **Reports to** 中的 id，并找到具有该 id 的 Bob 员工。Bob 没有返回 id 时，Pyn 使用来自 Bob 的经理 **Employee ID**（`work.reportsToIdInCompany`），并把它匹配到同一 Bob 公司中具有该 **Employee ID**（`work.employeeIdInCompany`）的人。经理也必须在同步范围内，所以所连接的 Bob 账户需要对其记录有查看权限。

### 时区

Pyn 不从 Bob 读取时区。它根据 **Primary Country** 和 **Postal Code** 推算：对美国、加拿大和澳大利亚使用邮政编码，对只有一个时区的国家只使用国家。对于有多个时区的其他国家，Pyn 使用此人的 Slack 时区（如果有）；否则 **Time Zone** 保持为空，按收件人时区排期的步骤会改为按工作区时区发送。

## 同步如何运行

Bob 中的更改会在大约一小时内到达 Pyn 以及下一条发出的消息中的令牌。Bob 中没有任何变化的一次运行会在 **History** 下记录为 "Successfully integrated to HiBob. No employee changes found"。Pyn 只从 Bob 读取，绝不写回。

离职员工留在同步范围内，这样他们的离职日期才会到达。从 Bob 结果中消失的人会被标记为 **Removed**，并变为 **Terminated**。

## 故障排除

| 你看到的 | 该检查什么 |
| --- | --- |
| 令牌显示它的回退值，例如 "Manager" 或 "department" | 它背后的资料字段为空。在[员工](https://support.pyn.ai/zh-cn/directory/employees/)中打开此人并检查该字段，然后查看下面各行。其他已连接的来源也可以填充某些字段；资料的 **Sources** 标签页列出此人背后的每条记录。 |
| 字段在 Bob 中已填写但在 Pyn 中为空 | 在 **Installed** 下打开 HiBob 集成并选择 **Advanced**。**Fields in Report** 列出 Bob 返回了什么以及针对多少人。缺少某个字段意味着服务用户的权限组，或者你用 **Connect with HiBob** 登录时你自己的账户，无法查看它。Bob 会直接省略这样的字段而不报错。 |
| **Manager** 为空 | Bob 中的 **Reports to** 为空、权限组无法查看它，或服务用户看不到该经理。持有经理 id 的自定义字段不会被读取。 |
| **Location** 显示的是城市 | 此人在 Bob 中没有 Site，所以 Pyn 使用了地址中的城市。 |
| 缺少某个 Bob 自定义字段 | 自定义字段只有在 Pyn 支持团队映射之后才会读取。 |
| Bob 中的更改还没有到达 | 等待下一次每小时刷新，并检查集成上的 **History**。 |

## 相关

- [令牌](https://support.pyn.ai/zh-cn/flows/steps/reference-tokens/)，查看每个令牌、它的回退值和格式。
- [HiBob](https://support.pyn.ai/zh-cn/integrations/hibob/)，连接 Bob 并授予 Pyn 所需的权限。
- [HRIS 字段](https://support.pyn.ai/zh-cn/integrations/hris-fields/)，把 HiBob 与其他来源对比。
- [员工属性](https://support.pyn.ai/zh-cn/directory/employees/reference-employee-properties/)，查看 Pyn 的每个字段。
- [修复缺失的经理、时区或电子邮件](https://support.pyn.ai/zh-cn/directory/employees/fix-missing-details/)，更正某个值。
