Documentation for JIRA 4.3. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata
JIRA 101

Thank you for choosing JIRA to track your projects and issues. To help you get up and running quickly, we've compiled some easy instructions for configuring and using JIRA 4.2.

Getting Started

1. Installing JIRA

First things first. If you haven't already got JIRA up and running, carry out the following steps:
  For Windows: (click to expand)

You may want to watch the video showing how to do this.

  1. Download the JIRA Standalone Windows Installer (.EXE) file from the Atlassian Download Center.
  2. Run the .EXE file, choose an installation directory, a home directory and a port ('8080' will do). We recommend that you choose to 'Run JIRA as a service'.
  3. JIRA will start automatically when the Installer finishes, if you selected the option to launch JIRA at the end of the Installer.
  4. To access JIRA, go to your web browser and type this address: http://localhost:8080. Windows 'Start' menu shortcuts will also be added which you can also use to start and stop JIRA.
  5. Follow the Setup Wizard. This will guide you through the process of setting up your JIRA server, creating an Admin user and (optionally) setting up email.

For more help on the technical procedures in this section, see the JIRA Installation Guide.

If you need assistance, please create a support ticket.

(warning) Before using JIRA as a production system, you need to switch from the default HSQL database, which is provided for evaluation purposes only. Please see the documentation for details.

  For Mac: (click to expand)

You may want to watch the video showing how to do this.

  1. Download the JIRA Standalone TAR (.GZ) file from the Atlassian Download Center, and unzip it.
  2. Edit the jira-application.properties file in the JIRA Installation Directory, add a 'jira.home' property and set it to your desired location for the JIRA home directory. Please use forward-slashes ("/"), not back-slashes ("\").
  3. Run bin/startup.sh to start JIRA.
  4. To access JIRA, go to your web browser and type this address: http://localhost:8080.
  5. Follow the Setup Wizard. This will guide you through the process of setting up your JIRA server, creating an Admin user and (optionally) setting up email.

For more help on the technical procedures in this section, see the JIRA Installation Guide.

If you need assistance, please create a support ticket.

(warning) Before using JIRA as a production system, you need to switch from the default HSQL database, which is provided for evaluation purposes only. Please see the documentation for details.

  For Linux: (click to expand)
  1. Download the JIRA Standalone TAR (.GZ) file from the Atlassian Download Center, and unzip it.
  2. Install Java and set JAVA_HOME.
  3. Edit the jira-application.properties file in the JIRA Installation Directory, add a 'jira.home' property and set it to your desired location for the JIRA home directory. Please use forward-slashes ("/"), not back-slashes ("\").
  4. Run bin/startup.sh to start JIRA.
  5. To access JIRA, go to your web browser and type this address: http://localhost:8080.
  6. Follow the Setup Wizard. This will guide you through the process of setting up your JIRA server, creating an Admin user and (optionally) setting up email.

For more help on the technical procedures in this section, see the JIRA Installation Guide.

If you need assistance, please create a support ticket.

(warning) Before using JIRA as a production system, you need to switch from the default HSQL database, which is provided for evaluation purposes only. Please see the documentation for details.

2. Adding Users

  For each of your users, you will need to do the following: (click to expand)
  1. Click 'Administration' in the top navigation bar.
  2. Click 'User Browser' in the left navigation column, then click 'Add User'.
  3. Enter the Username, Password, Full Name and Email Address; and (optionally) tick the box to send the user an email containing their account details. Then click the Create button. For more details, please see the documentation.
  4. The User Browser will be displayed. Locate the new user and click the 'Groups' link in the 'Operations' column.
  5. If the user is going to need to work on issues, select the 'jira-developers' group and click the 'Join' button. (If the user is only going to log issues, and not work on them, then they don't need to belong to the 'jira-developers' group.) For more about groups, please see the documentation.
    • Note: Adding your users to the 'jira-developers' group will automatically add them to the Default Members for the 'Developers' project role. For more about project roles, please see the documentation.

You may want to suggest to your users that they take a look at 'Mastering the Basics' (below). You may also want to point them to the documentation on:

(info) Your users will need to access JIRA at http://<JIRA machine name>:8080 (not http://localhost:8080).

3. Creating a Project

  Before you can create issues, you need to create a project to contain them. Here's how: (click to expand)
  1. Click 'Administration' in the top navigation bar.
  2. Click 'Projects' in the left navigation column, then click 'Add Project'.
  3. In the 'Name' field, type a descriptive name for your project (typically two or three words, e.g. 'Purchase Orders').
  4. In the 'Key' field, type a meaningful prefix for issues in your project (typically three or four characters, e.g.'ORD'). Note that this cannot be changed later.
  5. In the 'Project Lead' field, select the user to whom issues should be assigned by default.
  6. If you chose to set up email when you installed JIRA (see above), change the 'Notification Scheme' field from 'None' to 'Default Notification Scheme'. This will allow JIRA to automatically send emails to appropriate people when particular events occur (e.g. 'Issue Created', 'Issue Resolved'). For more about email, please see the documentation.
  7. Leave the rest of the fields with their default values for now. Click the 'Add' button.

For more about creating a project, please see the documentation or watch the video.

4. Optional Extras

 Installing the Universal Plugin Manager: (click to expand)

To make it easy to add and manage JIRA plugins, you need to first do the following:

  1. Download the Universal Plugin Manager from the Atlassian Plugin Exchange.
  2. Shut down JIRA.
  3. Copy the UPM plugin jar (e.g. 'atlassian-universal-plugin-manager-plugin-x.x.x.jar') into your JIRA home directory under plugins/installed-plugins/.
  4. Start up JIRA.
  5. Go to 'Administration > Plugins'. The Universal Plugin Manager will be listed and enabled.

Once you have installed the UPM, you can use it manage your JIRA plugins. For details, please see the documentation on Using the Universal Plugin Manager.

Mastering the Basics

5. Creating an Issue

  To enter a new issue into JIRA: (click to expand)
  1. Click the 'Create Issue' link in the top navigation-bar.
  2. Select the relevant Project and Issue Type, then click the 'Next' button.
  3. Type a short description of the issue in the 'Summary' field, then click the 'Create' button.

For more details, please see the documentation.

6. Logging Work on an Issue

  To record the time that you have spent working on an issue, and action you have taken: (click to expand)
  1. Go to the issue, and select 'Log work' from the 'Operations' menu in the left column.
  2. In the 'Time Spent' field, enter the amount of time to be logged. Use 'w', 'd', 'h' and 'm' to specify weeks, days, hours or minutes (e.g. to enter two hours of work, type '2h').
  3. In the 'Work Description' field, type a description or comment about the work you have done
  4. Click the 'Log' button.

For more details about the other options on this screen, please see the documentation.

7. Resolving an Issue

  Resolving an issue sets its Status to 'Resolved', indicating that work is complete. To resolve an issue: (click to expand)
  1. Go to the issue, and select 'Resolve Issue' from the 'Available Workflow Actions' menu in the left column.
  2. In the 'Resolution' field, select the 'Resolution' that best describes the outcome (e.g. 'Fixed').
  3. (Optional) In the 'Comment' field, type a description or comment about the issue's resolution.
  4. Click the 'Resolve' button.

For more information about how an issue moves from one Status to another, please see the documentation.

8. Searching for Issues

  To use Quick Search: (click to expand)
  • Use the box in the top right corner of every page to quickly search JIRA. You can type an issue key (e.g. TEST-1234) to jump directly to an issue, or use syntax like my open issues to immediately return all issues which are assigned to you and haven't yet been resolved.
  To use Regular Search: (click to expand)
  1. Click 'Issues' on the top navigation bar to display JIRA's searching and filtering panel.
  2. Select the Project, Issue Type, or any other issue attributes of interest. You can also perform comprehensive text searches.
  To use Advanced Search: (click to expand)
  1. Click 'Issues' on the top navigation bar, then click 'advanced' to display the JQL (JIRA Query Language) panel.
  2. Type your query (e.g. 'project=TEST') and click the 'Search' button.

See the documentation for more information about saving your searches ('issue filters') and receiving search results via email.

9. Charting, Reporting and Exporting

  To generate a chart: (click to expand)
  1. View your search results (see 'Searching' above) in the Issue Navigator.
  2. Click the 'Views' menu and select the 'Charts' option.
  3. Choose your preferred type of chart, and enter any required configuration details. For more details, please see the documentation.
  To generate a report: (click to expand)
  1. Click 'Projects' in the top navigation bar.
  2. Select the project you are interested in.
  3. Click 'Reports' at the right of the screen and select the report of interest.
  4. Enter any required configuration details, then click 'Next' to display your report (e.g. Workload Pie Chart Report).
  To export data to MS-Word, MS-Excel, XML or RSS: (click to expand)
  1. View your search results (see 'Searching' above) in the Issue Navigator.
  2. Click the 'Views' menu and select 'Word', 'Excel', or your preferred format. For more details, please see the documentation.

Customising JIRA

(Note that you need to be an Administrator to do the tasks in this section.)
 Before you begin: (click to expand)

You may want to create a sample project named 'Purchase Orders', in which to perform the tasks described in this section. For instructions, please see 'Creating a Project' (above).

10. Adding a new Issue Type

  Why would I do this? (click to expand)

The Issue Type is one of the first things a user must choose when they create an issue.
Depending on how your organisation is using JIRA, you might want to add a new Issue Type.
For example, if you are using JIRA to track purchase orders, the default Issue Types ('Bug', 'Improvement', 'New Feature', 'Task') might not be relevant. So you might want to add a new Issue Type called 'Order'.

  How do I do this? (click to expand)

To add a new Issue Type called 'Order', and associate it with a project called 'Purchase Orders':

  1. Click 'Administration' in the top navigation bar.
  2. Click 'Issue Types' in the left navigation column (under 'Issue Settings').
  3. In the 'Add New Issue Type' form, in the 'Name' field, type 'Order. In the 'Description' field, type 'A purchase order'. Then click the 'Add' button'. (For more about adding Issue Types, and icons, please see the documentation.)
  4. Click the 'Issue Types Scheme' tab at the top of the 'Manage Issue Types' screen.
  5. In the 'Add New Issue Type Scheme' form, in the 'Name' field, type 'Purchase Order Issue Type Scheme'. Then click the 'Add' button'. (For more about Issue Type Schemes, please see the documentation.)
  6. In the 'Available Issue Types' list, click the Issue Type called 'Order' and drag it into the 'Issue Types for Current Scheme' list. Then click the 'Save' button.
  7. Click 'Projects' in the left navigation column. Then in the 'Name' column, click 'Purchase Orders'. The project details will be displayed.
  8. Click the 'Select' link next to the 'Issue Type Scheme' field, select 'Purchase Order Issue Type Scheme' and click the 'Associate' button.

To test what you have done, create an issue in the 'Purchase Orders' project. The only available Issue Type should be 'Order'.

11. Adding a new Screen

  Why would I do this? (click to expand)

Depending on how your organisation is using JIRA, you might want to add a purpose-built screen that will be displayed for particular types of issues, or for particular projects or workflows.
For example, if you are using JIRA to track purchase orders, some of the normal issue fields (e.g. 'Affects Version', 'Fix Version', 'Environment') might not be relevant. So you might want to create a simplified screen that omits these fields.

  How do I do this? (click to expand)

To add a new Screen called 'Purchase Order Screen', and associate it with a project called 'Purchase Orders':

  1. Click 'Administration' in the top navigation bar.
  2. Click 'Screens' in the left navigation column (under 'Issue Fields').
  3. Click the 'Copy' link next to 'Default Screen'.
  4. In the 'Name' field, type 'Purchase Order Screen'. Then click the 'Copy' button'. (For more about Screens, please see the documentation.)
  5. Click the 'Configure' link next to 'Purchase Order Screen'.
  6. Tick the 'Remove' box for the following fields: 'Affects Version', 'Fix Version', 'Environment'. Then click the 'Remove' button.
  7. Click 'Screen Schemes' in the left navigation column (under 'Issue Fields').
  8. In the 'Name' field, type 'Purchase Order Screen Scheme'. In the 'Default Screen' field, select 'Purchase Order Screen'. Then click the 'Add' button'. (For more about Screen Schemes, please see the documentation.)
  9. Click 'Issue Type Screen Schemes' in the left navigation column (under 'Issue Fields').
  10. In the 'Name' field, type 'Purchase Order Issue Type Screen Scheme'. In the 'Screen Scheme' field, select 'Purchase Order Screen Scheme'. Then click the 'Add' button'. (For more about Issue Type Screen Schemes, please see the documentation.)
  11. Click 'Projects' in the left navigation column. Then in the 'Name' column, click 'Purchase Orders'. The project details will be displayed.
  12. Click the 'Select' link next to the 'Issue Type Screen Scheme' field, select 'Purchase Order Issue Type Screen Scheme' and click the 'Associate' button.

To test what you have done, view an issue in the 'Purchase Orders' project. You shouldn't see the 'Affects Version', 'Fix Version' or 'Environment' fields.

12. Adding a new Custom Field

  Why would I do this? (click to expand)

Depending on how your organisation is using JIRA, you might need to add a 'custom' field that will be displayed for particular types of issues, or for particular projects.
For example, if you are using JIRA to track purchase orders, you might create a custom field called 'Supplier'.

  How do I do this? (click to expand)

To create a new custom field called 'Supplier' and put it on the 'Purchase Order Screen':

  1. Click 'Administration' in the top navigation bar.
  2. Click 'Custom Fields' in the left navigation column (under 'Issue Fields'), then click 'Add Custom Field'.
  3. On the 'Create Custom Field - Step 1' screen, in the 'Field Type' field, choose 'Select List'. Then click the 'Next' button.
  4. On the 'Create Custom Field - Step 2' screen:
    1. in the 'Name' field, type 'Supplier'.
    2. in the 'Description' field, type 'Choose the supplier for this Purchase Order'.
    3. under 'Choose applicable issue types' select 'Order'. Then click the 'Finish' button.
  5. On the 'Associate field Order to screens' screen, tick the check-box for 'Purchase Order Screen'. Then click the 'Update' button.
  6. On the 'View Custom Fields' screen, click the 'Configure' link next to 'Supplier'. Then click 'Edit Options'.
  7. Add three options: 'ABC Pty Ltd', 'ACME Pty Ltd', 'XYZ Pty Ltd'. Choose 'ACME Pty Ltd' as the default. Then click the 'Done' button.

To test what you have done, create an issue in the 'Purchase Orders' project. You should see a field called 'Supplier' that has a drop-down box containing your three options.

Note: you may also want to watch the video on adding a custom field.

13. Adding a new Issue Status and Workflow

  Why would I do this? (click to expand)

Depending on how your organisation is using JIRA, you might need to add a new 'Status' , i.e. a new step in the issue 'workflow'.
For example, if you are using JIRA to track purchase orders, you might add a new Status called 'Purchase Approved' .

  How do I do this? (click to expand)

To add a new Status called 'Purchase Approved', and create a new workflow that has an extra step between 'Open' and 'In Progress':

  1. Click 'Administration' in the top navigation bar.
  2. Click 'Statuses' in the left navigation column (under 'Issue Settings').
  3. In the 'Name' field, type 'Purchase Approved'. Then click the 'Add' button'. (For more about adding Statuses, and icons, please see the documentation.)
  4. Click 'Workflows' in the left navigation column.
  5. Click the 'Copy' link next to 'jira (Read-only System Workflow)'.
  6. In the 'Workflow Name' field, type 'Purchase Order Workflow'. Then click the 'Copy' button'. (For more about Workflow, please see the documentation.)
  7. Click the 'Steps' link next to 'Purchase Order Workflow'.
  8. In the 'Add New Step' form:
    1. in the 'Name' field, type 'Purchase Approved'.
    2. in the 'Linked Status' field, select 'Purchase Approved'.
    3. click the 'Add' button.
  9. Click the 'Add Transition' link next to 'Open':
    1. in the 'Name' field, type 'Approve Purchase'.
    2. in the 'Destination Step' field, select 'Purchase Approved'.
    3. click the 'Add' button.
  10. Click the 'Add Transition' link next to 'Purchase Approved':
    1. in the 'Name' field, type 'Start Progress'.
    2. in the 'Destination Step' field, select 'In Progress'.
    3. click the 'Add' button.
  11. Click the 'Delete Transitions' link next to 'Open'. Select 'Start Progress' and click the 'Delete' button.
  12. Click 'Workflow Schemes' in the left navigation column (under 'Schemes'). Then click 'Add Workflow Scheme'.
  13. In the 'Name' field, type 'Purchase Order Workflow Scheme'. In the 'Default Screen' field, select 'Purchase Order Screen'. Then click the 'Add' button'. (For more about Workflow Schemes, please see the documentation.)
  14. Click the 'Workflows' link next to 'Purchase Order Workflow Scheme', click 'Assign Workflow' and select 'Purchase Order Workflow'. Then click the 'Add' button.
  15. Click 'Projects' in the left navigation column. Then in the 'Name' column, click 'Purchase Orders'. The project details will be displayed.
  16. Click the 'Select' link next to the 'Workflow Scheme' field, select 'Purchase Order Workflow Scheme' and click the 'Associate' button.

To test what you have done, create an issue in the 'Purchase Orders' project. After you save the issue, the left column should contain a link called 'Approve Purchase', but not a link called 'Start Progress'.

Note: you may also want to watch the video on customising JIRA Workflow.

14. Using Permission Schemes, Groups and Project Roles

  Why would I do this? (click to expand)

A Permission scheme allows you to grant people 'permission' to work on issues in a project. The new project that you created previously is using JIRA's Default Permission Scheme. If you end up creating lots of projects, you might need to grant different people permission to work on different projects.
For example, if your organisation requires all software development issues to be tested by a Quality Assurance person before being closed, you could create a permission scheme called 'Software Development Permission Scheme' in which you assign the 'Close Issue' permission to the appropriate people. You would then associate your new permission scheme with all your software development projects.
There are a number of ways to do this, depending on your requirements:

  • Project roles enable you to associate different people with particular functions, for particular projects.
  • Groups enable you to associate the same people with a particular function, for all projects that use this permission scheme.
  How do I do this? (click to expand)

To add a new permission scheme called 'Software Development Permission Scheme', and a project role called 'Quality Assurance':

  1. Create a project role called 'Quality Assurance':
    1. Click 'Administration' in the top navigation bar.
    2. Click 'Project Roles' (under 'Users, Groups and Roles') in the left column.
    3. In the 'Name' field, type 'Quality Assurance'. Then click the 'Add Project Role' button.
  2. Create a permission scheme called 'Software Development Permission Scheme', in which you assign the 'Close Issue' permission to the 'Quality Assurance' project role:
    1. Click 'Permission Schemes' (under 'Schemes) in the left column.
    2. Click the 'Copy' link next to 'Default Permission Scheme'. A new permission scheme called 'Copy of Default Permission Scheme' will be created.
    3. Click the 'Edit' link next to 'Copy of Default Permission Scheme'. On the 'Edit' screen,
      1. change the 'Name' to 'Software Development Permission Scheme'
      2. change the 'Description' to 'Permission scheme for software development projects'. Then click the 'Update' button.
    4. Click the 'Permissions' link next to 'Copy of Default Permission Scheme'. On the 'Edit Permissions' screen,
      1. for the 'Close Issues' permission, click the 'Delete' link next to 'Project Role (Developers)'.
      2. for the 'Close Issues' permission, click the 'Add' link. Click 'Project Role' and choose 'Quality Assurance'. Then click the 'Add' button.
  3. Associate the 'Software Development Permission Scheme' with all your software development projects. Do the following for each relevant project:
    1. Click 'Projects' in the left navigation column. Then in the 'Name' column, click the name of the relevant project. The project details will be displayed.
    2. Click the 'Select' link next to the 'Permission Scheme' field, select 'Software Development Workflow Scheme' and click the 'Associate' button.
  4. For each software development project, add the appropriate people to the 'Quality Assurance' project role:
    1. Click 'Projects' in the left navigation column. Then in the 'Name' column, click the name of the relevant project. The project details will be displayed.
    2. Click the 'View members' link next to 'Project Roles'.
    3. Select the 'Edit' link next to 'Quality Assurance' and add the appropriate people.

Or, to add a new permission scheme called 'Software Development Permission Scheme', and a group called 'quality-assurance':

  1. Create a group called 'quality-assurance', and add the appropriate people to it.
    1. Click 'Administration' in the top navigation bar.
    2. Click 'Groups' (under 'Users, Groups and Roles') in the left column.
    3. In the 'Name' field, type 'quality-assurance'. Then click the 'Add Group' button.
  2. Create a permission scheme called 'Software Development Permission Scheme', in which you assign the 'Close Issue' permission to the 'quality-assurance' group.
    1. Click 'Permission Schemes' (under 'Schemes) in the left column.
    2. Click the 'Copy' link next to 'Default Permission Scheme'. A new permission scheme called 'Copy of Default Permission Scheme' will be created.
    3. Click the 'Edit' link next to 'Copy of Default Permission Scheme'. On the 'Edit' screen,
      1. change the 'Name' to 'Software Development Permission Scheme'
      2. change the 'Description' to 'Permission scheme for software development projects'. Then click the 'Update' button.
    4. Click the 'Permissions' link next to 'Copy of Default Permission Scheme'. On the 'Edit Permissions' screen,
      1. for the 'Close Issues' permission, click the 'Delete' link next to 'Project Role (Developers)'.
      2. for the 'Close Issues' permission, click the 'Add' link. Click 'Group' and choose 'quality-assurance'. Then click the 'Add' button.
  3. Associate the 'Software Development Permission Scheme' with all your software development projects. Do the following for each relevant project:
    1. Click 'Projects' in the left navigation column. Then in the 'Name' column, click the name of the relevant project. The project details will be displayed.
    2. Click the 'Select' link next to the 'Permission Scheme' field, select 'Software Development Workflow Scheme' and click the 'Associate' button.

15. Installing Plugins

  Why would I do this? (click to expand)

You can install plugins to add new functionality to JIRA (e.g. additional gadgets or reports), or to change the behaviour of existing features.

  How do I do this? (click to expand)

Once you have downloaded or created your plugin jar file, follow these steps to install it in your JIRA instance:

  1. Shut down JIRA.
  2. Copy your plugin jar (e.g. 'EXAMPLE_PLUGIN.jar') into the appropriate plugins directory:
    • If you are installing a 'Version 1' plugin, copy the jar into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
    • If you are installing a 'Version 2' (OSGi) plugin, copy the jar into your JIRA home directory under plugins/installed-plugins/.
      (info) To find out whether a plugin is Version 1 or Version 2, check the Plugin Exchange. Note that plugins have different versions, and older builds of plugins may be Version 1.
  3. Start up JIRA.
  4. Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will be listed and enabled.
For more details please see the documentation.

Important Next Steps

(Note that you need to be an Administrator to do the tasks in this section.)

16. Connecting to an External Database

Before using JIRA as a production system, you need to switch from the default HSQL database, which is provided for evaluation purposes only. Please see the documentation for details.

17. Backing up Data

To back up your JIRA data, and establish processes for regular backups, please see the documentation.

Thank you for using JIRA.

Thanks for choosing JIRA. We're always happy to help. Feel free to email or call us with any questions you have.