OpenProject Jira 迁移字段映射完全参考:从项目、工作包到用户与自定义字段
OpenProject Jira 迁移字段映射完全参考:从项目、工作包到用户与自定义字段
导读
本文是 OpenProject Jira Migrator(Jira Data Center 导入工具)的字段映射参考手册,系统梳理迁移过程中 Jira 数据如何一一对应到 OpenProject 的字段:哪些字段被迁移、哪些被明确丢弃、哪些以何种规则自动创建或去重。通过本文,你将掌握项目级字段、Issue → 工作包字段、用户与组、自定义字段四大类映射的全部规则,以及大小写不敏感匹配、变更历史分组、附件静默失败等关键行为陷阱,为制定迁移前的数据清洗方案和迁移后的核对清单提供直接依据。
说明:Jira Migrator 是 OpenProject 官方正在积极开发的导入工具,目前仅支持 Jira Data Center 10.x 与 11.x,不支持 Cloud 实例,仅建议在测试环境使用。本文映射规则对应仓库中 docs/installation-and-operations/jira-migration 目录下的 Field Mapping Reference,并与 Jira 迁移总览、自定义字段迁移 相互补充。
项目级字段映射
迁移每个项目时,Jira 的项目字段按以下规则转换:
| Jira 字段 | 迁移为 OpenProject | 你需要知道的事 |
|---|---|---|
| 旧/重命名后的项目 key | 项目标识符(Project identifier) | 如果 Jira 项目被重命名过,旧 key 在迁移后依然能解析到同一个项目 |
| 项目描述 | 项目描述 | — |
| 项目 key | 项目标识符 | — |
| 项目名称 | 项目名称 | — |
此外,每个被迁移的项目都会被创建为 私有(private)且激活(active),且没有父项目——这并非来源于 Jira 中的任何设置,而是迁移工具本身的创建方式。
Issue → 工作包字段映射
这是映射参考的核心部分。以下表格完整列出每个 Jira Issue 字段在 OpenProject 工作包中的去向。
| Jira 字段 | 迁移为 OpenProject | 你需要知道的事 |
|---|---|---|
| Affects Versions(影响版本) | 不迁移 | — |
| Assignee(经办人) | Assignee(负责人) | — |
| Attachments(附件) | Attachments(附件) | 重新上传到工作包,原作者信息尽可能保留 |
| Change history(变更历史:状态变化、字段编辑等) | Activity 条目 | 保留,但分组粒度比 Jira 原始历史更粗——见 迁移后检查清单 |
| Comments(评论) | Activity/notes | 作者与日期保留;文本从 Jira 标记转换 |
| Components(组件) | 不迁移 | —(规划中:JIM-107) |
| Creator(创建人) | Author(作者) | — |
| Description(描述) | Description(描述) | 从 Jira 标记转换为 OpenProject 标记——标题、粗体/斜体、链接、代码/引用块、表格均会转换。部分元素不转换:{info}/{warning}/{note}/{tip} 提示框、{toc}、以及 {expand}/{section}/{column} 布局完全无法识别——其内容会保留,但原始的 {macro} 标签文本会残留为可见、未转换的文本,既不会干净移除也不会被样式化。裸 issue key 链接(如 <a href="https://link.gitcode.com/i/1eb566411ae06c3c6408b1dcb743a925" target="_blank">PROJECT-123])和附件链接(如 [^file.pdf])也会保留为字面、不可点击的文本。见 [迁移前检查清单 与 迁移后检查清单 |
| Due date(截止日期) | Due date(截止日期) | — |
| Environment(环境) | 不迁移 | — |
| Fix Versions(修复版本) | 不迁移 | —(规划中:JIM-154) |
| Issue creation date(创建日期) | 工作包创建日期 | 设置为迁移运行时的日期,而非 Jira 中 issue 的原始日期(跟踪:JIM-189) |
| Issue id(内部 ID) | 不迁移 | Jira 内部 ID(规划中:JIM-8) |
Issue key(如 PROJECT-123) |
工作包标识符(Work package identifier) | 旧/重命名后的 issue key 在迁移后同样保持可用,与项目 key 的机制一致 |
| Issue links(阻塞、关联等) | 不迁移 | —(规划中:JIM-76) |
| Issue type(问题类型) | Type(类型) | 按名称匹配(不区分大小写);无匹配时自动创建新 Type,并挂接到正确的项目(镜像 Jira 按项目区分的 Issue Type Scheme)。只有名称被迁移。迁移的 Type 不会被标记为项目默认类型,即使它在 Jira 中就是默认值 |
| Logged work / time entries(已记录工时) | 不迁移 | 只有两个估算字段会迁移,实际记录的时间不会迁移(规划中:JIM-93) |
| Original time estimate(原始时间估算) | Estimated hours(估算工时) | — |
| Priority(优先级) | Priority(优先级) | 按名称匹配(不区分大小写);缺失时自动创建。如果 Jira 中 issue 没有优先级,则使用 OpenProject 的默认优先级。只有名称被迁移——Jira 的严重程度顺序、颜色和图标都不保留,这一点不仅影响外观:当 issue 未设置优先级时,OpenProject 会回退到列表中排在最前的那个优先级 |
| Remaining time estimate(剩余时间估算) | Remaining hours(剩余工时) | — |
| Reporter(报告人) | 不迁移 | Jira 的 "Reporter" 概念在 OpenProject 中不存在,被丢弃;只有 Creator 变为 Author |
| Resolution(解决结果) | 不迁移 | Jira 将 issue 关闭的原因(Fixed、Won't Fix、Duplicate、Cannot Reproduce)与其工作流状态(Status)分开跟踪。只有 Status 被迁移——关闭原因被完全丢弃,多个不同的 Jira 解决结果可能映射到同一个 OpenProject 状态且不留任何痕迹(规划为自定义字段:JIM-149;更广泛的原生支持跟踪于 FND-231) |
| Resolution date(解决日期) | 不迁移 | — |
| Security Level(安全级别) | 不迁移 | — |
| Status(状态) | Status(状态) | 按名称匹配(不区分大小写);缺失时自动创建。只有名称被迁移——迁移的状态永远不会被自动标记为 OpenProject 中的 "closed"(关闭),即使它在 Jira 中代表已结束状态(如 Done、Closed、Resolved)。这会影响任何依赖"哪些工作包实际已完成"的过滤和报表 |
| Sub-tasks / parent-child links(子任务/父子链接) | 不迁移 | —(规划中:JIM-75) |
| Summary(摘要) | Subject(主题) | — |
| Votes(投票) | 不迁移 | OpenProject 中不存在此概念(变通方案规划中:JIM-207) |
| Watchers(关注者) | 不迁移 | —(规划中:JIM-180) |
| Web link(Web 链接) | 不迁移 | OpenProject 中不存在此概念(变通方案规划中:JIM-206) |
用户与组映射
| Jira 字段 | 迁移为 OpenProject | 你需要知道的事 |
|---|---|---|
| Active flag(激活标志) | 账户状态 | 创建时锁定(locked);只有在你 批准导入 后才会自动解锁,且仅针对在 Jira 中处于激活状态的用户 |
| Display name(显示名) | First / last name(名/姓) | 自动拆分;单词名会同时用于名和姓 |
| Email(邮箱) | Email(邮箱) | 如果 Jira 用户没有邮箱,会生成一个占位邮箱以便账户仍能创建。不总是 Jira 值的 1:1 复制——见下文邮箱/用户名冲突处理 |
| Jira group membership(Jira 组成员关系) | OpenProject 组成员关系 | 按名称匹配或创建。注意:会拉取用户在 Jira 中的全部组列表,而不仅是与迁移项目相关的组 |
| Username(用户名) | Username(用户名) | 也不总是 1:1 复制——见下文邮箱/用户名冲突处理 |
| Password(密码) | 随机生成 | Jira 密码无法迁移,因此每个新用户之后都需要重置密码或发送邀请(规划中:JIM-116) |
自定义字段
自定义字段的迁移规则自成体系,包括字段类型映射、支持/不支持的字段类型及各种边界情况,完整内容请参阅 自定义字段迁移文档。其要点包括:迁移器会自动检测导入 issue 中实际使用的自定义字段并创建对应的 OpenProject 自定义字段;所有新建的自定义字段被放置在工作包表单配置的 "Jira import" 分组中,默认不分配到任何现有项目。
值得注意的行为细节
以下行为直接决定迁移结果是否符合预期,建议在迁移前逐条对照:
- 状态/类型/优先级匹配忽略大小写,但不忽略拼写。
"To Do"与"TO DO"会正确匹配到同一状态;但"To-Do"与"To Do"、或"Doing"与"In Progress"会各自创建独立的状态/类型/优先级。若希望它们合并,请在迁移前统一各 Jira 项目间的命名。 - 变更历史是分组而非 1:1 复制。 同一人在同一分钟内对同一字段的多次编辑会合并为一条 activity 条目(除非其中两条都触及描述)——因此 OpenProject 的 activity 标签页会比 Jira 原始历史更"粗粒度",且并非总以 OpenProject 的常规格式呈现字段变更详情。此外还有一个比分组更严重的已确认 bug:紧随 Jira "带评论的状态转换"之后的评论时间戳可能损坏,显示为迁移日期而非真实日期。跟踪于 JIM-152。
- 内联图片仍指向原 Jira 服务器。 嵌入在描述/评论中的图片不会被重新托管到 OpenProject——一旦 Jira 实例退役,这些图片就会失效,除非手动重新上传。跟踪于 JIM-53。
- 导入器没有 LDAP 概念。 每个新用户都被创建为普通的本地账户并配以随机密码——即使你的 OpenProject 使用 LDAP 登录,也不会关联到任何 LDAP 源。如果 Jira 用户名与真实 LDAP 登录名匹配,该用户真实的 LDAP 密码在迁移后将失效,因为新建的本地账户会"抢占"该登录名。每个受影响账户都需要手动修复——见 迁移前检查清单 与 迁移后检查清单。
- 附件是"一切失败都大声报错"的唯一例外。 在其他任何环节,导入过程中的问题都会抛出错误并中止整个运行。附件则不同:下载失败或上传被拒会被静默记录并跳过,导入继续执行并可能"成功完成"但缺失部分附件。审查/批准界面不会显示任何摘要或警告——如何检查见 迁移后检查清单。迁移后检查清单还给出了日志中的具体特征:服务器日志中会出现
Attachment creation failed for <filename>或Download attachment failed for <filename>字样,需要在批准前检索这些日志并核对对应工作包。 - 重复运行导入对用户是安全的——重试时已导入的用户不会被重复创建。用户账户本身不会重建,但组成员关系每次都会重新同步。
- 邮箱/用户名冲突是解决而非拒绝。 如果 Jira 用户的邮箱已存在于 OpenProject,导入器不会直接失败:若现有账户在同一次导入运行中尚未关联到其他 Jira 用户,则复用该账户;否则通过在邮箱后追加 Jira 用户 key 来消歧(如
email+JIRAKEY@domain.com),使两个账户共存。如果 Jira 用户名已存在于 OpenProject,则在用户名后追加 Jira 用户 key 消歧(如name+JIRAKEY)。 - 批准时的用户激活是有条件的,而非自动的。 每个导入的用户都以
locked状态创建,无论其在 Jira 中的状态如何。批准导入只会解锁同时满足以下条件的用户:(a) 由本次运行新建(而非复用了现有 OpenProject 账户),且 (b) 在 Jira 中标记为active。复用/匹配的账户保持原状。 - @提及通过实时 API 查询解析,而非仅依赖已知用户。 对描述或评论中出现的每个不同的
[~username]提及,导入器都会直接调用 Jira 的用户端点——即使该用户在其他任何地方都未被引用(例如从未担任经办人、作者或关注者)。若解析成功并完成导入,提及会渲染为真正的 OpenProject<mention>标签(可点击、触发通知);若无法解析,则回退为纯文本@username。 - 姓名拆分是朴素的。
firstname/lastname通过在 JiradisplayName的最后一个空白字符处拆分得到——并非真正的姓名解析逻辑。单词型显示名会被复制到两个字段。OpenProject 名称中不允许的字符会在拆分前被剔除。 - 工作包序列计数器在导入后按项目回填,设置为导入工作包中找到的最高序列号——纯粹是为了保证迁移后新建的工作包不会与已导入的标识符冲突。
源码视角:映射背后的实现佐证
字段映射参考文档描述的行为可以在仓库源码中得到印证,以下路径可供深入研读:
- Wiki 标记转换管线:描述、评论等文本的 Jira 标记 → Markdown 转换由 app/services/import/jira_wiki_markup_converter.rb 驱动,其核心逻辑是
JiraWikiMarkup::Parser解析 AST 后再由JiraWikiMarkup::Renderer渲染(见 app/services/import/jira_wiki_markup/ 下的 parser.rb、nodes.rb、renderer.rb)。这解释了文档中"标题、粗体/斜体、链接、代码/引用块、表格会转换,而部分{macro}不被识别"的现象——转换器只实现了已识别的节点类型。 - 变更历史与评论时间戳:活动条目的写入与时间戳处理位于 app/services/import/jira_import_journals.rb,其中
update_creation_entry等方法直接操作工作包 journals 的created_at、updated_at与validity_period,与文档描述的"变更历史分组、时间戳可能显示迁移日期"(JIM-152)的行为边界直接相关。 - 配置与连接模型:导入配置的持久化模型为 app/models/import/jira.rb,它校验 URL 必须为 http/https,并通过
Import::JiraClient(app/services/import/jira_client.rb)建立与 Jira 的 API 连接;围绕导入运行还衍生出 app/models/import/jira_import.rb、jira_import_state_machine.rb 以及导入各实体(项目、issue、状态、类型、优先级、用户等,见 app/models/import/ 目录)等模型,共同构成"审查 → 批准/回滚"状态机的基础。 - 导入服务层:app/services/import/jiras/ 下的 create_service.rb、set_attributes_service.rb、update_service.rb 负责导入配置的创建与更新,与文档"只有名称跨迁移、自动创建缺失的类型/状态/优先级"等按名匹配策略共同构成导入主流程。
迁移前与迁移后的闭环建议
字段映射参考中反复出现两个配套文档,构成完整的迁移闭环:
- 迁移前检查清单:重点解决"哪些数据会丢失、是否可接受",包括统一 Jira 各项目间的 Status / Type / Priority 命名(避免因拼写差异产生重复实体)、导出不会被迁移的数据(如日志工时、关注者、史诗链接、Story Points、子任务关系)等。
- 迁移后检查清单:覆盖批准前的抽样核对与附件日志检索、批准后的密码重置/LDAP 冲突修复、手动重建工作流/权限/看板/关联关系,以及"将迁移的状态手动标记为 closed、重排优先级、按项目设置默认类型"等清理动作。
由于导入器当前仍处于 beta 阶段且仅覆盖基础数据(项目、标识符、issue、基础自定义字段、用户、状态、类型),官方建议:先备份 OpenProject 实例、在测试环境用小数据子集验证映射与附件、确认无误后再执行完整迁移,并在批准前完成全部核对——因为一旦批准,回滚将不再可能(详见 Jira 迁移总览)。