Get Ahead of the Curve: Exploring Jira Cloud's Powerful New Bulk Move API

Jira Cloud is constantly evolving, introducing new features and functionalities to streamline workflows and boost productivity. One such exciting addition is the experimental Bulk Move API, a game-changer for anyone who frequently needs to move multiple Jira issues at once.

Currently, moving issues can not be done by Jira automation which can be a huge hinderance to daily activities, some users will prefer to use the Clone Issue action but I encountered one big problem with this, cloning does not keep the form data from Jira Service Management project.

Bulk Move API keeps all form data even when moving just one issue.

To read the official Jira Cloud API documentation on this click here.

This article dives deep into this powerful new tool, exploring its capabilities, use cases, limitations, and the unique advantages it offers over manual methods.

In this article, I will showcase a basic move with one issue, this can be scaled up and customized to a whole new level of complexity when needed.

What is the Bulk Move API?

The Bulk Move API allows you to programmatically move multiple Jira issues between projects, boards, or even different Jira instances in a single request.

This eliminates the tedious manual process of the bulk move action in the filter menu, this is also limited to 1000 issues at a time, using the API can save you significant time and effort.

Unlocking the Power: Use Cases

The Bulk Move API opens up a world of possibilities for Jira users:

• Mass Issue Migration: Effortlessly move large volumes of issues between projects during reorganizations, sprints, or releases.
• Automated Workflows: Integrate the API into your custom workflows to automatically move issues based on predefined criteria, such as status changes or due dates.
• Data Analysis and Reporting: Move issues to dedicated projects for analysis or reporting purposes, allowing for more granular insights into your project data.
• Routing issues through Jira Automation: Create a main Jira Service Management project and route tickets to the teams projects through automation.

Limitations and Considerations:

While incredibly powerful, the Bulk Move API is still in its experimental phase. Keep these points in mind:

• API Access: You'll need appropriate API permissions to access and utilize the Bulk Move API, the API access is based on the users permissions, you will still need permission to Bulk Move and access to all the projects involved.
• Rate Limits: Like most APIs, the Bulk Move API has rate limits to prevent abuse. Be mindful of these limits when designing your workflows.
• Data Integrity: Always test your API calls thoroughly to ensure data integrity and avoid unintended consequences.

When using the bulk move, keep in mind that there are limits on the number of issues and fields you can include.

• You can move up to 1,000 issues in a single operation, including any subtasks.
• All issues must originate from the same project and share the same issue type and parent.
• The total combined number of fields across all issues must not exceed 1,500,000. For example, if each issue includes 15,000 fields, then the maximum number of issues that can be moved is 100.

Unique Features and Advantages:

The Bulk Move API offers several unique advantages over traditional methods:

• Granular Control: You can specify precise move criteria, including issue types, statuses, and custom fields (only required custom fields).
• Batch Processing: Move multiple issues simultaneously, significantly reducing processing time.
• Flexibility and Customization: Integrate the API into your existing workflows and automate complex move scenarios through automation or workflows.

Getting Started:

For this example, I will showcase the basics of this powerful API and walk you through how to execute this in Jira automation.

You can test this in any software you are most comfortable with, Postman is also highly recommended for seeing input/output more clearly.

Firstly, create a basic Jira Automation rule with a web request action and a log to check the web response.

The trigger does not matter currently as I have simply set it to "Scheduled" and set the JQL to a test issue for an easy way to run the API call.

Now lets dive deeper into the API request itself.

The building blocks of the web request URL just require you to replace {{Atlassian Domain}} with your unique instance url.

https://{{Atlassian Domain}}.atlassian.net/rest/api/3/bulk/issues/move        

Set the HTTP method to POST and change the Web request body to "Custom data".

Our custom data will consist of a JSON body which configures the issue type, project and keys that will be moved.

{
    "targetToSourcesMapping": {
        "{{Project Key}},{{Issue Type ID}}": {
            "inferFieldDefaults": true,
            "inferStatusDefaults": true,
            "inferSubtaskTypeDefault": true,
            "issueIdsOrKeys": [
                "{{key}}"      
            ]
        }
    }
}        

I will mark the variables you will need to change for a basic move with the Jira variable syntax, two curly braces {{variable}}.

You will need to configure the destination project key {{Project Key}} (e.g. ITSM) and the destination issue type ID {{Issue Type ID}} (e.g. 10200).

There is also another variable involved called {{key}}, this is simply taking the key that the rule was scheduled on (ID-217) and sending that key as the issue to move. If you want to move multiple issues you will need to format them into a list of keys as shown below.

 [
        "ISSUE-1", "ISSUE-2"
 ]        

For the Boolean properties, these are required and I will explain each one below, for a simple request such as moving one issue and retaining all values that can be retained when moving, you can ignore these and copy paste my template.

inferFieldDefaults

If true, values from the source issues will be retained for the mandatory fields in the field configuration of the destination project. The targetMandatoryFields property shouldn't be defined.

If false, the user is required to set values for mandatory fields present in the field configuration of the destination project. Provide input by defining the targetMandatoryFields property.

inferStatusDefaults

If true, the statuses of issues being moved in this target group that are not present in the target workflow will be changed to the default status of the target workflow (see below). Leave targetStatus empty when using this.

If false, you must provide a targetStatus for each status not present in the target workflow.

The default status in a workflow is referred to as the "initial status". Each workflow has its own unique initial status. When an issue is created, it is automatically assigned to this initial status.

inferSubtaskTypeDefault

When an issue is moved, its subtasks (if there are any) need to be moved with it. inferSubtaskTypeDefault helps with moving the subtasks by picking a random subtask type in the target project.

If true, subtasks will automatically move to the same project as their parent.

When they move:

• Their issueType will be set to the default for subtasks in the target project.
• Values for mandatory fields will be retained from the source issues
• Specifying separate mapping for implicit subtasks won’t be allowed.

If false, you must manually move the subtasks. They will retain the parent which they had in the current project after being moved.

There are many more customisable options for bulk move, if you want to experiment further, you can read the Atlassian API documentation here.

Configuring the web request action and authorization

After we have finished with the custom JSON body, remember to set the option "Delay execution of subsequent rule actions until we've received a response for this web request" on, this way we can always log the response in order of execution.

Now the last configuration and a very important part of Jira Cloud API's are the headers.

Firstly, you can set "Content-Type" to "Application/json" to set the content type for the API, this isn't always necessary but it can help parse the custom data.

Next, we need to use Basic Authentication using an API Key generated from this URL https://id.atlassian.com/manage-profile/security/api-tokens

You will need to combine the API Key with your Atlassian email address to create a basic authentication. You can use a free generator such as https://www.debugbear.com/basic-auth-header-generator or simply use a software like Postman which can generate it for you.

When you have generated your Basic Authentication code, you can enter it into the headers.

It will look something like this.

Authentication: Basic aGlkZGVuZWFzdGVyZWdnQGdtYWlsLmNvbTpZT1UgRk9VTkQgSVQ=        

Please remember that your API Key should be stored somewhere secure like a password generator or vault and will only be shown once in the Atlassian UI.

Note: The API Key reflects the permissions of the user who generated it, if you don't have access to bulk move or don't have access to all projects involved in the moving, this won't work and will return an error.

If you would like to read more about how to authenticate and the basics of the Jira Cloud REST API, please read my earlier article on this linked here.

I hope you have a great time experimenting with the API's and please let me know if you need any help with all things Atlassian!

Sponsored by Elegance Group - Atlassian Platinum Partner

Proudly sponsored by Elegance Group, a distinguished Atlassian partner recognized globally and awarded Partner of the Year in 2022 and still conducting consistent elegant solutions.

For expert advice on Licensing or Services from an acclaimed Atlassian Partner, reach out to Elegance Group.

Book a meeting with us to enhance your business with our unparalleled Atlassian solutions

.