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.明确指出了问题所在。它通常由以下两个主要原因导致：
- 自定义字段未配置在相应的屏幕上： 在Jira中，Issue的创建、编辑和查看操作都关联到特定的屏幕（Screen）。如果自定义字段没有被添加到用于创建或编辑该Issue类型的屏幕上，即使代码尝试设置其值，Jira也会拒绝该操作，因为它认为该字段在该上下文中不可用。
- 用户缺乏必要的权限： 执行REST API调用的用户（或JRJC使用的凭据对应的用户）可能没有在该项目中创建或编辑Issue的权限，或者没有修改该特定自定义字段的权限。
这两个原因中，第一个是更常见的问题。Jira的字段可见性和可编辑性是严格受屏幕配置和权限方案控制的。
3. 解决方案与最佳实践
要解决“字段无法设置”的问题，需要从Jira的管理配置层面进行排查和调整。
3.1 Jira屏幕配置检查与调整
这是最常见的解决方案。你需要确保自定义字段“Test Type”已添加到对应Issue类型的“创建Issue屏幕”和/或“编辑Issue屏幕”上。
- 确定Issue类型和项目： 找出你正在尝试创建的Issue所属的项目和Issue类型。
-
查找屏幕方案：
- 导航到Jira管理界面 -> 项目。
- 选择你的项目，然后点击“屏幕”或“操作”菜单下的“屏幕方案”。
- 找到与你的Issue类型关联的屏幕方案。
-
检查屏幕配置：
- 点击屏幕方案旁边的“配置”链接。
- 找到“创建Issue屏幕”和“编辑Issue屏幕”（如果存在）。
- 点击对应的屏幕名称，进入屏幕配置页面。
- 在该页面，检查“Test Type”自定义字段是否已列出。如果未列出，你需要将其添加到屏幕中。
-
添加字段到屏幕：
- 在屏幕配置页面，找到底部的“选择字段以添加至屏幕”下拉菜单。
- 选择“Test Type”字段，然后点击“添加”。
- 确保字段被添加到屏幕后，保存更改。
注意事项：
- 如果你的Jira实例使用了工作流，某些字段的可见性和可编辑性也可能受到工作流属性的限制。在这种情况下，你可能还需要检查相关工作流的配置。
- 自定义字段在不同Issue类型或不同操作（创建/编辑/查看）下可能使用不同的屏幕。务必检查与你当前操作（创建Issue）和Issue类型相匹配的屏幕。
3.2 权限管理检查
如果屏幕配置正确，那么问题可能出在权限上。
-
检查项目权限：
- 导航到Jira管理界面 -> 项目。
- 选择你的项目，然后点击“权限”或“权限方案”。
- 检查用于执行API调用的用户（或用户组/角色）是否具有“创建Issue”和“编辑Issue”的权限。
-
检查字段权限：
- 虽然不常见，但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方法就能顺利完成自定义字段的设置。
