使用JRJC通过REST API设置Jira自定义字段：配置、权限与错误排查

1. 理解JRJC与Jira自定义字段设置

在使用jrjc（jira rest java client）通过rest api创建jira issue时，经常需要为issue设置自定义字段的值。jrjc提供了一套简洁的api来构建issueinput对象，其中包含设置自定义字段的方法。

1.1 JRJC创建Issue的基本流程

通常，创建Issue的流程涉及构建一个IssueInputBuilder对象，指定项目键、Issue类型、概要和描述等基本信息。

Long testIssueTypeId = getTestIssueTypeId(projectKey);

IssueInputBuilder builder = new IssueInputBuilder()
    .setProjectKey(projectKey)
    .setIssueTypeId(testIssueTypeId)
    .setSummary(summary)
    .setDescription(description);

// ... 在此处设置自定义字段 ...

IssueInput input = builder.build();

return jira.getIssueClient().createIssue(input).claim();

1.2 设置自定义字段的方法

IssueInputBuilder提供了setFieldValue(String fieldId, Object value)方法来设置自定义字段。这里的fieldId可以是自定义字段的名称或其内部ID（通常格式为customfield_XXXXX）。value则根据自定义字段的类型而异，例如，对于单选/多选下拉列表类型的自定义字段，其值通常是CustomFieldOption对象。

例如，对于一个名为“Application”的自定义字段，其JSON表示可能如下：

{
  "self": "https://jira.web.labs.att.com/rest/api/2/customFieldOption/14314",
  "value":"NA:12345",
  "id": "14314",
  "disabled": false
}

在JRJC中，我们可以尝试使用CustomFieldOption来设置此类字段：

// 尝试设置名为“Test Type”的自定义字段
builder.setFieldValue("Test Type",
   new CustomFieldOption(14314L, null, "Functional", null, null));

这里的14314L是自定义选项的ID，"Functional"是其显示值。

2. 错误分析：'Field cannot be set'

当尝试通过JRJC设置自定义字段时，可能会遇到以下错误：

RestClientException{statusCode=Optional.of(400), errorCollections=[ErrorCollection{status=400, errors={Test Type=Field 'Test Type' cannot be set. It is not on the appropriate screen, or unknown.}, errorMessages=[]}]}

这个错误信息Field 'Test Type' cannot be set. It is not on the appropriate screen, or unknown.明确指出了问题所在。它通常由以下两个主要原因导致：

1. 自定义字段未配置在相应的屏幕上： 在Jira中，Issue的创建、编辑和查看操作都关联到特定的屏幕（Screen）。如果自定义字段没有被添加到用于创建或编辑该Issue类型的屏幕上，即使代码尝试设置其值，Jira也会拒绝该操作，因为它认为该字段在该上下文中不可用。
2. 用户缺乏必要的权限： 执行REST API调用的用户（或JRJC使用的凭据对应的用户）可能没有在该项目中创建或编辑Issue的权限，或者没有修改该特定自定义字段的权限。

这两个原因中，第一个是更常见的问题。Jira的字段可见性和可编辑性是严格受屏幕配置和权限方案控制的。

通义视频

通义万相AI视频生成工具

70

查看详情

3. 解决方案与最佳实践

要解决“字段无法设置”的问题，需要从Jira的管理配置层面进行排查和调整。

3.1 Jira屏幕配置检查与调整

这是最常见的解决方案。你需要确保自定义字段“Test Type”已添加到对应Issue类型的“创建Issue屏幕”和/或“编辑Issue屏幕”上。

1. 确定Issue类型和项目： 找出你正在尝试创建的Issue所属的项目和Issue类型。
2. 查找屏幕方案：
   • 导航到Jira管理界面 -> 项目。
   • 选择你的项目，然后点击“屏幕”或“操作”菜单下的“屏幕方案”。
   • 找到与你的Issue类型关联的屏幕方案。
3. 检查屏幕配置：
   • 点击屏幕方案旁边的“配置”链接。
   • 找到“创建Issue屏幕”和“编辑Issue屏幕”（如果存在）。
   • 点击对应的屏幕名称，进入屏幕配置页面。
   • 在该页面，检查“Test Type”自定义字段是否已列出。如果未列出，你需要将其添加到屏幕中。
4. 添加字段到屏幕：
   • 在屏幕配置页面，找到底部的“选择字段以添加至屏幕”下拉菜单。
   • 选择“Test Type”字段，然后点击“添加”。
   • 确保字段被添加到屏幕后，保存更改。

注意事项：

• 如果你的Jira实例使用了工作流，某些字段的可见性和可编辑性也可能受到工作流属性的限制。在这种情况下，你可能还需要检查相关工作流的配置。
• 自定义字段在不同Issue类型或不同操作（创建/编辑/查看）下可能使用不同的屏幕。务必检查与你当前操作（创建Issue）和Issue类型相匹配的屏幕。

3.2 权限管理检查

如果屏幕配置正确，那么问题可能出在权限上。

1. 检查项目权限：
   • 导航到Jira管理界面 -> 项目。
   • 选择你的项目，然后点击“权限”或“权限方案”。
   • 检查用于执行API调用的用户（或用户组/角色）是否具有“创建Issue”和“编辑Issue”的权限。
2. 检查字段权限：
   • 虽然不常见，但Jira允许为特定字段设置字段安全方案。
   • 导航到Jira管理界面 -> 问题 -> 字段配置方案。
   • 找到与你的项目关联的字段配置方案，并检查“Test Type”字段是否有额外的权限限制。

3.3 JRJC代码层面的注意事项

一旦Jira配置正确，你的JRJC代码将能够成功设置自定义字段。

• 字段ID或名称的准确性： 确保setFieldValue中使用的字段标识（"Test Type"或"customfield_XXXXX"）与Jira中的实际字段匹配。推荐使用customfield_XXXXX形式的ID，因为它更稳定，不受字段名称变更的影响。你可以通过Jira REST API的/rest/api/2/field端点获取所有字段的详细信息，包括它们的ID。
• 值的类型匹配： 确保传递给setFieldValue的值的类型与Jira中自定义字段的预期类型匹配。对于下拉列表，CustomFieldOption是正确的选择。CustomFieldOption的构造函数通常需要选项的ID，以及可选的显示值。

  // 假设“Test Type”是一个单选下拉字段，且选项“Functional”的ID是14314
  builder.setFieldValue("customfield_10001", // 假设Test Type的实际ID是customfield_10001
     new CustomFieldOption(14314L, null, "Functional", null, null));

  登录后复制

4. 总结

通过JRJC使用REST API设置Jira自定义字段时，遇到的“字段无法设置”错误并非代码逻辑错误，而是Jira实例配置问题。核心在于确保自定义字段已正确地配置在相应Issue类型的“创建/编辑”屏幕上，并且执行API操作的用户拥有足够的权限。开发者在排查此类问题时，应优先检查Jira的管理界面，确认屏幕方案、屏幕配置以及权限方案，而非仅仅修改代码。一旦Jira后端配置到位，JRJC的setFieldValue方法就能顺利完成自定义字段的设置。

以上就是使用JRJC通过REST API设置Jira自定义字段：配置、权限与错误排查的详细内容，更多请关注php中文网其它相关文章！