同步与集成
本页内容
同步功能会自动将您其他系统中的人员镜像到 Users 中，使门禁访问权限跟随外部数据源，无需手动录入。本页介绍三种同步来源、Performance Hub 员工同步、标识符、由来源管理的 Access Time Windows、新鲜度和范围映射、移除、重复项处理、同步活动面板、邀请以及批量删除。所有配置均在 Settings → Sync settings 下完成。
Performance Hub staff 同步默认开启。集成和 Computer Vision 同步默认关闭，以便现有设施保留其手动管理的列表；在您启用相应来源之前，不会从这些来源同步任何内容。
同步来源
图 1：Sync settings
| 来源 | 镜像内容 | 生成的用户来源标记 |
|---|---|---|
| Performance Hub staff | 角色中包含此设施的 Performance Hub 用户 | Performance Hub staff |
| 集成 | 来自已连接集成的会员，以及（在支持的情况下）由来源管理的 Access Time Windows | Integration / 合作伙伴名称 |
| Performance Hub features (CCTV/Computer Vision) | 来自 CCTV 模块的已识别人员 | CCTV/Computer Vision |
每个区块都有各自的启用开关，并显示上次运行时间和计数（或 Never run）。
对于集成来源，您还可以在 Sync from these integrations 下选择启用或停用单个集成："Turn off an integration to stop mirroring its people. People already synced stay until you remove them." 点击 Show all integrations 可展开完整列表。
要求标识符
人员通过发送到其手机或电子邮箱的一次性验证码登录移动应用，因此既没有手机号也没有电子邮件地址的记录对门禁访问毫无用处。Require identifier 下拉菜单控制同步哪些记录：
| 选项 | 同步的记录 |
|---|---|
| Email OR phone（默认） | 有电子邮件地址或手机号 |
| Email required | 有电子邮件地址 |
| Phone required | 有手机号 |
| Both required | 两者都有 |
不符合要求的记录会被跳过（并在同步活动面板中显示为因缺少标识符而跳过）。
Access Time Window 映射和来源新鲜度
每个提供 Access Time Windows 的集成都有各自的设置：
- Access Time Window mapping："Map each partner scope key to facility doors or Access Scopes. Unknown and unmapped keys fail closed." 每个集成最多可以有 50 个映射，包括
default键。在 Add partner scope key 下添加键。 - Source freshness policy：一项安全设置："Choose how old a partner snapshot may be before all of its windows fail closed." 请将其设置为与集成承诺的更新频率相匹配，以免已停止更新的集成中的时间窗口继续授予访问权限。
有关集成时间窗口的更新方式，请参阅 Access Time Window 快照。
Performance Hub 员工
图 2：Performance Hub 员工来源
"Anyone whose Performance Hub roles cover this facility is added to Users automatically and kept in step with Performance Hub IAM." 例如，零售连锁店的门店员工无需任何人手动添加即可获得后场区域门的访问权限。
- 员工（Performance Hub 用户）同步时会带有标签 Performance Hub staff、Role: …（每个角色一个），组织管理员还会带有 Organisation admin。
- 系统会为每个设施创建一次可编辑的 Performance Hub staff Access Policy，允许带有该标签的人员随时通过每扇门。该卡片会显示策略是否处于活动状态，并提供 Edit policy。您可以像编辑任何 Access Policy 一样编辑或停用它。
- Roles 显示包含哪些角色。要包含或排除的角色由组织管理员在 Organisation Settings 中设置；其他管理员会看到 "Ask an organisation admin to change this in Organisation Settings."
- 关闭同步时需要确认（"Turn off Performance Hub staff sync?"）。
员工详细信息在 Performance Hub IAM 中管理，在 Users 中为只读。要停止某位员工的门禁访问权限，请参阅 Users → Performance Hub 员工。
同步的运行时间
| 触发方式 | 时间 |
|---|---|
| Continuous | Performance Hub 员工的变更以及已连接集成推送的变更通常会实时同步 |
| Daily full sync | "A full reconcile also runs automatically every day to catch any inconsistencies." Next full sync 显示下一次运行的时间 |
| Sync now | 此页面上的该按钮会从您的集成拉取最新数据，然后将其协调到 Users 中；按钮会先显示 Running…，然后显示 Sync complete（或 Sync failed） |
同步会更新哪些内容，以及永远不会改动哪些内容
每次同步时，已同步的行都会根据来源进行刷新：
| 每次同步时覆盖 | 保留（由管理员管理） |
|---|---|
| 名字、姓氏 | Access enabled 开关 |
| 手机号、电子邮件地址 | Additional permanent access |
| 人员类型、会员状态 | Custom tags |
| 同步的标签 | Notes |
| 上次同步时间戳 | 解除关联状态、应用消息 |
| 该来源管理的 Access Time Windows | Permanent grants and administrator-owned Access Time Windows |
因此，您可以放心地停用已同步的用户、为其授予权限或添加标签，同步不会撤销这些操作。
**解除关联：**在用户面板上关闭 Track source updates 后，同步会完全跳过该行：对姓名或联系方式的编辑会保留，来源中的移除也不再影响该用户。请参阅 Users。
对于提供 Access Time Windows 的来源，解除关联还会在明确确认后清除该来源的时间窗口。重新关联后，这些时间窗口会在下一次成功的完整快照中恢复；它不会恢复来自失败获取的缓存时间窗口。
移除
当会员在集成中被删除时，其门禁访问权限会被移除（Removed by integration）。其 Users 行不会被删除，因此历史记录会保留。
如果某次同步会一次性移除异常多的人员，这些移除会被暂缓以待审核（N removals held back for review）。超过安全上限的集成驱动移除会等待管理员审核后才生效，因此来自集成的错误拉取不会一次性移除所有人的访问权限。
Access Time Window 快照
每个集成只更新其自身的来源分区。其会员更新是一个完整的、修订号单调递增的时间窗口快照：
- 省略时间窗口数据时，当前来源快照保持不变。
- 较新的快照会替换该来源的完整列表。
- 相同修订号且规范化负载相同时，视为幂等重放。
- 相同修订号但数据不同时，视为冲突；较旧的修订号会作为过时数据被跳过。
- 较新的空快照会明确撤销该来源的时间窗口。
- 上游获取失败或不完整时，必须不发送快照，绝不能发送空快照或部分快照。
每个稳定的来源 scope_key（包括 default）都在 Access Time Window 映射下映射到整个设施、门或 Access Scope 目标。未知或已停用的映射会以关闭方式失效。设置中还会显示来源的时效以及集成的来源新鲜度策略。
重复项处理
图 3：重复项处理
“当两个人共享一个电子邮箱或手机号码时，只有一个人可以同步到“用户”中。请选择保留名额的人；另一个人会被标记为冲突并不予同步。”
- Prefer the active person："A person with an active status always wins over an expired one. Turn off to apply the tiebreaker regardless of status."
- Tiebreaker：当状态无法决定胜出者时使用，例如 Oldest By Date Of Birth, Then Earliest Start Date。
另一条记录会在 Users 中显示 Not synced – duplicate，并计入 Not synced 磁贴。例如，当某位临床医生既是员工又是患者会员时，医疗诊所可以只保留一条记录。
自动应用邀请
在 App invitations 下，Auto-send app invitations 会向尚未收到邀请的符合条件的已同步用户发送电子邮件，Advanced recipient rules 可以限制接收邀请的人员。Send invitations… 会在您检查收件人列表后向现有用户批量发送邀请。完整详细信息请参阅应用邀请。
同步活动与故障排除
展开 Sync activity & troubleshooting，即可 "see why recent records did or did not sync." 您可以按姓名、ID 或原因搜索，并点击 Refresh 刷新列表。每个条目都有一个结果标记：
| 结果 | 含义 |
|---|---|
| Added | 创建了新的 Users 行 |
| Updated | 根据来源刷新了现有行 |
| Skipped | 记录未同步，条目会显示原因（见下文） |
| Disabled | 该人员已在来源中被移除，因此其访问权限已关闭 |
| Processed | 记录已处理，但没有可见的变更 |
| Stale snapshot | 较旧的 Access Time Window 修订被忽略，因此无法覆盖较新的状态 |
您可能会看到以下跳过原因：
| 跳过原因 | 解决方法 |
|---|---|
| Integration sync is turned off for this facility | 在此页面上启用来源开关 |
| This integration is turned off in sync settings | 在 "Sync from these integrations" 下启用该集成 |
| No phone or email on the record (a phone or email is required to log in) | 在来源系统中添加联系方式，或放宽 Require identifier |
| Record is decoupled and managed manually | 属于预期情况；如果希望恢复同步，请通过该用户的 Track source updates 开关重新关联 |
| No facility on the source record | 来源记录在来源系统中未与此设施关联 |
| No matching Users record | 该变更引用的人员在此处没有对应的行（例如在首次同步之前已被移除） |
| Unknown or unmapped scope key | 配置该集成的 scope_key 映射；受影响的时间窗口会以关闭方式失效 |
| Access Time Window source is stale | 恢复来源的成功传送，并检查所配置的新鲜度阈值；不要根据未经验证的获取结果进行清除 |
点击某个条目会打开 Sync activity detail，其中显示完整记录：姓名、外部 ID、来源、集成、原因以及用于向支持团队升级问题的 ID。
批量删除已同步的用户
要清除来自某个集成的用户（例如在断开该集成之后），请使用 Bulk delete synced users。在删除任何内容之前，您会先检查确切的列表。
- 在 Bulk delete synced users 下，点击 Bulk delete…
- 选择范围：All integration-synced users 或单个集成。点击 Preview。
- 检查：对话框会准确显示将移除多少用户（并附有示例列表）。请注意警告：This cannot be undone，并且这些行上的所有管理员自定义内容（授权、自定义标签、备注）都会丢失。这些用户的访问日志历史记录会保留。
- Also turn off syncing from this integration (recommended) 默认处于勾选状态；请保持勾选，否则下一次同步时会重新创建相同的用户（不含其原有的自定义内容）。
- 勾选 I understand this is permanent and customisations will be lost，然后点击 Delete N。
如果底层用户集在预览和确认之间发生了变化，系统会要求您重新运行预览，以确保您删除的正是您检查过的内容。