Last updated Nov 1, 2024

Bulk operation APIs: additional examples and FAQ

Additional examples

In addition to examples added in the Issue Bulk Operations documentation, here are some additional examples and FAQ, for better understanding of the APIs.

Bulk edit getFields API

Example response of bulk edit get fields API, which contains custom fields. It says, Approvals custom field with ID: customfield_10041 is not available for bulk edit. While the Change type custom field with ID: customfield_10005 is available for bulk edit, as it has no unavailableMessage populated.
It also signifies that the Change type custom field accepts only one of the following options: Standard, Normal, or Emergency.

1
2
{
  "fields": [
    {
      "type": "com.atlassian.servicedesk.approvals-plugin:sd-approvals",
      "id": "customfield_10041",
      "name": "Approvals",
      "description": "Provides search options for Jira approvals information. This custom field is created programmatically and required by Jira.",
      "isRequired": false,
      "unavailableMessage": "{0}NOTE{1}: This field is not available for bulk update operations."
    },
    {
      "type": "com.atlassian.jira.plugin.system.customfieldtypes:select",
      "id": "customfield_10005",
      "name": "Change type",
      "description": "",
      "isRequired": false,
      "fieldOptions": [
        {
          "optionId": 10004,
          "value": "Standard",
          "isDisabled": false
        },
        {
          "optionId": 10005,
          "value": "Normal",
          "isDisabled": false
        },
        {
          "optionId": 10006,
          "value": "Emergency",
          "isDisabled": false
        }
      ]
    }
  ]
}

Bulk edit submit API

  1. This payload of bulk edit submit API tries to edit three fields: labels, issuetype and priority, for three issues. In editedFieldsInput we are sending the required values, like in case of labelsFields, we want to add a label Hello to field with ID: labels, so we have chosen the bulkEditMultiSelectFieldOption as ADD.
    There are other options as well, for which you can refer to the original documentation.
1
2
{
    "selectedActions": [
        "labels",
        "issuetype",
        "priority"
    ],
    "selectedIssueIdsOrKeys": [
        "10001",
        "10002",
        "10003"
    ],
    "editedFieldsInput": {
        "labelsFields": [
            {
                "fieldId": "labels",
                "labels": [
                    {
                        "name": "Hello"
                    }
                ],
                "bulkEditMultiSelectFieldOption": "ADD"
            }
        ],
        "issueType": {
            "issueTypeId": "10013"
        },
        "priority": {
            "priorityId": "1"
        }
    }
}
  1. This payload tries to edit an environment field, which comes under richTextFields. For these, we use the Atlassian Document Format (ADF). Please refer to Atlassian Document Format for more information on ADF.
    This payload will edit the field value to: Hi.
1
2
{
    "selectedActions": [
        "environment"
    ],
    "selectedIssueIdsOrKeys": [
        "CS-2"
    ],
    "editedFieldsInput": {
        "richTextFields": [
            {
                "fieldId": "environment",
                "richText": {
                    "adfValue": {
                        "version": 1,
                        "type": "doc",
                        "content": [
                            {
                                "type": "paragraph",
                                "content": [
                                    {
                                        "type": "text",
                                        "text": "Hi",
                                        "marks": [
                                            {
                                                "type": "strong"
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                }
            }
        ]
    }
}
  1. This payload simply clears the environment field. After successful execution of this request, it’s field value will be empty.
1
2
{
    "selectedActions": [
        "environment"
    ],
    "selectedIssueIdsOrKeys": [
        "CS-3"
    ],
    "editedFieldsInput": {
        "richTextFields": [
            {
                "fieldId": "environment",
                "richText": {}
            }
        ]
    }
}
  1. This payload attempts to edit a cascading type field customfield_10064. It sets the parent value as option with ID: 10042 and the ID: 10044 for the child value.
1
2
{
    "selectedActions": [
        "customfield_10064"
    ],
    "selectedIssueIdsOrKeys": [
        "10125",
        "10124"
    ],
    "editedFieldsInput": {
        "cascadingSelectFields": [
            {
                "fieldId": "customfield_10064",
                "parentOptionValue": {
                    "optionId": "10042"
                },
                "childOptionValue": {
                    "optionId": "10044"
                }
            }
        ]
    }
}

Bulk move submit API

  1. This payload for bulk move attempts to move a subtask explicitly, meaning the subtask has its own mapping and is not moved as part of its parent issue.
    The subtask MTCJS-2 will be moved to a project MTCJ with issue type ID as 10008 under a new parent i.e, MTCJ-11. Also, in this payload, we have provided the mandatory fields and status mapping explicitly.
1
2
{
  "targetToSourcesMapping": {
        "MTCJ,10008,MTCJ-11": {
            "issueIdsOrKeys": ["MTCJS-2"],
            "inferFieldDefaults": false,
            "inferStatusDefaults": false,
            "inferSubtaskTypeDefault": true,
            "targetMandatoryFields": [
                {
                    "fields": {
                        "fixVersions": {
                            "value": ["10008"]
                        }
                    }
                }
            ],
            "targetStatus": [
                {
                   "statuses": {
                       "10000": ["10010", "10011"],
                       "10001": ["10012"]
                    }
                }
            ]
        }
    }
}
  1. In this payload, the objective is to move MTCJS-1 along with its two subtasks: MTCJS-2 and MTCJS-3, whose subtask issue types are different. Given that inferSubtaskTypeDefault is set to false, a distinct mapping for its subtasks has been specified. Both MTCJS-2 and MTCJS-3 have been reassigned to different target subtask issue types.
    Furthermore, within the target project MTCJ, under issueTypes 10007 or 10008, it was necessary to populate fields such as fixVersions and description. So, these values were provided accordingly. It's worth noting that there are no mandatory fields for the target context of MTCJ,10009.
1
2
{
    "targetToSourcesMapping": {
        "MTCJ,10007": {
            "issueIdsOrKeys": ["MTCJS-1"],
            "inferFieldDefaults": false,
            "inferStatusDefaults": false,
            "inferSubtaskTypeDefault": false,
            "targetMandatoryFields": [
                {
                    "fields": {
                        "fixVersions": {
                            "value": ["10000"]
                        },
                        "description": {
                            "value": {
                                "version": 1,
                                "type": "doc",
                                "content": [
                                    {
                                        "type": "paragraph",
                                        "content": [
                                            {
                                                "type": "text",
                                                "text": "New description"
                                            }
                                        ]
                                    }
                                ]
                            },
                            "type": "adf",
                            "retain": true
                        }
                    }
                }
            ],
            "targetStatus": [
                {
                    "statuses": {
                        "10000": ["10001","10002"]
                    }
                }
            ]
        },
        "MTCJ,10008": {
            "issueIdsOrKeys": ["MTCJS-2"],
            "inferFieldDefaults": false,
            "inferStatusDefaults": false,
            "inferSubtaskTypeDefault": true,
            "targetMandatoryFields": [
                {
                    "fields": {
                        "fixVersions": {
                            "value": ["10000"]
                        },
                        "description": {
                            "value": {
                                "version": 1,
                                "type": "doc",
                                "content": [
                                    {
                                        "type": "paragraph",
                                        "content": [
                                            {
                                                "type": "text",
                                                "text": "New description"
                                            }
                                        ]
                                    }
                                ]
                            },
                            "type": "adf",
                            "retain": true
                        }
                    }
                }
            ],
            "targetStatus": [
                {
                    "statuses": {
                        "10003": ["10004"]
                    }
                }
            ]
        },
        "CBMBP3,10009": {
            "issueIdsOrKeys": ["MTCJS-3"],
            "inferFieldDefaults": true,
            "inferStatusDefaults": true,
            "inferSubtaskTypeDefault": true
        }
    }
}

Bulk operations progress API

Response returned when the status of the taskId is RUNNING.

1
2
{
    "taskId": "10001",
    "status": "RUNNING",
    "progressPercent": 65,
    "submittedBy": {
        "accountId": "<account_id>"
    },
    "created": 1690180055963,
    "started": 1690180056206,
    "updated": 1690180058294
}

FAQ

  1. I attempted to update mandatory field values while moving issues, but the new values weren't applied. Why did this happen?
    Answer: If all selected issues already have pre-filled mandatory fields, changes to these fields are not applied unless at least one issue lacks pre-filled values. The retain attribute in your payload is only considered in cases where mandatory fields are not universally pre-filled.

  2. I received a validation error asking to fill in mandatory fields for some issues. Why?
    Answer: This error indicates that not all issues had their mandatory fields pre-filled, which is necessary when inferFieldDefaults is set to true. You'll need to provide values for these fields explicitly or set inferFieldDefaults to false.

  3. Why did moving an issue with a subtask throw a validation error regarding mandatory field values for the subtask?
    Answer: If a subtask lacks pre-filled mandatory fields and inferSubtaskTypeDefault is set to true, the system requires explicit mapping for these fields. You need to set inferSubtaskTypeDefault to false and provide the necessary field mappings for subtasks.

  4. I attempted to move an issue with its subtasks to a new parent in a different project but encountered an error. What went wrong?
    Answer: The error, You can only move issues to a single target project, issue type, and parent issue, occurs because current functionality does not support moving issues and subtasks to different target projects in a single operation.

  5. How many issues can I edit at once?
    Answer: Yes, for all the bulk operation APIs, there is a strict limit on the number of issues you can update in a single request. The maximum number of issues, including subtasks, that you can update at once is capped at 1000. To edit more than 1000 issues, you'll need to divide your update operations into multiple requests, ensuring each one stays within the limit.

Rate this page: