#禅道集成

禅道集成仅适用于国内版 HiFox。它可以将禅道产品线或项目中的工作导入到 HiFox Space，并可按需配置后续同步。Sharkly 不提供禅道集成。

禅道仍可以作为团队已有的任务来源；导入后，团队可以在 HiFox 中组织、指派、执行和验收这些工作。

#禅道导入与禅道同步的区别

导入时也可以选择在导入完成后开启后续同步。该选项只有在对应禅道连接和回调都已配置完成时才可用。

#连接前的准备

开始前，请确认：

• 你是 HiFox 组织的 owner 或 admin，能够管理外部应用集成；
• 用于连接的禅道账号可以访问要导入或同步的产品线、项目及其中的工作；
• 已确定接收数据的 HiFox Space，并确认相关成员可在该 Space 中处理任务；
• 禅道地址可从执行导入的环境访问；
• 如果要启用后续同步，禅道管理员可以按照页面提供的指引配置回调。

连接禅道并不会自动给 HiFox 成员增加禅道权限，也不会给禅道账号增加 HiFox Space 的访问权限。两边的权限仍需分别满足。

#从外部应用集成打开禅道

在组织设置中打开外部应用集成，选择禅道。页面名称或具体入口可能随产品界面调整，以线上显示为准。

在禅道页面中可以：

• 连接或更新禅道实例；
• 检查连接状态并刷新可用的产品线、项目；
• 创建或管理产品线 / 项目与 HiFox Space 的同步链接；
• 打开导入向导和查看导入记录；
• 按页面指引配置禅道回调。

#导入禅道数据

导入向导会依次引导你完成连接信息、范围检查、工作选择、状态和成员映射、导入选项以及确认导入。

#1. 选择来源和目标 Space

在导入向导中填写禅道地址、账号和密码。系统读取连接后，会列出你可访问的禅道产品线和项目。

选择一项来源，并选择接收数据的 HiFox Space。产品线通常会包含与其相关的工作；项目适合只迁移某一交付范围。选择前请确认来源和目标 Space，避免把数据导入错误的团队范围。

#2. 检查导入预览

系统会先验证连接并显示预览，不会在这一步创建 HiFox 数据。

预览会帮助你了解将要导入的工作数量，以及相关项目、迭代、工作类型、进行中和已完成工作等范围。请先确认数量和来源符合预期，再继续下一步。

#3. 选择工作范围

你可以选择导入：

• 进行中的工作；
• 已完成的工作；
• 两者都导入。

如果这是第一次导入，建议先用较小范围验证结果。历史数据量较大时，可先导入正在进行的工作，再根据团队需要补充已完成记录。

#4. 映射状态

禅道中的需求、任务和缺陷可能使用不同的状态字典。导入向导会列出识别到的状态，并提供建议映射。

对每个来源状态，你可以：

• 映射到已有的 HiFox 任务状态；
• 创建一个新的 HiFox 任务状态；
• 调整状态在工作流中的顺序。

状态映射会影响导入后任务在列表、看板和后续同步中的表现。开始导入前，请确认同名状态在两边代表的实际流程一致。

#5. 映射成员

成员映射是可选的。你可以把可识别的禅道成员映射到现有的 HiFox 成员，或跳过不需要导入的成员。

默认跳过成员映射更稳妥：它不会因为一次历史导入而改变组织成员。需要保留负责人等信息时，再针对性地完成映射。

#6. 选择导入选项

确认导入前，按页面提供的选项决定本次导入方式。常见选项包括：

• 导入后保持同步：在连接和回调均已就绪时，开启后续同步；
• 导入迭代：当预览中包含可导入的迭代时，决定是否一并导入；
• 添加 Migrated 标签：便于在导入后筛选和检查本次结果；
• 覆盖导入：仅用于再次导入同一来源时，用来源数据刷新可更新的已导入内容。

导入会保留可支持的工作上下文，例如任务内容、评论和附件。不同禅道版本、产品配置和字段类型的支持范围可能不同，以向导预览和页面提示为准。

#7. 确认、跟踪进度和检查结果

确认页会汇总本次将导入和跳过的工作、成员、项目、任务类型和状态。确认无误后开始导入。

导入期间，可以在进度页查看完成、跳过和失败的项目，并可根据页面提供的操作取消正在进行的导入。导入完成后：

1. 打开目标 Space 检查任务数量、状态和处理人；
2. 使用 Migrated 标签筛选本次导入的任务（如本次保留了该标签）；
3. 查看进度页或导入记录中的失败说明；
4. 修正权限、连接、映射或来源范围后，再按页面提示继续处理。

取消导入不会自动替你判断哪些已创建数据应保留或清理。请先检查实际导入结果，再决定下一步操作。

#配置禅道同步

禅道同步由连接、同步链接和回调三部分组成。仅保存连接信息不足以接收禅道后续变更。

#1. 连接禅道实例

在禅道集成页添加连接，填写页面要求的禅道地址和账号信息。连接成功后，可以检查连接状态、更新凭据或刷新可用来源。

建议使用权限与用途匹配的账号。连接账号需要能读取目标产品线或项目；如需将 HiFox 的兼容变更写回禅道，还应具备相应的创建或编辑权限。

#2. 创建同步链接

在禅道集成页创建同步链接，选择：

• 已连接的禅道实例；
• 一个禅道产品线或项目；
• 一个目标 HiFox Space；
• 同步方向。

可根据团队协作方式选择让禅道变更进入 HiFox，或启用双向同步。双向同步适合同时在两边持续协作的团队；如果禅道仍是唯一的修改入口，先使用禅道到 HiFox 的方向通常更稳妥。

选择错误的产品线、项目或 Space 时，请按页面操作调整或重新建立链接，不要依赖后续导入来修正同步关系。

#3. 按页面指引配置回调

创建连接后，在禅道集成页面打开回调配置。页面会针对当前连接提供需要填写的回调地址和配置步骤。

请在禅道设置中严格按页面指引完成配置，并使用一个测试变更确认回调已送达。不要把页面中的回调地址或连接信息复制到公开文档、截图或不受信任的渠道。

连接和回调页面会显示当前状态，例如连接是否正常、回调是否已配置，以及是否正在等待或未能处理回调。出现提示时，先根据页面说明检查连接、权限和回调设置，再继续操作。

#查看同步状态与处理问题

已建立同步关系的任务会在任务详情和禅道集成页面显示相关状态或提示。常见处理方式如下：

• 连接或权限提示：更新连接账号信息，并确认账号仍可访问和编辑目标来源；
• 回调未到达或处理异常：按回调配置页重新检查禅道设置，并用测试变更验证；
• 状态或成员不同步：检查来源状态与 HiFox 状态的映射，以及相关成员是否已正确映射；
• 可重试的同步失败：先按页面提示解决原因，再重新触发同步；
• 写回限制说明：某些禅道对象或字段当前无法写回时，任务详情会明确说明这一限制。这不是通过反复重试就能解决的同步失败，应根据限制调整操作或继续在禅道中处理该项变更。

不要根据旧截图、内部错误码或非正式对照表猜测问题原因。以当前页面显示的状态和操作指引为准；仍无法解决时，保留相关任务和时间信息后联系支持。

#权限边界

通常情况下：

• 组织 owner 和 admin 可以连接禅道、更新凭据、配置回调，以及创建、修改或删除同步链接；
• 禅道账号的访问范围决定可读取和写入哪些产品线、项目及工作；
• HiFox Space 的成员和权限决定谁能查看或处理导入后的任务；
• 禅道连接信息仅用于集成功能，页面不会把可直接使用的敏感凭据展示给其他成员。

开始双向同步前，建议先用小范围来源验证状态、成员和写回边界，再扩大到更多产品线或项目。

#常见问题

#导入后还能开启同步吗？

可以。在禅道集成页完成连接、同步链接和回调配置后，再按页面指引为相应来源开启同步。也可以在导入向导中，在配置已就绪时选择「导入后保持同步」。

#为什么看不到产品线或项目？

先检查连接账号是否有访问该来源的权限，再在禅道集成页刷新来源列表。若仍不可见，请确认填写的是正确的禅道地址和账号。

#为什么不能直接重试写回？

页面若说明某个对象或字段目前不支持写回，重试不会改变该限制。请在禅道中完成相应操作，或按页面说明调整同步方式；只有提示明确为可重试的错误时，才应在修正原因后重试。

#删除同步链接会删除已有任务吗？

删除同步链接会停止后续同步，不会自动删除已导入或已同步到 HiFox 的任务。处理前请先确认团队是否仍需要保留这些历史记录。