Bulk changing organization email addresses via API

[#1]

A lot of solutions are available when we start automating stuff. Experimenting with Atlassian’s API on various things that can be done has made room for endless possibilities. If you’re an organization administrator you might have come across situations whereby you are tasked to make changes to your user’s email address. Most probably due to a re-org or an acquisition. Whatever the reason is, you might have been stuck with the dilemma of how would you change all those email addresses to the appropriate target email? Well, today we’ll be exploring a solution that will help with this type of task. First of all, we’ll be writing a script in python and we’ll be using a python library called jiraone which can be installed by using pip install jiraone if you’re in a virtual environment or python3 -m pip install jiraone.

To begin, the prerequisite to using the functions of this package is to ensure that you’ve verified the domains you’re attempting to change in your organization. Atlassian provides two methods for this, either DNS or HTTPS. The second step would be to generate an admin token following this link. Once you’re done with that, we can begin with configuring our script below. We’ll be writing a very straightforward script that does a hefty task. You will need to prepare a CSV file following the format below. You can download the entire list of your users from your organization to get the accountId and edit the file to output it in the below format.

from jiraone.module import bulk_change_email

token = "VgfDt37usjGYxxxx"
# The list of users should be in the same directory as the script
file = "users.csv"
bulk_change_email(file, token)

# Output
# Changing current email: prince.nyeche@example.com to target email: prince.nyeche@noreplay.com
# Changing current email: prince_crown@example.com to target email: prince_crown@noreplay.com
# **************************************************************************************************** 

What’s happening above is that we’re reading the file and simply changing the email to the target email. We’re authenticating to the resource using the admin token supplied to the function. Please note that the above function will only work for the target email address which doesn’t exist as an Atlassian account. If you’ve encountered a situation, whereby you’re performing a user management change request but the target email address already exists as an Atlassian account, this will cause a conflict but fear not - keep reading below and we’ll explain how you can overcome this huddle.

Oh! you’re still here. Did I pique your interest yet? Anyway, there have been problems surrounding the change of email addresses where the target email address already exists as an Atlassian account. This usually happens when the user already went ahead to create a new account or probably your SSO provider automatically provisioned a new account based on a new domain that was acquired. And you want to retain the user activity that was in the previous email account but during the change, you get a conflict because the target email address already exists. Fear not, I’m going to explain how to work around this problem using the next function.

from jiraone.module import bulk_change_swap_email

token = "VgfDt37usjGYxxxx"
# The list of users should be in the same directory as the script
file = "users.csv"
bulk_change_swap_email(file, token)

# Checking organization users...
# Success:---Status: 204
# Changing current email: prince.nyeche@example.com to dummy email: dummy0000007@example.com
# Changing target email: prince.nyeche@noreplay.com to current email: prince.nyeche@example.com
# Changing dummy email: dummy0000007@example.com to target email: prince.nyeche@noreplay.com
# *******************************************************************************************

The above does a swap of email replacing the current email address with the target email address thus retaining the user activity that exists using a 3rd dummy non-existent email address which is auto-generated from the function using your current email address domain suffix. We use a function within the function to match users based on their email and this is only possible if you're an organization administrator. 

Once that is done, you should have your preferred email address replaced. For any of the email addresses that are not changed, the function is able to rewrite it to the same file that was supplied. So you can review and know the reason behind why it failed. In summary, as an organization administrator, you can be able to perform all these changes at ease using API and the above python library.