使用文档
使用 Jira 自动化操作 RowCraft 表格
在 Jira 自动化规则中使用 RowCraft 动作,可以在规则运行时操作表格字段或面板表格。例如,创建工作项时添加费用明细、更新匹配的清单行,或先读取表格供后续步骤使用。
选择动作
在 Jira 自动化规则中添加动作,在其他应用中搜索 RowCraft。动作名称始终显示为英文;动作的设置界面跟随编辑规则者的语言。

| 动作 | 作用 |
|---|---|
| RowCraft - Add table rows | 在表格末尾追加一行或多行。 |
| RowCraft - Update table rows | 修改匹配行中的指定列。 |
| RowCraft - Delete table rows | 删除匹配的行。 |
| RowCraft - Replace table rows | 用提供的行替换整张表格;空列表会清空表格。 |
| RowCraft - Read table | 只读取表格,将结果提供给后续步骤。 |

首次添加 RowCraft 动作时,Jira 自动化会要求你选择 连接。每个动作都需要选择 表格 和 工作项:默认的 {{issue.key}} 是当前规则运行的工作项;也可以填写其他工作项键或 {{issue.parent.key}} 等智能值。
新增或修改行
- 选择表格字段或面板表格,以及要操作的工作项。
- 修改或删除时,选择要操作的行:满足所有条件的行、行号 或 所有行。
- 填写一行时,选择 一行,每列一个输入框,输入固定值或 Jira 智能值。公式列和行号列由 RowCraft 计算,不提供输入框。
- 新增或替换多行时,选择 JSON(多行)。使用 插入示例 获取当前表格的示例;JSON 的键是列名。JSON 中可能包含引号或换行的智能值应加
.jsonEncode,例如{{issue.summary.jsonEncode}}。 - 完成动作配置、保存规则,并在工作项上测试。修改已保存规则中的动作时,需要先选择动作设置底部的 下一步,再保存规则。
留空的输入框在不同动作中含义不同:
- 新增 和 替换:留空的列使用该列“新行的默认值”。
- 修改:留空表示不改变该单元格。要清空单元格,请使用 JSON 并写
null。
用“每列一个输入框”执行 替换 时,表格会只剩这一行;如果所有输入框都留空,表格会被清空。
例如,向包含 Item、Category 和 Qty 列的表格添加两行,可以使用下面的 JSON;请替换为你自己的列名和有效值:
[
{ "Item": "Laptop stand", "Category": "Office supplies", "Qty": 2 },
{ "Item": "USB-C cable", "Category": "Hardware", "Qty": 4 }
]
选择要修改或删除的行
- 满足所有条件的行:最多三个“列 = 值”条件。文本比较不区分大小写,并忽略首尾空格。公式列可以作为条件;要按位置选择,请改用 行号。
- 行号:1 是第一行,-1 是最后一行,-2 是倒数第二行。超出表格行数的行号视为没有匹配行。
- 所有行:表格中的每一行。
修改 会把同一组新值写入每个匹配行。使用 JSON 时,修改动作只接受一个包含要修改单元格的对象,不接受列表。
只有 修改 动作有 没有符合条件的行时 设置:
| 选项 | 结果 |
|---|---|
| 不做任何事,继续运行(默认) | 规则继续运行,不做任何修改。 |
| 报错并停止规则 | 规则停止,审计日志中写明未匹配的条件。 |
| 新增一行(含条件中的值和新的值) | 新增一行,填入条件中的值和新的值。 |
删除 时没有匹配行,动作成功结束、不做修改,changedRows 为 0。
值的格式
| 列类型 | 值 |
|---|---|
| 数字 | 数字,例如 1200.50 |
| 日期 | 2026-12-31,或 {{now.jiraDate}} 这类智能值 |
| 复选框 | true 或 false;也接受 yes/no、1/0、是/否、x 和 ✓。留空表示未勾选。 |
| 下拉单选 | 选项名称。来自 Jira 字段的选项也可以填写选项 ID。 |
| 下拉多选 | 用逗号分隔的多个选项名称;JSON 中也可以用数组 |
| 人员 | 账号 ID({{initiator.accountId}})、邮箱或全名。一个名字匹配到多人时,动作会停止并要求改用账号 ID 或邮箱。 |
| 工作项 | 工作项键,例如 {{issue.key}},或工作项链接 |
列名匹配不区分大小写。人员以规则的连接用户身份查找,只能找到该用户能看到的人。RowCraft 会按列设置和目标工作项检查每个值。一个动作最多提供 1,000 行;表格自身的最大行数限制仍然有效。
在后续步骤中使用结果
Read table 提供 rowCount、rowsJson 和 totalsJson。写入动作提供 rowCount(保存后的行数)和 changedRows(新增、修改或删除的行数;替换 时为替换后的行数)。
rowsJson包含所有行,以列名为键,另有一个#键表示行号。数字保持为数字;其他单元格是表格中显示的文本,空单元格为null。totalsJson只包含设置了合计的列。
智能值前缀由 Jira 自动化生成,例如 Read table 的 {{fetchedRowcraftTable.rowCount}};请以智能值面板中显示的名称为准。后续步骤需要访问 JSON 中的值时,可以使用 Jira 的 jsonStringToObject()。
权限与排查
- 动作以规则的 连接用户 身份运行。该用户必须能浏览工作项;修改时还要有编辑权限。表格规则、必填、锁定和列权限按该用户亲自编辑时的方式生效。表格字段还需要位于该工作项的编辑界面上。
- 表格字段的修改会以连接用户的名义记入工作项历史;面板表格的修改记入表格历史。
- 表格必须适用于工作项的项目和工作类型。如果字段有多个上下文,设置界面会列出所有上下文的列,但只能写入工作项自身上下文中的列。
- 动作需要有效的 RowCraft 许可。失败时,规则审计日志会用连接用户的语言写明原因,例如列不存在或值无效。
- 动作保存后,RowCraft 会重新计算公式、合计、搜索数据和写入 Jira 字段的合计。如果同时有人编辑同一张表格,动作会重新读取并重试,最多三次;仍然冲突时,审计日志提示“动作运行期间表格一直在变化,请重新运行规则”。