Penstock

Guide / Share and move

从 Camunda 7 迁移到 Camunda 8

迁移助手会显示 Camunda 7 项目中哪些内容无法直接迁移到 Camunda 8,转换能转换的部分,并生成一份可以交给他人的报告。

Free 查看、计划和报告免费。转换、worker 骨架和等价性检查需要 Pro,在流水线中需要 Team。

目的与适用对象

Camunda 7 Community Edition 已经停止维护。使用它的团队必须决定是否迁移到 Camunda 8,然后付诸实施:流程图、决策、表单,以及它们背后的 Java 代码。迁移助手在您的工具中、在代码旁边,完成分析工作和大部分转换工作。

它适用于 Camunda 7、Operaton 和 CIB seven 项目。这两个分支都按 Camunda 7 源项目读取,因为它们的流程图使用相同的 camunda: 命名空间。

哪些免费,哪些属于 Pro

部分方案
分析:哪些内容无法直接迁移、原因、怎么做、由谁来做Free
迁移报告,Markdown 格式和单个 HTML 页面Free
转换流程图、决策或表单,带预览Pro,在流水线中需要 Team
根据您的 delegate 生成的 job worker 骨架Pro
迁移工作区和 penstock migrate plan:每项变更,附带类别和原因Free
只写入您接受的变更(migrate apply --write)Pro
penstock migrate verify:在两个引擎上运行相同的场景并进行比较Pro,在流水线中需要 Team。前 3 个场景免费。
penstock migrate agents:将 AI 智能体迁移到 8.10 模板预览免费,限前 3 个元素。--write:Pro

查看哪些内容无法直接迁移

  1. 打开一张 Camunda 7 流程图。
  2. 点击工具栏上的 Migrate to Camunda 8。对于 Camunda 7、Operaton 和 CIB seven 流程图,它默认固定在工具栏上,也可以取消固定,放回 More 菜单。
  3. 侧边栏的 Problems 标签页会打开并定位到 Migrate to Camunda 8 分组。它会显示例如 7 to do, 3 to check, 19 convert unchanged 这样的内容。再次点击 Migrate to Camunda 8 即可关闭。
  4. 阅读各个分组,每组都带有计数:Needs work(需要人工处理)、Review after converting(由 Penstock 转换,您来检查),以及默认折叠的 Convert unchanged(可以精确转换的内容)。如果流程图在其他分组中没有问题,标签页顶部仍会显示 No problems found.
  5. 点击某一行,画布上对应的元素会被选中。每一行都说明了问题是什么、原因以及处理方法。
一张 Camunda 7 流程图,已点击 Check 和 Migrate to Camunda 8。三个脚本任务以蓝色虚线标出。Problems 标签页显示 No problems found,并包含 Migrate to Camunda 8 分组、一个 Convert 按钮、3 to do、7 convert unchanged,以及三条检查结果 The groovy script cannot run in Camunda 8
Problems 标签页中的迁移分组:右侧是 Convert 按钮,下方是计数,再下方是检查结果。需要处理的任务在画布上被标出。

该分组只针对一张流程图。对于整个项目(一次处理所有文件),Penstock 会列出每个文件的状态(ready、converts、needs work、blocked)和检查结果,以及 Java 代码中每个类将变成什么。

迁移整个项目

JetBrains

打开 Penstock 工具窗口,找到 Migrate to Camunda 8。它列出每个文件的状态和检查结果,以及 Java 代码中每个类将变成什么。右键点击一个文件并选择 Convert to Camunda 8…,或者在根节点上使用 Convert All…。

VS Code

不可用于 VS Code. VS Code 暂不支持 Camunda 7 到 Camunda 8 的转换,也没有显示它的项目列表。请在命令行中使用 penstock migrate。

Command line

$ penstock migrate .
ready       src/main/resources/approve-order.form  1 convert
needs work  src/main/resources/order-process.bpmn  1 to do, 8 convert
        error   migration/message-catch: Shipment confirmed: The message shipment-confirmed needs a correlation key. ...
        error   migration/delegate-expression: Send receipt: Delegate ${sendReceipt} becomes the job type sendReceipt. ...
ready       src/main/resources/shipping-method.dmn  1 convert

3 files to migrate for Camunda 8.8: 2 ready, 0 convert, 1 need work, 0 blocked.
Job workers to write: 2
  • migrate、migrate analyze:列出无法直接迁移的内容。有错误时,或使用 --fail-on warning 且有警告时,退出码为 1。免费。
  • migrate convert:转换文件。它会把 Camunda 8 文件写入所给文件夹旁边的 camunda-8 文件夹,或写入 --out <dir>,原始文件保持不变。请先使用 --dry-run。属于 Pro,在流水线中需要 Team。
  • migrate report:生成报告。免费。
  • --target 8.5 到 8.9、--format text|json|sarif|github、--baseline、--update-baseline、--verbose。

转换后的文件夹会带有它自己的 penstock.yaml,其中写明 engine: camunda-8,Camunda 7 文件的 penstock.yaml 不会被改动。参见所有命令。

术语含义

文件状态含义
Ready无需任何处理。
Converts由 Penstock 转换,剩余部分需要检查。
Needs work其中一部分需要人工处理。
Blocked它用到了 Camunda 8 中没有对应形式的内容。
检查结果的标记含义
ConvertsPenstock 会精确转换它。
To check由 Penstock 转换,再由人工检查结果。转换后该检查结果仍会保留。
To doPenstock 不做处理,只在对应元素上做标记,由人工完成。

在流水线中

分析无需编辑器即可运行,因此当项目中仍有 Camunda 7 流程图时,可以用它作为流水线的关卡。

选项作用
--target <version>用于检查的 Camunda 8 目标版本,默认为 8.8。
--format text|json|sarif|github以表格、JSON(包含工作量统计和阻塞项)、SARIF 或变更行上的注解形式输出检查结果。SARIF 和注解属于 Pro,在流水线中需要 Team。
--fail-on error|warning决定哪些情况使退出码为 1。错误总是会;使用 warning 时,警告也会。
--baseline、--update-baseline只在出现自上次 --update-baseline 以来新增的问题时失败,该选项会在项目根目录写入 penstock-migration-baseline.json。属于 Pro,在流水线中需要 Team。
--verbose同时列出说明性条目,即只会原样迁移的内容。

检查哪些内容

迁移工作区

工作区列出转换到 Camunda 8 时会进行的每一项变更,按文件列出,BPMN 还会按元素列出。每项变更都显示当前内容、转换后的内容、类别和原因,并配有复选框、实时计数和工作量估算。

自动转换结果含义不变。
转换后含义有变化Penstock 会转换它;由您判断新的含义是否正确。
需要人工处理无法精确转换。
保持原样原样迁移,不做改动。

在 Penstock Web 中,它位于命令面板里。

各工具中迁移工作区的位置

JetBrains

迁移工作区位于 Penstock 工具窗口和 Tools 菜单中。

VS Code

使用 Migration workspace 命令。

Command line

penstock migrate plan 列出各项变更及其 id,penstock migrate apply --only 应用所选的变更。参见 migrate。

Apply selected 只以原子方式写入已接受的变更。和以前一样,它会拒绝已被修改的文件和符号链接。被拒绝的元素会逐字节保持原样。只有当您选择 Save selection 时,所选内容才会保存在 .penstock/migration-selection.json 中。

penstock migrate plan --format json src/orders
penstock migrate plan --only ID1,ID2 --save-selection
penstock migrate apply --saved --write
penstock migrate apply --only ID1,ID2 --exclude ID3 --write

migrate plan 列出各项变更的 id,不写入任何内容,除非您使用 --save-selection 要求保存所选内容。migrate apply 接受 --only、--exclude 和 --saved。计划中不存在的 id、空列表或过长的 id 会在写入任何内容之前被拒绝。migrate_apply MCP 工具接受 only 和 exclude。

转换

Pro

  1. 在 Problems 标签页的 Migrate to Camunda 8 分组中,点击 Convert。您的工具也可以转换单个文件或项目中的所有文件。
  2. 流程图会在可视化流程图差异对比中左右并排打开两次:转换前和转换后,各自居中显示在自己的窗格中,共用一个标题。预览还会显示 Camunda 8 文件将要写入的文件夹,即被转换文件夹旁边的 camunda-8,您可以在预览中修改它,也可以用 --out 指定。此时还不会写入任何内容。
  3. 阅读变更内容,然后点击 Convert。Camunda 7 文件保持不变,新文件会带有它们自己的 penstock.yaml,其中写明 engine: camunda-8。
  4. 如果目标文件夹中已有转换过的文件,也不会卡住:预览会提供 Replace the files in <folder> 选项,当该文件夹不在版本控制之下时会给出警告,只有在您勾选后才会覆盖这些文件。

Penstock 无法精确转换的内容会保留在文件中,并在对应元素上用 conversion:message 标记,Camunda Modeler 也能读取这个标记。它同时仍作为一条检查结果保留。重复转换不会再产生任何变化。

Job worker 骨架

Pro

每个 Java delegate、external task handler 或监听器都会被追溯到其源代码,并给出文件、行号以及它将变成什么。Penstock 可以在代码旁边生成一个骨架:Spring job worker、Node worker 或 Python worker。骨架根据代码读取和写入的变量以及它抛出的 BPMN 错误生成。Penstock 绝不会覆盖已有文件。

在您的工具中生成骨架

JetBrains

在工具窗口中依次打开 Migrate to Camunda 8 和 Code。右键点击一项并选择 Job Worker Skeleton…(Spring)、Node Worker Skeleton… 或 Python Worker Skeleton…。属于 Pro。

VS Code

不可用于 VS Code. Job worker 骨架只能在 JetBrains IDE 中生成,VS Code 暂不支持。penstock migrate 会打印需要编写的 job worker 数量。

Command line

不可用于 Command line. 骨架只能在 IDE 中生成。penstock migrate 会打印需要编写的 job worker 数量。

报告

报告包括 Markdown 格式和一个自包含的 HTML 页面。

在您的工具中生成报告

JetBrains

在工具窗口中 Migrate to Camunda 8 的根节点上点击 Migration Report。

VS Code

在 Penstock 视图中 Migrate to Camunda 8 的根节点上点击 Migration Report。

Command line

$ penstock migrate report .
wrote migration-report.md
wrote migration-report.html

使用 --out <dir> 选择输出文件夹。

HTML 是一个面向管理者的自包含页面:范围、迁移的成本(需要编写的 job worker、需要改写的表达式、需要替换的脚本、需要迁移的监听器、需要重建的表单、调用的流程、决策)、各文件及其状态,以及代码。

检查转换后的流程行为是否一致

Pro 前 3 个场景免费。

penstock migrate verify --original-profile c7-test --converted-profile c8-test src/orders

它在一个测试引擎上用原始的 Camunda 7 流程图(或 Operaton、CIB seven)运行项目中保存的场景,在另一个测试引擎上用转换后的 Camunda 8 流程图运行同样的场景。对每个场景,它会报告:

它会通过转换生成的 id 映射比较元素路径,并比较最终状态、incident,以及变量的名称和值。所有场景都等价时退出码为 0,至少有一个不同时为 1,有内容无法比较或因被拒绝而没有运行任何内容时为 2。

两个引擎都必须标记为 deployment.forTests。不会在共享引擎或生产引擎上运行任何内容。如果转换添加了可执行内容,运行会被拒绝,直到您用 --run-unreviewed 或工作区中的按钮确认为止,该按钮会列出添加了哪些内容。密钥的值绝不会出现在结果中。工作区会在每个结果旁边显示它涉及的变更,并带有一个汇总横幅。migrate_verify MCP 工具为智能体提供同样的功能。

AI 智能体

penstock migrate agents [paths] 会按照新模板中声明的迁移规则,把 AI 智能体元素从 8.9 及更早的模板版本迁移到 8.10 的智能体任务模板和智能体子流程模板。默认只做演练(dry run)。无法证明映射正确的元素会保持不变,并与原因一起列出。预览中的前 3 个元素免费;--write 以原子方式替换文件,属于 Pro。migrate_agents MCP 工具提供同样的功能。参见 Camunda 8 的 AI 智能体。

它不做什么

常见问题

没有 Migrate to Camunda 8 按钮。
它只对 Camunda 7、Operaton 和 CIB seven 流程图显示。Camunda 8 或 Classic BPMN 流程图没有这个按钮。该分组会显示 Nothing to convert: this is not a Camunda 7 diagram.
点击 Convert 时提示我购买 Pro。
转换是 Pro 功能。分析和报告免费。参见方案与许可证。
转换后,检查仍然列出了一些结果。
这些是需要人工处理或检查的内容。在您修复之前,它们会一直留在对应元素上。
“Unknown target”。
请使用 8.5、8.6、8.7、8.8 或 8.9。
“There is nothing to migrate”。
在您指定的路径中没有找到 Camunda 7 流程图、决策或表单。