As a JIRA administrator, it is usually your responsibility to set up accounts in JIRA for the new user whenever someone new joins the organization. This is usually fine on an ad-hoc basis, but from time to time, you might be required to import many users at once. In these cases, you will need some additional tools to help you efficiently enable all these users to access the system without any delay.
For this recipe, we will need the JIRA Command Line Interface (CLI). You can get it at https://marketplace.atlassian.com/plugins/org.swift.jira.cli/cloud/overview.
The CLI add-on has two components. The first component is an add-on that you can install via the UPM just like any other JIRA add-ons. The second component is the actual command-line client, which we will use to execute commands against JIRA. You can download the latest command-line tool (atlassian-cli-x.x.x-distribution.zip) from
https://bobswift.atlassian.net/wiki/display/info/Downloads+-+Latest+CLI+Clients
.
You will also need to have an administrator account, as user creation is an administrative task.
Before we can start using the command-line client to import users into JIRA, we first need to prepare our user data. The easiest way is to create a comma-separated values (CSV) file containing the following information, in the order specified. You can use a spreadsheet application such as Microsoft Excel to create it:
|
Username |
Password |
|
Full name |
Group A |
|
tester1 |
xxxxx |
Test User |
jira-softwareusers |
The following list explains each column of the CSV file:
- Username: The username of the user; note that usernames in JIRA need to be unique.
- Password: The password for the new user. You can leave it blank, and let JIRA automatically generate one for you.
- Email: The e-mail address for the new user. E-mails can be sent out to the user for him/her to reset the password once the account is created.
- Full name: The full name of the new user.
- Group: Groups to add the new user into. If you want to add the user to multiple groups, put each group into its separate column. Note that the group name you specify must already exist in JIRA.
Now that you have your data file, proceed with the following steps to import and create the user accounts in JIRA:
- Unzip the CLI Client into a directory on your computer (for example,
/opt/cli). - Copy the users' CSV file to a directory on your computer (for example,
/tmp/users.csv) - Open a command prompt, and change to the directory which contains the CLI Client, that is, the directory that contains the
jira.shorjira.batfile. - Make sure the
jira.shfile (Linux) orjira.bat(Windows) file is executable. - Run the following command to import users; make sure you substitute the administrator username and password in your JIRA URL.
./jira.sh --action addUserWithFile --server http://localhost:8080 --password <password> --user <username> --file /tmp/users.csv
If everything runs fine, you will see an output similar to the following one on your console:
The result of the command, as shown in the preceding output, will show every new user added to JIRA as defined in the CSV file. Since we did not specify a password for the Tester Four user, the user is assigned an auto-generated password. The last line in the output also provides a summary of the number of users added successfully, and the failed ones, if any.
The command-line client that we used to run the addUserWithFile command uses JIRA's remote APIs to interact with JIRA. JIRA exposes many of its core functionalities via these APIs, such as creating new users and issues.
When we run the addUserWithFile command, we pass in the CSV file that contains our new users, formatted in a way that the client is able to understand, and make an API call JIRA to create those users for us.
However, take note that the same security rules apply when using these remote APIs (with or without the command-line client). So in our case, since creating new users is an administrative task, we need to provide an administrator account in the command.
The JIRA Command Line Interface add-on can do a lot more than just creating users. Simply run ./jira.sh or jira.bat to see a full list of commands and features it supports.