本文详解 cameo report wizard 中自定义工具（custom tool）的正确安装流程及关键配置要点，重点解决工具成功加载却无法在 vtl 模板中导入的常见问题，明确指出环境配置缺失是根本原因。
本文详解 cameo report wizard 中自定义工具（custom tool）的正确安装流程及关键配置要点，重点解决工具成功加载却无法在 vtl 模板中导入的常见问题，明确指出环境配置缺失是根本原因。
在使用 MagicDraw 或 Cameo Systems Modeler 的 Report Wizard 功能扩展报表能力时，开发并集成自定义 Java 工具（如 MyCustomTool）是一项高频需求。尽管官方文档《Installing custom tool》和《Importing custom tool to template》步骤清晰，但实践中常出现“工具 JAR 成功部署至 plugins/reportwizard/tools/ 目录，Cameo 启动后识别到类、日志无报错，却在 VTL 模板中 #importTool("com.example.MyCustomTool") 失败”的情况——这并非代码或路径错误，而是
环境配置未就绪所致
。
✅ 正确实施流程（四步闭环）
编译与打包
确保自定义工具类继承 com.nomagic.magicdraw.reportwizard.tool.Tool，并正确声明包路径（如 package com.example;）。使用 Maven 或手动编译生成标准 JAR，验证内容：
部署位置
将 JAR 文件放入 Cameo 安装目录下的指定插件路径：
CAMEO_HOME/plugins/reportwizard/tools/
⚠️ 注意：不是 lib/、plugins/ 根目录，也不是 reportwizard/ 下其他子目录。
核心：启用 Report Wizard 插件（关键配置！）
这是文档未显式强调、但实际必需的前置步骤
：
启动 Cameo → Help → Plugins...
在插件列表中勾选
Report Wizard
（确保状态为
Enabled
）
若未启用，即使工具 JAR 存在，Report Wizard 的类加载器不会初始化，导致 VTL 中 #importTool() 无法解析任何自定义类。
重启 Cameo 生效。
VTL 模板中调用
在 .vtl 模板文件中，使用全限定类名导入并实例化：
? 排查清单（快速定位问题）
检查项正确做法常见误操作✅ 插件状态Report Wizard 插件必须启用仅启用 Modeling 或 SysML 插件，忽略 Report Wizard✅ 类路径JAR 内 .class 文件路径严格匹配 import 字符串包名拼写错误（如 com.exmaple）、大小写不一致✅ 构造函数工具类必须有 public 无参构造函数添加了带参构造且未保留无参构造✅ 权限与签名JAR 无需签名；若使用 JDK 17+，避免 --illegal-access=deny 干扰在 vmoptions 中误加限制性 JVM 参数
? 总结
Cameo Report Wizard 自定义工具的“加载成功但导入失败”，90% 以上源于
Report Wizard 插件未启用
这一隐性依赖。官方文档聚焦于代码与路径，但忽略了插件生态的激活前提。务必养成习惯：每次部署新工具前，首先进入 Help > Plugins 确认 Report Wizard 处于 Enabled 状态。完成此步后，再检查 JAR 结构、包名一致性与 VTL 语法，即可实现稳定集成。
jar -tf mytool-1.0.jar
# 输出应包含：com/example/MyCustomTool.class## 导入工具（必须在 #foreach 或 #if 前执行）
#importTool("com.example.MyCustomTool")
## 创建实例（注意：需提供无参构造或符合 Report Wizard 工具规范的构造）
#set($myTool = $toolFactory.createTool("com.example.MyCustomTool"))
## 调用方法（假设工具提供 getFormattedValue()）
$myTool.getFormattedValue($element)