376
JIRA Documentation 1. Documentation 1.1. JIRA 3.5.x Documentation This section has documentation on installing, using and administering JIRA. Developers and admins looking to extend JIRA should also consult the JIRA Space in Confluence. Here are some pointers to get you started: Not yet downloaded JIRA? You can get it from the JIRA download page. Setting up or installing JIRA? Start with the requirements and installation guide. Upgrading JIRA? Follow the upgrading docs. Don't forget to set up an external database. To learn about JIRA the best place to start is with the basic concepts of issues and projects. Having problems or errors with JIRA? See debugging problems. Looking to extend JIRA? Read extending JIRA or browse the API docs, before consulting the JIRA Space in Confluence. The FAQ should cover any other questions you have. The documentation can also be viewed in PDF format, or downloaded as XML source for custom intranet deployments. If you have any questions about JIRA after reading the documentation here, the best place to start is the mailing list. JIRA's documentation is an ongoing effort and we are constantly trying to improve it. If you have any suggestions about areas you'd like better documented, or ideas about how to improve the existing docs - please contact us. 2. Installing JIRA 2.1. JIRA Requirements JIRA is a 'web application', meaning it runs centrally on a server, and users interact with it through web browsers from any computer. Most requirements therefore relate to the server, and software running on it. 2.1.1. Software requirements JIRA is distributed in two formats, Standalone and WAR/Webapp. with different installation requirements: The Standalone distribution requires Java ( installation guide). JIRA Standalone comes with a built-in application server and database, and is the preferred format for new users. The WAR/Webapp distribution requires Java ( installation guide), an application server and a database. 2.1.1.1. Recommendations We strongly recommend using JIRA Standalone as it is well tested and much easier to install than the WAR/Webapp distribution. JIRA Standalone is shipped with the Apache Tomcat application server which is a stable, light weight and fast performing server. Unless you have a strong preference, or an obligation, to use another application server please use JIRA Standalone. JIRA Standalone ships with a built-in database, however, for production environments we Page 1 Copyright © 2002-2005 Atlassian All rights reserved.

Jira Manual

Embed Size (px)

Citation preview

Page 1: Jira Manual

JIRA Documentation

1. Documentation

1.1. JIRA 3.5.x Documentation

This section has documentation on installing, using and administering JIRA. Developers andadmins looking to extend JIRA should also consult the JIRA Space in Confluence.

Here are some pointers to get you started:

• Not yet downloaded JIRA? You can get it from the JIRA download page.• Setting up or installing JIRA? Start with the requirements and installation guide.• Upgrading JIRA? Follow the upgrading docs. Don't forget to set up an external database.• To learn about JIRA the best place to start is with the basic concepts of issues and projects.• Having problems or errors with JIRA? See debugging problems.• Looking to extend JIRA? Read extending JIRA or browse the API docs, before consulting the

JIRA Space in Confluence.• The FAQ should cover any other questions you have.

The documentation can also be viewed in PDF format, or downloaded as XML source for customintranet deployments.

If you have any questions about JIRA after reading the documentation here, the best place to startis the mailing list.

JIRA's documentation is an ongoing effort and we are constantly trying to improve it. If you haveany suggestions about areas you'd like better documented, or ideas about how to improve theexisting docs - please contact us.

2. Installing JIRA

2.1. JIRA Requirements

JIRA is a 'web application', meaning it runs centrally on a server, and users interact with itthrough web browsers from any computer. Most requirements therefore relate to the server, andsoftware running on it.

2.1.1. Software requirements

JIRA is distributed in two formats, Standalone and WAR/Webapp. with different installationrequirements:

• The Standalone distribution requires Java (installation guide). JIRA Standalone comes witha built-in application server and database, and is the preferred format for new users.

• The WAR/Webapp distribution requires Java (installation guide), an application server anda database.

2.1.1.1. Recommendations

We strongly recommend using JIRA Standalone as it is well tested and much easier to installthan the WAR/Webapp distribution. JIRA Standalone is shipped with the Apache Tomcatapplication server which is a stable, light weight and fast performing server. Unless you have astrong preference, or an obligation, to use another application server please use JIRA Standalone.

JIRA Standalone ships with a built-in database, however, for production environments we

Page 1Copyright © 2002-2005 Atlassian All rights reserved.

Page 2: Jira Manual

recommend configuring JIRA Standalone to use an external database. JIRA supports mostrelational database servers and therefore we suggest using the one you are most comfortableadministering. If you are looking for a low cost solution, please consider using MySQL orPostgreSQL as both of these are open source (free) software.

JIRA also requires access to a local disk for certain functionality. If JIRA does not have read andwrite access to disk, searching and attachments will not work. We strongly recommend that diskaccess is available at all times.

Note:JIRA Standalone requires Java to be installed. Please follow this document to install Java before you proceed with installing JIRA.The WAR distribution of JIRA also requires Java to run, however you probably have it already installed if you are using anotherapplication server.

2.1.2. Browser requirements

JIRA will work with any modern browser (IE 6, Mozilla, Firefox, Opera, Safari etc). All of themain functionality will work in IE 5.5, however some of the visual effects will be missing, as IE5.5 is becoming quite dated and does not support web standards that are in common use today.

Note:To get the full experience JIRA has to offer you should enable javascript in your browser. You will still be able to use all the corefeatures of JIRA with javascript disabled, but some features such as adding issue types per project and the preview for the wikirenderer will not work.

2.1.3. Hardware requirements

The hardware required to run JIRA heavily depends on the number of issues and users that yourinstallation will have, as well as the maximum number of concurrent requests that the system willexperience during peak hours.

During evaluation JIRA will run well on any reasonably fast workstation computer (eg. 1.5+Ghzprocessor). Memory requirements depend on how many projects and issues you will store, but256MB is enough for most evaluation purposes.

Most users start by downloading JIRA Standalone, and running it on their local computer. It iseasy to move JIRA to a central server later.

If you are planning to have a small number of projects (10-20) with 1,000 to 5,000 issues in totaland about 100-200 users, a recent server (2.8+GHz CPU) with 256-512MB of RAM free shouldcater for your needs.

If you are planning for a greater number of issues and users, adding more memory will help. Wehave reports that allocating 1GB of RAM to JIRA is sufficient for 100,000 issues.

If your system will experience a large number of concurrent requests, running JIRA on amulti-CPU machine will increase the concurrency of processing the requests, and therefore speedup the response time.

For reference, jira.atlassian.com has 14,000 issues and 10,000 users. During peak loads thesystem experiences about 30 requests for pages per minute. The system runs on a dual 2.8GHzXeon machine and is allocated up to 450MB of RAM.

We would appreciate if you let us know what hardware configuration works for you. Pleasecreate a ticket in our support system with your hardware specification and mention the number ofusers and issues in your JIRA installation.

JIRA Documentation

Page 2Copyright © 2002-2005 Atlassian All rights reserved.

Page 3: Jira Manual

2.2. Installing Java

JIRA requires a Java Development Kit (JDK) 1.3 or above to run. This may be obtained from Sun'swebsite (get the 'offline' edition if you're using Windows).

Some JDK version notes:

• To build JIRA from source, you will need JDK 1.4 or above• Older JIRA releases (JIRA 3.1.1 and earlier) do not work 100% with JDK 1.5 due to a JDK bug

that affects filter subscriptions. The problem has been worked around in JIRA 3.2 and above.• For FreeBSD, you'll need JDK 1.4.2-p5 or above.

2.2.1. Set JAVA_HOME

Once the JDK is installed, you will need to set the JAVA_HOME environment variable, pointing tothe root directory of the JDK. Some JDK installers set this automatically (check by typing 'echo%JAVA_HOME%' in a DOS prompt, or 'echo $JAVA_HOME' in a shell). If it is unset, set it by handin the Control Panel.

1. Right click on the My Computer icon on your desktop and select properties2. Click the Advanced Tab3. Click the Environment Variables button4. Click New5. Enter JAVA_HOME as the variable name and the directory where you installed Java.

Setting JAVA_HOME in Windows

JIRA Documentation

Page 3Copyright © 2002-2005 Atlassian All rights reserved.

Page 4: Jira Manual

2.2.2. Confirm Java works

When the above steps have been done correctly, it should be possible to open a DOS prompt andtype %JAVA_HOME%\bin\javac, and see this printed:Usage: javac <options> <source files>where possible options include:...

2.2.3. Where to now?

You're now set to run JIRA Standalone - download it if you haven't already, and proceed to theInstall Guide. Once installed, you may wish to configure JIRA Standalone to use an externaldatabase, or you can switch databases later.

If you are installing JIRA into an existing app server and database (i.e. you have theWAR/Webapp edition of JIRA), you should proceed to the application server guide, and then tothe database guide.

2.3. Install Guide

JIRA is distributed in two different formats.

1. Standalone - Bundled with an application server and database, the standalone version runsout of the box, once you have installed Java.

2. WAR/EAR - Deployable as a WAR or EAR inside any J2EE application server or servletcontainer (for which you need Java, a new or existing application server and database).

2.3.1. 1. Installing JIRA Standalone

To install JIRA Standalone, follow these steps:

1. Unzip the downloaded file. On Windows, this is trickier than it sounds. Firstly avoid WinXP's built in unzip as it doesn't extract all the files. Secondly, extract JIRA to 'c:\' or anothershort path to avoid Windows path size limitations. Finally, if you downloaded JIRA 3.2.2or earlier (not 3.3.3) and use WinZIP 9, please manually create a temp\ directory in theroot directory (alongside bin\, conf\ etc), as WinZIP doesn't extract this (resulting in indexerrors).Solaris users will need to use GNU tar to handle the long filenames.

2. Run the startup script:• On Windows, run bin/startup.bat (try bin/catalina.bat run if that

immediately exits), or• On Unix/Linux, run bin/startup.sh. Logs will be written to

logs/catalina.out.3. Point a web browser at http://localhost:8080, where you should see the setup wizard. If you

see something else, you may need to change the port JIRA runs on.

If something goes wrong, please verify that Java is installed correctly. If the problem persists,please contact us - we're happy to help.

Assuming everything works, where to from here?

• JIRA Standalone uses an in-memory HSQL database engine. We strongly recommend thatyou use an external database for production JIRA instances.

• For JIRA to be started and stopped when the host server does so, you can install JIRAStandalone as a service.

2.3.2. 2. Installing JIRA as a WAR / EAR

JIRA Documentation

Page 4Copyright © 2002-2005 Atlassian All rights reserved.

Page 5: Jira Manual

The distribution ZIP file contains an Ant build script to create a deployable EAR or WAR for yourparticular application server (and any necessary library directories).

The basic set of steps to install JIRA WAR/EAR is as follows:

1. Download and unzip JIRA (but not with XP's unzipper) if you have not already done so.2. Follow the instructions in the readme.txt file, located in the root directory of the unpacked JIRA

distribution. This refers to the server-specific install guides.3. Access JIRA using your web browser and run through the brief setup wizard.

2.3.2.1. Increasing application server memory

For production use, please check that your application server is allocated sufficient memory. Javaapps claim up to only 64Mb by default, and this usually isn't enough for JIRA. See the IncreasingJIRA memory page for more information.

2.3.3. Avoid Windows XP's built-in unzip tool!

The built-in unzip tool in Windows XP is broken - it silently fails to extract files with long names(see JRA-2153). Other users have also reported problems using WinRAR. Please use another toollike WinZIP to unpack JIRA.

2.4. Setup Wizard

After you have installed JIRA, and accessed its URL (eg. http://localhost:8080 orhttp://localhost:8080/jira) for the first time, you will be presented with a brief setup wizard toconfigure JIRA.

2.4.1. Step 1 of 3: Application Properties

The first page of the wizard looks like this:

JIRA Documentation

Page 5Copyright © 2002-2005 Atlassian All rights reserved.

Page 6: Jira Manual

Application properties setup page, prompting for Application Title, Mode, Base URL andLicense Key

On this page you can set some of the JIRA configuration settings, and enter your license key.We recommend that you specify a backup path as this will allow Jira to periodically backup the

JIRA Documentation

Page 6Copyright © 2002-2005 Atlassian All rights reserved.

Page 7: Jira Manual

database.

For more details on the settings and what they mean, see Configuring JIRA.

You can obtain an evaluation license key which will allow JIRA to run unrestricted for 30 days.

2.4.2. Step 2 of 3: Administrator Account

After completing the first page, the second page of the wizard sets up an administrator account:

Admin account setup page, prompting for username, password, name and emailOnce this initial administrator account is created, that administrator can then create otheradministrators.

2.4.3. Step 3 of 3: Email Notification

The last page of the setup wizard allows you to configure the outgoing emails from JIRA.

JIRA Documentation

Page 7Copyright © 2002-2005 Atlassian All rights reserved.

Page 8: Jira Manual

JIRA Documentation

Page 8Copyright © 2002-2005 Atlassian All rights reserved.

Page 9: Jira Manual

Email notification setup page prompting for configuration detailsTo disable email notifications (you can always enable them later), just click the Disable EmailNotifications button.

For the outgoing mail server choice, you must either specify the JNDI location of ajavax.mail.Session object (usually provided by your application server) or specify thelocation of an SMTP server.

Once you complete this step, JIRA should be set up and ready for use.

2.5. JIRA Standalone

2.5.1. JIRA Standalone: using an external database

JIRA Standalone uses the HSQL database engine for persistent storage of issues. This is generallyfine for light to medium usage, but for larger installs, you should preferably use an enterprisedatabase. Many companies do this in order to take advantage of existing database backup andrecovery procedures. Also, as HSQL stores all data in-memory (operations logged to disk in case offailure), there is an upper cap on the amount of issue data that can be stored.

To modify JIRA Standalone to use an external database, do the following:

1. In your database:

1. Create a user which JIRA will connect as (e.g. jirauser).2. Create a database for JIRA to store issues in (e.g. jiradb).3. Ensure that the user has permission to connect to the database, and create and populate tables

2. Add the JDBC driver jar for your database to the common/lib/ directory. [download driver]

3. Edit conf/server.xml, and customize the username, password, driverClassName, and urlparameters for the Datasource (here assuming MySQL). Please refer to one of the sections belowthat applies to your database for more information.

<Server port="8005" shutdown="SHUTDOWN">

<Service name="Catalina">

<Connector port="8080"maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" />

<Engine name="Catalina" defaultHost="localhost"><Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">

<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="true"><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"username="[enter db username]"password="[enter db password]"driverClassName="com.mysql.jdbc.Driver"url="jdbc:mysql://localhost/jiradb?autoReconnect=true"[ delete the minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis params here ]/>

<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>

<Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false"/></Context>

</Host></Engine>

</Service></Server>

JIRA Documentation

Page 9Copyright © 2002-2005 Atlassian All rights reserved.

Page 10: Jira Manual

4. In conf/server.xml, delete the minEvictableIdleTimeMillis andtimeBetweenEvictionRunsMillis attributes, which are only needed for HSQL, and hurtperformance otherwise.

5. Edit atlassian-jira/WEB-INF/classes/entityengine.xml, and change thefield-type-name attribute to the value for your database (valid values are listed in thefile). As noted in the comment, other databases/appservers may require otherentityengine.xml changes:

<!-- DATASOURCE - You will need to update this tag for your installation.

1. Update field-type-name attribute to match your database.Possible values include: cloudscape, db2, firebird, frontbase, hsql, mckoidb, mysql, mssql, oracle, postgres, postgres72, sapdb, sybase2. If using Orion, JBoss or Jetty you will need to customize the <jndi-jdbc> tag.See http://www.atlassian.com/software/jira/docs/latest/servers/

3. If using Postgres 7.3+ (schema-aware), add:schema-name="public"

to the datasource attribute list below.If using DB2, add:

constraint-name-clip-length="15"to the datasource attribute list below, and an appropriate schema-name attribute, eg:schema-name="DB2INST1"

--><datasource name="defaultDS" field-type-name="mysql"

helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"...

If you forget to do this and start JIRA, it may create database tables incorrectly. See this pageif this happens to you.

2.5.1.1. Oracle

For Oracle, VARCHAR2 text fields have a maximum size of 4000 characters. This createsproblems if you are working with issues that have long descriptions, comments or custom fieldvalues. The limitation also greatly reduces the ability to use custom workflows. FortunatelyOracle have worked around the VARCHAR2 limitation in their latest Oracle 10g JDBC driver.This fix works with Oracle 9 and 10. Therefore we strongly recommend using Oracle 10g driversif you are using Oracle 9 or 10.

Oracle 9i and 10g

If you are using Oracle 9i please use Oracle 10g JDBC drivers as they are required for for thisconfiguration.

Obtain driver from $ORACLE_HOME/jdbc/lib/ - if you are usingOracle 10gOracle's site - if you are using Oracle 9i (Pleaseensure that you use the 10g driver (Release 1)-it is about 1.3MB in size where as the wrong 9idriver is 1.14MB)

jar name(s) classes12.jar - if you are using JDK 1.3ojdbc14.jar - if you are using JDK 1.4 or above.Note: the file size should be 1,536,979 (10gR2).The Oracle 9 drivers have the same name anddo not support CLOBs.WARNING: We had reports from users that the10.2.0.1.0 version of the JDBC driver hangs withsome databases. The 10.1.0.4 version does nothave this problem.

JIRA Documentation

Page 10Copyright © 2002-2005 Atlassian All rights reserved.

Page 11: Jira Manual

driverClassName oracle.jdbc.driver.OracleDriver

url example jdbc:oracle:thin:@localhost:1521:jiradb

Warning:WARNING: We had reports from users that the 10.2.0.1.0 version of the JDBC driver hangs with some databases. The 10.1.0.4 versiondoes not have this problem.

When editing the atlassian-jira/WEB-INF/classes/entityengine.xml file, pleaseset the field-type-name to oracle10g and not oracle.

Note:The field-type-name must be set to oracle10g for this configuration to work.

In your app server configuration (eg. conf/server.xml for Tomcat/JIRA Standalone), add thefollowing parameter to the datasource definition:

<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="true"><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"username="jirauser"password="jirapassword"driverClassName="oracle.jdbc.driver.OracleDriver"url="jdbc:oracle:thin:@localhost:1521:jiradb"connectionProperties="SetBigStringTryClob=true" />

<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>

<Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false"/></Context>

If you are using another application server please see the following document regarding setting theSetBigStringTryClob parameter.

Note:If you are using Orion or OC4J (Oracle iAS) please read through the following document, as the instructions differ slightly for these appservers.

Note:The SetBigStringTryClob property needs to be set to true to store text of unlimited size in the database. If this property is not set,Oracle will only store stings up to 32K bytes in size.

Oracle 8

Due to the limitation of the VARCHAR2 field we strongly recommend upgrading to Oracle 9i or10g and using Oracle 10g JDBC drivers as described in the above section..

Obtain driver from $ORACLE_HOME/jdbc/lib/

jar name(s) classes12.zip (rename this!). Check the JDBCFAQ for more info.

driverClassName oracle.jdbc.driver.OracleDriver

url example jdbc:oracle:thin:@localhost:1521:jiradb

Warning:When using Oracle 8 please use Oracle 8 drivers (e.g. 8.1.7) as we have had numerous problem reports about corrupted data when usingOracle 9 drivers with Oracle 8. There have also been data corruption problems using BEA supplied oracle drivers.

JIRA Documentation

Page 11Copyright © 2002-2005 Atlassian All rights reserved.

Page 12: Jira Manual

Note:Oracle does not support unlimited field lengths, and so certain fields (notably descriptions and comments) are limited to 4000characters. If you are migrating existing data to Oracle, you should check if your data has long fields. To do this, download and runthis XSLT stylesheet against an XML backup of your database.

Warning:Due to the 4000 character limit, JIRA workflows cannot be edited and stored in Oracle 8. We recommend upgrading to Oracle 9i or10g and using Oracle 10g JDBC drivers as described in the section above.. However if you need to use Oracle 8 there is aworkaround involving storing workflows on disk.

Note:Tomcat expects jars in common/lib to have a .jar extension, so for instance, the classes12.zip file should be renamed toclasses12.jar

2.5.1.2. DB2

Obtain driver from The DB2 JDBC driver is shipped with DB2.

jar name(s) db2jcc.jar

driverClassName com.ibm.db2.jcc.DB2Driver

url example jdbc:db2://localhost:50000/jiradb

Note:DB2 is database schema-aware, so a schema-name attribute has to be specified for the <datasource> tag inentitymodel.xml. Set the value of the schema-name attribute to the name of the schema you are using for JIRA's databasetables.

Note:Some versions of DB2 enforce a maximum length of 18 characters for a column name. However, the OFBiz entity-engine generatescolumn names for primary keys based on the table name - so if the table name is longer than 15 characters, DB2 will not create thetable. The solution is to modify the entitymodel.xml and add a constraint-name-clip-length attribute to the<datasource> tag in entitymodel.xml. Set the value of the constraint-name-clip-length attribute to 15.

Note:At least some versions of DB2 require the length of CLOBs and BLOBs to be explicitly set inWEB-INF/classes/entitydefs/fieldtype-db2.xml (BLOB to BLOB(1000) and CLOB to CLOB(2000)). See JRA-4912.

Note:A user reports that DB2 on z/OS will not work with JIRA, as the SQL format differs. "UDB on LUW will automatically define indexspaces etc, where as on z/OS you define them via DDL."

Here is an example of the <datasource> definition in entitymodel.xml:<datasource name="defaultDS" field-type-name="db2"

schema-name="DB2INST1"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"constraint-name-clip-length="15"><jndi-jdbc jndi-server-name="default" jndi-name="java:comp/env/jdbc/JiraDS">

</datasource>

JIRA Documentation

Page 12Copyright © 2002-2005 Atlassian All rights reserved.

Page 13: Jira Manual

2.5.1.3. MySQL

Obtain driver from MySQL Connector/J 3.1.12 (tar.gz or zip).NOTE: the older 3.1.11 driver is broken.

jar name(s) mysql-connector-java-3.x.x-bin.jarNOTE: Do not place the Debug Driver(mysql-connector-java-3.x.x-bin-g.jar) on theCLASSPATH as this can cause issues(JRA-8674).

driverClassName com.mysql.jdbc.Driver

url example jdbc:mysql://localhost:3306/jiradb?autoReconnect=true

For installs on Linux, this step-by-step guide may be helpful.

For help with configuring MySQL 4.1 to store non-ASCII characters, this guide may be helpful.

Note:MySQL closes idle connection after 8 hours, so the autoReconnect=true is necessary to tell the driver to reconnect

Note:A user has reported encountering problems using the Resin JDBC driver for MySQL. However, the Connector/J driver from MySQLworks correctly (except for version 3.1.11).

Note:Please refer to the MySQL documentation for details on character encoding.

2.5.1.4. Firebird

Obtain driver from http://firebird.sourceforge.net

jar name(s) firebirdsql.jar

driverClassName org.firebirdsql.jdbc.FBDriver

url example jdbc:firebirdsql:localhost/3050:/opt/firebird/examples/jiradb.fdb

Note:The words TYPE, POSITION and PARAMETER are reserved keywords in Firebird - hence JIRA cannot use them for table columnnames. This can be fixed by editing atlassian-jira/WEB-INF/classes/entitydefs/entitymodel.xml, changing therelevant column names to something else (eg. '_type'), and then restarting with a clean database.

Note:A constraint within Firebird does not allow key sizes to be greater than 250. Hence, theatlassian-jira/WEB-INF/classes/entitydefs/fieldtype-firebird.xml that ships with JIRA has been modified toadhere to this constraint.

Note:The following page includes modified versions of the entitymodel.xml, taking both of these constraints into consideration and can be usedto run JIRA with a Firebird DB. Due to the indexing restriction, it should be noted that the performance of JIRA is significantly reducedas some indexes have been removed.

2.5.1.5. SQL Server 2000

JIRA Documentation

Page 13Copyright © 2002-2005 Atlassian All rights reserved.

Page 14: Jira Manual

Obtain driver from JTDS (recommended, assumed below), or I-netsoftware (commercial). Note: Microsoft havetheir own JDBC driver but we stronglyrecommend avoiding it after receiving manyreports of intermittent disconnections(JRA-5760, JRA-6872), workflow problems(JRA-8443) and Chinese character problems(JRA-5054).

jar name(s) jtds-[version].jar

driverClassName net.sourceforge.jtds.jdbc.Driver

url example jdbc:jtds:sqlserver://localhost:1433/jiradb

Note:In SQL Server, the database user (jirauser above) should not be the database owner, but should be in the db_owner role. Seehere for details.

2.5.1.6. Mckoi

Notes for using JIRA with Mckoi database are provided separately.

2.5.1.7. MaxDB

This is the database formerly known as SapDB. There is one know issue with both MaxDB 7.5and 7.6, "LONG columns cannot be compared to one another. The contents of LONG columnscannot be compared to character strings or other data types." This kind of query is performedonce within JIRA, in the QuickSearch. This issue only ever effects the quick search when you aresearching for issues that have been moved from their original project to a new project and youare searching on the issue key from the original project. This search will report that the issue doesnot exist when using maxDB. Full details can be found here

MaxDB 7.5

MaxDB 7.5 does not properly support database schema names. We therefore run into theproblem that the JIRA tables are stored at the same level as the system tables of MaxDB. MaxDBcontains a system table named VERSION, JIRA also tries to create a table named VERSION. Tostop JIRA from usurping the system table you should modify youratlassian-jira/WEB-INF/classes/entitydefs/entitymodel.xml, changing<entity entity-name="Version" table-name="version" package-name=""> to <entityentity-name="Version" table-name="jiraversion" package-name="">. This should be done beforeyou first run JIRA against the database so that the tables will be created correctly the first time.

Because JIRA can see all system tables you will notice a warning, such as: Table named"USER_SYS_PRIVS" exists in the database but has no corresponding entity, for eachsystem table. This is not anything to worry about.

Obtain driver from http://dev.mysql.com/get/Downloads/MaxDB/7.5.00/sapdbc-7_6_00_12_4339.jar/from/pick

jar name(s) sapdbc.jar

driverClassName com.sap.dbtech.jdbc.DriverSapDB

url example jdbc:sapdb://localhost/database_name (see alsohttp://dev.mysql.com/doc/maxdb/en/ef/2de883d47a3840ac4ebb0b65a599e5/content.htm)

MaxDB 7.6

JIRA Documentation

Page 14Copyright © 2002-2005 Atlassian All rights reserved.

Page 15: Jira Manual

MaxDB 7.6 does not have the same schema problems as 7.5. If you specify the schema name to bethe same as your db username everything will work normally.<datasource name="defaultDS" field-type-name="sapdb"

schema-name="{DB_USER_NAME}"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"check-indices-on-start="true">

Obtain driver from http://dev.mysql.com/get/Downloads/MaxDB/7.6.00/sapdbc-7_6_00_12_4339.jar/from/pick

jar name(s) sapdbc.jar

driverClassName com.sap.dbtech.jdbc.DriverSapDB

url example jdbc:sapdb://localhost/database_name (see alsohttp://dev.mysql.com/doc/maxdb/en/ef/2de883d47a3840ac4ebb0b65a599e5/content.htm)

2.5.1.8. PostgreSQL

Obtain driver from http://jdbc.postgresql.org/download.html

jar name(s) Depends on version that is downloaded

driverClassName org.postgresql.Driver

url example jdbc:postgresql://host:port/database (see alsohttp://jdbc.postgresql.org/doc.html)

If you are using Postgres 7.3 and above, you will need to editWEB-INF/classes/entityengine.xml to define the schema to use, typically 'public':<datasource name="defaultDS" field-type-name="postgres72"schema-name="public"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"check-indices-on-start="true">

Note:In Postgres 7.1, you will need to edit entitymodel.xml as described in JRA-4929, to avoid an error regarding the POSITION column.This is not necessary in later Postgres releases.

2.5.1.9. Sybase

Obtain driver from http://www.sybase.com/products/middleware/jconnectforjdbc

jar name(s) jconn2.jar

driverClassName com.sybase.jdbc2.jdbc.SybDriver

url example jdbc:sybase:Tds:yourmachinename:portnumber/jiradb

Note:By default Sybase does not allow NULL values for a table's columns - which can be problematic for JIRA.A solution to this issue is to setup the Sybase database used by JIRA to allow NULL values by default, by setting the ALLOW DEFAULTSON option. This procedure is described at:http://manuals.sybase.com/onlinebooks/group-as/asg1250e/svrtsg/@Generic__BookTextView/15380. See also JRA-4815.

JIRA Documentation

Page 15Copyright © 2002-2005 Atlassian All rights reserved.

Page 16: Jira Manual

2.5.1.10. HSQLDB

Obtain driver from http://repository.atlassian.com/hsqldb/jars/hsqldb-1.7.1-patched.jar(the patch is for bug also fixed in the 1.8 series).

driverClassName org.hsqldb.jdbcDriver

url example jdbc:hsqldb:/path/to/jira/database/jiradb(in Tomcat 5.x, use'jdbc:hsqldb:${catalina.home}/database/jiradb'and '${catalina.home}' will be replace with theJIRA path at runtime)

Note: JIRA does not yet work with the latest (1.8) version of hsqldb - see JRA-6824.

2.5.1.11. Switching databases

JIRA data can be migrated between databases. To do this:

1. Create an export of your data as an XML backup2. Alter your JIRA instance to use the new database, following the steps described above. When

restarted, you should see the JIRA setup screen, indicating a blank database.

JIRA Setup screen3. On the setup page, click import your existing data, and restore your data from the

XML backup. Once installed, make sure the index, attachment and backup paths are correct.

2.5.2. Installing JIRA as a Service

For long-term use, the app server hosting JIRA should be configured to survive server restarts.For Windows servers, this means configuring the app server to run as a service. JIRA'sStandalone distribution can be installed as a service as follows:

1. Open a DOS prompt,2. 'cd' to the JIRA Standalone directory, and then the bin\ subdirectory3. If a directory in the path has spaces (eg. 'C:\Program Files\..'), please convert it to its

eight-character equivalent.

4. Ensure the JAVA_HOME variable is set to the JDK base directory, with echo%JAVA_HOME%.

5. Run the following command:

JIRA Documentation

Page 16Copyright © 2002-2005 Atlassian All rights reserved.

Page 17: Jira Manual

service.bat install JIRA6. To have the service start automatically when the server starts, run:

tomcat5 //US//JIRA --Startup auto7. To increase maximum memory JIRA can use (default will already be 256MB) run:

tomcat5 //US//JIRA --JvmMx 5128. To add JVM parameter, for example pass a parameter to enable JIRA's Jelly support, run:

tomcat5 //US//JIRA ++JvmOptions="-Djira.jelly.on=true"

Note:See the Tomcat docs for further service options.

Here is a screenshot of the process:

The process thus farTo change the user that the JIRA service is running as, navigate to the service: Control Panel ->Administrative Tools -> Services. Locate the Apache Tomcat service, right click and view thePreferences.

JIRA Documentation

Page 17Copyright © 2002-2005 Atlassian All rights reserved.

Page 18: Jira Manual

The installed JIRA serviceGo to the "Log On" tab and change the user as desired. You will need to change the user if youare using network drives for backups, attachments or indexes. You must also specify thesenetwork drives by UNC and not letter mappings. E.g. \\backupserver\jira not z:\jira Ensure thatthe %CATALINA_HOME%\*, index and database directories are all writeable by the user theservice is running as.

JIRA should now be installed as a service, but will not automatically start up until the next serverreboot. The JIRA service can be started with the command 'net start JIRA' and stopped with 'netstop JIRA'. The JIRA service can be uninstalled with:service.bat remove JIRA

2.5.2.1. Turning on Verbose GC Logging

Occasionally, it may be useful to view Jira's Garbage Collection information. This is especiallytrue when investigating memory issues.

To turn on the garbage collection logging on execute the following command in the commandprompttomcat5 //US//JIRA ++JvmOptions="-Xloggc:path\to\logs\atlassian-gc.log"

JIRA Documentation

Page 18Copyright © 2002-2005 Atlassian All rights reserved.

Page 19: Jira Manual

The path (denoted by \path\to\) refers to the directory in which JIRA is currently installed. Forexample:tomcat5 //US//JIRA ++JvmOptions="-Xloggc:c:\jira\logs\atlassian-gc.log"

2.6. JIRA Webapp

2.6.1. JIRA Configuration Overview

While the individual server install guides provide specific instructions, it is useful to have an overallconceptual overview of what the configuration process involves.

2.6.1.1. Webapp layout

After downloading and unpackaging the JIRA webapp, one is presented with a directory containing:

appendcp.batbuild.batbuild.shbuild.xmledit-webapp/etc/readme.txttools/webapp/

The build.xml file is an Ant file, which when invoked with the build.(sh|bat) script, willconstruct a deployable webapp. build.xml does this by copying the contents of the webapp/directory, and overwriting it with the contents of edit-webapp/. Thus, never edit files in thewebapp/ directory!. If a file needs editing, first copy it from webapp/path/to/file toedit-webapp/path/to/file, and edit it there.

2.6.1.2. Database configuration

The biggest part of configuring JIRA is connecting it up to a database. In J2EE apps like JIRA, theserver (Tomcat, Orion etc) is responsible for setting up a Database connection factory, and thenmakes this available to the webapp (JIRA) via a lookup API called JNDI. So all the hard work,setting up JDBC URLs, usernames and passwords, is done in the app server. All JIRA needs is theJNDI address where it can find the database connection, in the form of a java.sql.DataSourceobject.

Beyond just getting a database connection, JIRA also needs to know what type of database it isdealing with, so it can issue appropriate SQL commands.

2.6.1.3. Transaction Manager configuration

J2EE apps also rely on a Transaction Manager to coordinate updates across multiple databases.While JIRA does not currently use this facility, JIRA's underlying library (OfBiz) still requires atransaction manager object. As with database connections, this is provided by the application server,as a javax.transaction.UserTransaction object looked up via JNDI.

2.6.1.4. User management configuration

JIRA stores all user profiles in a database table. Occasionally, integration with external usermanagement systems like LDAP is required. This requires some configuration of osuser.xml.See The LDAP Integration guide for more information.

So to recap, JIRA needs to know at least three things:

JIRA Documentation

Page 19Copyright © 2002-2005 Atlassian All rights reserved.

Page 20: Jira Manual

• The JNDI address of its database connection (a java.sql.DataSource object).• What type of database it is dealing with.• The JNDI address of a Transaction Manager (a javax.transaction.UserTransaction object).

This is all done in the entityengine.xml file, as described in the database configurationguide. You'll find a copy of entityengine.xml is edit-webapp/WEB-INF/classes,ready to be edited.

There are a few app servers which, for various reasons, we have been unable to use the normalJNDI lookup procedure to obtain a datasource/transaction manager. See the individual app serverguides for more details on how these are configured — it generally means that moreconfiguration details end up in entityengine.xml.

2.6.2. Entity Engine

The Entity Engine from the OFBiz project is what JIRA uses to persist data to a database. Youcan find out more about why we chose the EE at the bottom of this page. See the configurationoverview for a conceptual overview of what is being done here.

2.6.2.1. Configuring the Entity Engine for JIRA

The configuration of the Entity Engine is done through an XML file calledentityengine.xml. This file is used to define parameters for persistence servers such asJDBC datasource parameters.

For JIRA, this file is located in the distribution atedit-webapp/WEB-INF/classes/entityengine.xml.

As outlined in the overview, the settings which generally need to be configured are:

• Transaction Factory - see below• field type - edit the field-type-name attribute of the <datasource> tag.• datasource location:

• edit the jndi-name attribute of the <jndi-jdbc> tag relevant to your database.• For certain schema-aware databases (Postgres, DB2), add a schema-name attribute

specifying the schema the database uses. See note in entityengine.xml• For databases with table/column name length limits (eg. DB2 on certain platforms), you

may need to set a constraint-name-clip-length parameter. See note in entityengine.xml

Transaction Factory

By default the Entity Engine tries to obtain a JTA transaction factory from the application serverusing JNDI. This table shows the different values for different application servers:

Orion, Tomcat 4.x, Tomcat 5.0 & Weblogic (see also the Orion, Resin, Tomcatand Weblogic guides)

<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="java:comp/UserTransaction"/>

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:comp/UserTransaction"/>

</transaction-factory>Tomcat 5.5 (see also the Tomcat 5.5 install guide)

<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="java:comp/env/UserTransaction"/>

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:comp/env/UserTransaction"/>

JIRA Documentation

Page 20Copyright © 2002-2005 Atlassian All rights reserved.

Page 21: Jira Manual

</transaction-factory>Resin 3 (see also the Resin 3 install guide<transaction-factoryclass="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="java:comp/UserTransaction" />

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:comp/TransactionManager" />

</transaction-factory>JBoss (see also the JBoss 3.x and JBoss 4.x guides)

<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="UserTransaction"/>

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:/TransactionManager"/>

</transaction-factory>Jetty (see also Jetty guide)<transaction-factory class="org.ofbiz.core.entity.transaction.JotmFactory" />

2.6.2.2. Altering the Entity Model

The Entity Model describes the table and column layout that JIRA uses in a database. It can becompletely altered without changing any of the internal workings of JIRA.

The model provided should work with almost any database (care has been taken to ensure thecolumn and table names are SQL compliant).

The entity model is configured through an XML file called entitymodel.xml (located in thedistribution at webapp/WEB-INF/classes/entitydefs/entitymodel.xml). To editthis file, copy it to edit-webapp/WEB-INF/classes/entitydefs/entitymodel.xmland make changes there. When the WAR/EAR is built using build.(sh|bat), the 'edit-webapp' versionof the file will be used.

The format of the file should be fairly self explanatory - basically JIRA always refers to theentity-name and field-name attributes within the code. The type attribute of a <field>tag should always match the type attribute of a <field-type-def> tag in yourfieldtype-*.xml files.

To change where entities and fields are persisted in your database, simply add (or edit) the attributetable-name (for entities) or col-name (for fields).

2.6.2.3. Why we chose the Entity Engine

We chose the EE over CMP or BMP entity beans because:

• it is more portable between application servers• table schemas are automatically created and updated• using the field type definitions, we can add support for new databases very quickly• it is faster than most CMP implementations and has some nice caching features

This document deals with configuring the entity engine for JIRA (but should be applicable to mostapplications). For more details on the entity engine itself and it's inner workings, see:

OFBiz Entity Engine Guidedescribes the theory behind the entity engine, its architecture and usage patternsOFBiz Entity Engine configuration guidedescribes all of the entity engine configuration options, whereas this document justdescribes configuring the entity engine for JIRAAPI Docsthe API docs for the org.ofbiz.entity package

JIRA Documentation

Page 21Copyright © 2002-2005 Atlassian All rights reserved.

Page 22: Jira Manual

2.6.3. Server-specific Guides

2.6.3.1. Installing JIRA in an external app server

The easiest way to get JIRA running is to use the JIRA Standalone distribution, which comespreconfigured with everything you need. However if you already have a Java application serverrunning (and occupying port 80), JIRA can be deployed within it.

JIRA has been successfully tested on the servers in the following table. Each has an individualsetup guide which will help you setup JIRA on it.

Which server should I use?

In terms of performance, Tomcat, Resin and Orion are the fastest. Tomcat and Resin 3.0.9+ areopen-source. Resin and Orion have commercial support.

Application Servers

OrionServer (vendor website)JIRA requires Orion 1.5.4 or above. See the Orion setup guide.Resin (vendor website)JIRA works with Resin 3.0.11 and above. It also works on Resin 2.1 releases up to2.1.8 (where a bug broke compatibility), although there were some problems withinternationalization in the 2.1 series. See the Resin setup guide.Tomcat (vendor website)JIRA will work on Tomcat 5.5.x, 5.0.x, Tomcat 4.1.x and Tomcat 4.0.x (except Tomcat4.0.4). See the respective install guides for Tomcat 5.5.x, Tomcat 5.0.x, Tomcat 4.1.x andTomcat 4.0.x.

Of these, we recommend using the latest 5.0 release, which are fast and well tested.

JBoss (vendor website)JIRA will work on JBoss 4.x, 3.2.3, 3.0 and 2.4.4 (other versions untested but assumed towork).

JBoss bundles an app server (Tomcat or Jetty), and JIRA does not use any of the J2EEcapabilities JBoss provides beyond the app server, so using the bundled app server directly(eg. Tomcat in JIRA Standalone) usually results in a performance gain.

To setup JIRA on JBoss, see the JBoss 3 and JBoss 4 setup guides

Jetty (vendor website)JIRA will run on Jetty 4.0 and above. See the Jetty setup guide.Oracle OC4J (vendor website)JIRA works on OC4J 9.0.3 and later. See the Orion guide for setup assistance.

Weblogic (vendor website)JIRA will run on Weblogic 7.0 Service Pack 2 and 8.1 Service Pack 2. See theWeblogic setup guide.

What about other servers?

Beyond these servers, we also have a generic server setup guide which contains tips for gettingJIRA running on other application servers.

We are actively seeking JIRA users on other application servers so that we can work through any

JIRA Documentation

Page 22Copyright © 2002-2005 Atlassian All rights reserved.

Page 23: Jira Manual

installation issues with them and provide detailed instructions for their server in the distribution.

We strongly believe in J2EE portability and are trying to become the first full J2EE application towork on all J2EE 1.3 servers.

We are currently testing JIRA with the following servers (with varying degrees of success):

• Pramati - 3.0 and 3.5• Weblogic - 6.1 SP2 and 7.0 (JIRA will not run on 6.1 SP2 due to a bug in Weblogic - we have

reported the bug to BEA and it should be fixed in SP3.)• JRun - 4.0. Due to a JRun bug, JIRA will not run on JRun 4 (tested 4.0 sp1a). We have a

prototype JRun 4 configuration guide for one day when this bug is fixed.• Borland Enterprise Server - 5.2.1. This apparently works if you manually remove the

org.xml.sax.* classes from the xmlrpc jar.

We are going to add to our list of compatible servers progressively. If you have a particular serveryou would like to get JIRA tested on, please tell us.

2.6.3.2. Installing JIRA on Orion Server / Oracle OC4J

These instructions will help you install JIRA on OrionServer and Oracle's App Server (OC4J).

This document is relevant to Orion 1.5.4, 1.6.0 and 2.0.x, and OC4J 9.0.4 and above.

1. Unpack JIRA

Download and unzip the JIRA WAR (Webapp ARchive) distribution. A new directory containingJIRA will be created, hereafter referred to as $JIRA_HOME

2. Database configuration

2.1. Copy JDBC driver jar to Orion/OC4J

Download the JDBC driver .jar file for your database (see the list here), and copy it to Orion's thelib/ directory (or OC4J's j2ee/home/applib/). For instance with Postgres, one might have$ORION/lib/pg73jdbc3.jar.

2.2 Orion/OC4J Database configuration

Edit $ORION/config/data-sources.xml (or$OC4J/j2ee/home/config/data-sources.xml) and define a 'datasource' for the databaseyou wish JIRA to use. For example, using Postgres:

<data-sourceclass="com.evermind.sql.DriverManagerDataSource"name="JIRA database"location="jdbc/JiraCoreDS"xa-location="jdbc/xa/JiraXADS"ejb-location="jdbc/JiraDS"connection-driver="org.postgresql.Driver"username="postgres"password="postgresPassword123"url="jdbc:postgresql:jiradb"inactivity-timeout="30"

/>

or for hsqldb (although you shouldn't use it in the long term, it has the virtue of requiring zerosetup):

<data-source

JIRA Documentation

Page 23Copyright © 2002-2005 Atlassian All rights reserved.

Page 24: Jira Manual

class="com.evermind.sql.DriverManagerDataSource"name="JIRA database"location="jdbc/JiraCoreDS"xa-location="jdbc/xa/JiraXADS"ejb-location="jdbc/JiraDS"connection-driver="org.hsqldb.jdbcDriver"username="sa"password=""url="jdbc:hsqldb:/tmp/jiradb"inactivity-timeout="30"

/>

Database details (in bold) will vary depending on database - see this page for other databasedetails.

Warning:Oracle users note: the setBigStringTryClob parameter needs to be passed through to the JDBC driver for JIRA to work fully, butOrion / OC4J do not let this string through. Please see the Oracle 10g JDBC driver notes for a workaround.

2.3. JIRA entityengine.xml configuration

Having installed a JDBC driver and configured a datasource, you now need to tell JIRA where tofind the datasource, and what type of database you're using.

This is done in the edit-webapp/WEB-INF/classes/entityengine.xml file (thesections in bold are the ones you will need to change):

<datasource name="defaultDS" field-type-name="postgres"schema-name="public"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"check-indices-on-start="true"><jndi-jdbc jndi-server-name="default" jndi-name="jdbc/JiraDS"/>

</datasource>

(In this example we're using Postgres, and have added a schema-name="public" attribute asPostgres requires.)

The jndi-name attribute in entityengine.xml must match the ejb-location attribute inyour Orion config/data-sources.xml file. Note the lack of java:comp/env in thejndi-name attribute.

App server modifications

OC4J 9.0.4 users: please also edit config/application.xml, and comment out the '../jsp/lib/taglib'library:<!--

<library path="../jsp/lib/taglib"/>-->

Otherwise you will get errors like this when importing data or upgrading:

2005-11-21 15:07:17,089 ERROR [atlassian.jira.upgrade.UpgradeManagerImpl] Exception thrown during upgrade: org/dom4j/Elementjava.lang.NoClassDefFoundError: org/dom4j/Element

at org.jaxen.dom4j.Dom4jXPath.<init>(Dom4jXPath.java:103)at org.dom4j.xpath.DefaultXPath.parse(DefaultXPath.java:313)at org.dom4j.xpath.DefaultXPath.<init>(DefaultXPath.java:63)at org.dom4j.DocumentFactory.createXPath(DocumentFactory.java:188)

JIRA Documentation

Page 24Copyright © 2002-2005 Atlassian All rights reserved.

Page 25: Jira Manual

at org.dom4j.DocumentHelper.createXPath(DocumentHelper.java:109)at com.atlassian.jira.upgrade.tasks.UpgradeTask_Build92.doUpgrade(UpgradeTask_Build92.java:63)....

This does not apply to OC4J 10.0.2.x

Finally, Orion does not come bundled with a compiler for JSP files. Hence you need to copy tools.jarfrom your JDK lib directory to the Orion directory. This doesn't apply to OC4J.

3. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line, in$JIRA_HOME. This will produce the deployable WAR file in the $JIRA_HOME/dist-genericdirectory. You can copy this elsewhere if you prefer.

4. Deploy JIRA

Edit config/application.xml to add the JIRA webapp to the default application like so:<web-module id="jira" path="$JIRA_HOME/dist-generic/atlassian-jira-3.3.war"/>

(where $JIRA_HOME is the path to your JIRA distribution)

Now bind this "jira" webapp to a website. For example, to add JIRA to the default Orion website editconfig/default-web-site.xml (in OC4J, config/http-web-site.xml) and add the following line:<web-app application="default" name="jira" root="/jira"/>

Where:

• application="default" references the "default" application (application.xml named"default" in server.xml)

• name="jira" references the id="jira" web-module defined in application.xml• root="/jira" is the path off the website JIRA will be visible at, eg.

http://localhost:8888/jira/.

5. Start Orion

Start Orion by using java-Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl -jarorion.jar -userThreads (oc4j.jar for OC4J) in the directory where you installed Orion. Watch thelog/* files for any errors.

Note:The -Djavax... parameter is to force OC4J to use the right XSLT engine - see JRA-8597

JIRA should become accessible at http://localhost/jira/ (using Orion, and assuming thedefault port 80 in default-web-site.xml) or http://localhost:8888/jira (OC4J).

Warning:The -userThreads option is important -- without it, services will fail to run.

Problems?

Here's a list of things to check:

1. Are there any errors in the log/* files? Usually if JIRA isn't starting, messages in the logs can getyou on the right track.

2. Have you got a .jar file for your database in lib/ (Orion) or applib/(OC4J)? In a console, tryrunning 'jar tvf <jar>' and make sure the .jar isn't corrupt, and contains the driver you expect (the

JIRA Documentation

Page 25Copyright © 2002-2005 Atlassian All rights reserved.

Page 26: Jira Manual

'connection-driver' in config/data-sources.xml; eg:

~/apps/oc4j-9.0.4/j2ee/home/applib$ jar tvf pg73jdbc3.jar | grep org.postgresql.Driver6229 Thu Aug 07 10:58:04 EST 2003 org/postgresql/Driver.class

3. Is the JIRA webapp being deployed? Check in the application-deployments/directory - there should be a jira/ subdirectory if the webapp was deployed. If there isn't,check your server.xml and default-web-site/http-web-site.xml files.

4. Are you sure you referenced the ejb-location JNDI name (not xa-location) inentityengine.xml?

5. If Orion seems to be using an old version of your JIRA .ear, delete theapplication-deployments/jira directory and restart. It is a good idea to do thisanyway if you are unsure of the state of things.

If the problems persist, please file a support request, attaching your logs and config files, andwe'll take a look.

2.6.3.3. Installing JIRA on JBoss 3

These instructions will help you install JIRA on JBoss 3.x (with embedded Jetty or Tomcat).These instructions have been tested with JBoss 3.2.3. Earlier releases are not expected to workfully (see JRA-4977, JRA-3667).

There is also separate guide for installing JIRA on JBoss 2.4, but we recommend using JBoss 3.xrather than JBoss 2.4 if you can (though if you have a choice, prefer Tomcat — it is significantlyfaster).

If you're having problems, see debugging JIRA.

1. Configure JBoss

The application server (JBoss) is responsible for establishing a database connection, and makingit available to webapps like JIRA as a "DataSource". JBoss comes with one DataSourcepreconfigured using a built-in hsqldb database. You can see the configuration for this inserver/default/deploy/hsqldb-ds.xml. In the rest of this guide, we assume use ofthis DataSource (called 'DefaultDS').

If you wish to use another database (MySQL, Oracle etc), create another config file in the'deploy' directory, eg server/default/deploy/jira-ds.xml:<?xml version="1.0" encoding="UTF-8"?><!-- DataSource for JIRA webapp,

called 'JiraDS' (must be same in entityengine.xml) --><datasources><local-tx-datasource><jndi-name>JiraDS</jndi-name><connection-url>jdbc:mysql://localhost/jiradb?autoReconnect=true</connection-url><driver-class>com.mysql.jdbc.Driver</driver-class><user-name>jira_mysql_username</user-name><password>jira_mysql_password</password>

</local-tx-datasource></datasources>

Here we have created a MySQL DataSource called 'JiraDS'. We would also have to copy theMySQL JDBC jar to servers/default/lib/. See the database configuration page for details.

1. Configure JIRA

Open the edit-webapp/WEB-INF/classes/entityengine.xml file, and make thefollowing changes:

JIRA Documentation

Page 26Copyright © 2002-2005 Atlassian All rights reserved.

Page 27: Jira Manual

1.1 Modify transaction factory attribute

Make the following changes (in bold) to the <transaction-factory> tag:

<transaction-factoryclass="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="UserTransaction" />

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:/TransactionManager" />

</transaction-factory>

1.2 Modify datasource attributes

Lower down in entityengine.xml, the <datasource> tag needs modifying in two locations:<datasource name="defaultDS"

field-type-name="hsql"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true" use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true">

<jndi-jdbc jndi-server-name="default"jndi-name="java:/DefaultDS"/>

</datasource>• The field-type-name parameter needs to be set appropriately for the type of database you

use.• The jndi-name attribute needs to point to a DataSource to use. As mentioned above, JBoss

comes preconfigured with a "DefaultDS" DataSource, which we assume use of here. If instead,you added the MySQL DataSource above, the jndi-name value would be java:/JiraDS.

2. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line, in thedirectory where you originally extracted JIRA to. This will produce a deployable WAR file in thedist-generic directory.

3. (optional) Remove old deployments

On some versions of JBoss you may need to undeploy any old JIRA EARs/WARs and remove alldeployed files before deploying the new WAR.

4. Deploy the WAR in JBoss

Rename the WAR to jira.war, and drop it into your deployment directory (usuallyjboss/server/default/deploy/). If JBoss is running, you should see messages on theJBoss console saying that it is deploying the WAR.

Note:The version of tomcat that ships with JBoss 3.2.x ships with an earlier version of the commons-collections.jar. JIRA requires thecommons-collections-3.1.jar. You will need to replace the version shipped with the tomcat instance in JBoss (usually found in{JBOSS_HOME}/server/default/deploy/jbossweb-tomcat50.sar/commons-collections.jar) with the version shipped with JIRA (usuallyfound in {JIRA_HOME}/WEB-INF/lib/commons-collections-3.1.jar).

Start JBOSS by running bin/run.bat under the JBoss directory. Watch the startup logs for errors.Once JBoss has started, JIRA should be accessible at http://localhost:8080/jira/(change the host and port as needed; the 'jira' part is whatever the WAR name is).

JIRA Documentation

Page 27Copyright © 2002-2005 Atlassian All rights reserved.

Page 28: Jira Manual

2.6.3.4. Installing JIRA on JBoss 4

These instructions will help you install JIRA on JBoss 4 (with embedded Jetty or Tomcat). Theseinstructions have been tested with JBoss 4.0.1 and 4.0.2. There are separate guides for JBoss 3.xand JBoss 2.4.

Warning:JIRA 3.3 and above will not work on JBoss 4.0.0 due to its broken classloader - see this issue.

If you're having problems, see debugging JIRA.

1. Configure JBoss

The application server (JBoss) is responsible for establishing a database connection, and makingit available to webapps like JIRA as a "DataSource". JBoss comes with one DataSourcepreconfigured using a built-in hsqldb database. You can see the configuration for this inserver/default/deploy/hsqldb-ds.xml. In the rest of this guide, we assume use ofthis DataSource (called 'DefaultDS').

Using HSQL with JBoss 4.0.2

JBoss 4.0.2 comes with hsqldb 1.8RC9 which JIRA does not work with. To fix this you need toreplace the hsqldb.jar. Download hsqldb-1.7.1-patched.jar and replaceserver/default/lib/hsqldb.jar with it.

If you wish to use another database (MySQL, Oracle etc), create another config file in the'deploy' directory, eg server/default/deploy/jira-ds.xml:<?xml version="1.0" encoding="UTF-8"?><!-- DataSource for JIRA webapp,

called 'JiraDS' (must be same in entityengine.xml) --><datasources><local-tx-datasource><jndi-name>JiraDS</jndi-name><connection-url>jdbc:mysql://localhost/jiradb?autoReconnect=true</connection-url><driver-class>com.mysql.jdbc.Driver</driver-class><user-name>jira_mysql_username</user-name><password>jira_mysql_password</password>

</local-tx-datasource></datasources>

Here we have created a MySQL DataSource called 'JiraDS'. We would also have to copy theMySQL JDBC jar to servers/default/lib/. See the database configuration page for details.

1. Configure JIRA

1.1 Modify transaction factory attribute

Modify the transaction factory in the entityengine.xml file, located in theedit-webapp/WEB-INF/classes directory. Changes to be made are shown in bold, to the<transaction-factory> tag:

<transaction-factoryclass="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="UserTransaction" />

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:/TransactionManager" />

</transaction-factory>

JIRA Documentation

Page 28Copyright © 2002-2005 Atlassian All rights reserved.

Page 29: Jira Manual

For JBoss 4.0.3, the following changes should be made - highlighted in bold:<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default" jndi-name="ClientUserTransaction"/><transaction-manager-jndi jndi-server-name="default" jndi-name="java:/TransactionManager"/>

</transaction-factory>

1.2 Modify datasource attributes

JIRA needs to know which DataSource to use. As mentioned above, JBoss comes preconfiguredwith a "DefaultDS" DataSource, which we assume use of here.

Here's the relevant section of the entityengine.xml file:<datasource name="defaultDS"

field-type-name="hsql"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true" use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true">

<jndi-jdbc jndi-server-name="default"jndi-name="java:/DefaultDS"/>

</datasource>

If, for example, you added the MySQL DataSource above, the jndi-name value would bejava:/JiraDS.

2. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line, in thedirectory where you originally extracted JIRA to. This will produce a deployable WAR file in thedist-generic directory.

3. (optional) Remove old deployments

On some versions of JBoss you may need to undeploy any old JIRA EARs/WARs and remove alldeployed files before deploying the new WAR.

4. Deploy the WAR in JBoss

Rename the WAR to jira.war, and drop it into your deployment directory (usuallyjboss/server/default/deploy/). If JBoss is running, you should see messages on theJBoss console saying that it is deploying the WAR.

Start JBOSS by running bin/run.bat under the JBoss directory. Watch the startup logs for errors.Note: in JBoss 4.0.2 you can expect to see one occurrence of a "Could not create an Appender"error, which is harmless - see JRA-6823. Once JBoss has started, JIRA should be accessible athttp://localhost:8080/jira/ (change the host and port as needed; the 'jira' part iswhatever the WAR name is).

2.6.3.5. Installing JIRA on Pramati Server 3.5

These instructions will help you install JIRA on Pramati Server 3.5 SP5 and above..

The instructions detail deploying atlassian-jira-2.6.war from the AdministrationConsole of the Pramati Server 3.5 SP5.

JIRA Install on Pramati Server 3.5 SP5

JIRA Documentation

Page 29Copyright © 2002-2005 Atlassian All rights reserved.

Page 30: Jira Manual

1. Execute rundefaultserver.bat from [pramati_install_dir]/server/binfolder. This batch file launches a browser and opens the Pramati Server administrationconsole. Login to the console as the root user.

2. Click on Configure Resources. Create a JDBC Connection Factory and a datasource(jdbc/JiraDS).

3. Increase the Content Size for Denial of Service to at least 15MB in Admin Console ->Configure -> Global Properties -> Denial Service.

4. Click on Applications -> Web Applications. Click on the Deploy button, browse to thelocation of the WAR and deploy atlassian-jira-2.6.war.

The application should be accessible through the URL:http://localhost:8181/atlassian-jira-2.6.

It is also recommended to use the Jikes compiler with the Pramati Server. To configure Jikes,please change the following tag in deploy-config.xml present in[pramati_install_dir]/server/nodes/default/config/ folder and re-start theserver for the changes to take effect:<compilation><out-of-process-compilation enabled="true"><external-compiler use="jikes" path="C:\jikes-1.18\bin\jikes.exe" /><!--options><property name="initial-heap-size-megabytes" value="120" /><property name="maximum-heap-size-megabytes" value="200" />

</options--></out-of-process-compilation><compilation>

Note:It is also possible to deploy from the server shell or using Pramati Server's deploytool. Please refer to Pramati's deployment guide forinformation about the different modes for deployment.

2.6.3.6. Installing JIRA on Tomcat 4.1.x

This section describes how to install JIRA on Tomcat 4.1.x, a popular open-source server fromthe Apache Jakarta project.

JIRA 3 will work with Tomcat 4.1.27, 4.1.29 and above. It will not fully work with Tomcat4.1.24 and versions earlier in the 4.1.x series (see JRA-4977).

If you have not yet downloaded Tomcat, we recommend you bypass the Tomcat-JIRA configprocess altogether by downloading the Standalone distribution, which comes preconfigured withTomcat 5.5.9.

Tomcat can be downloaded the Apache site, with earlier versions available from the archives.

1. Unpack JIRA

Unzip the JIRA WAR (Webapp ARchive) distribution. A new directory containing JIRA will becreated, hereafter referred to as $JIRA_HOME

2. Configure JIRA

JIRA needs to be told what type of database you'll be using. The database is specified in$JIRA_HOME/edit-webapp/WEB-INF/classes/entityengine.xml. Locate the<datasource> tag near the bottom, and change the field-type-name attribute value:

<datasource name="defaultDS"helper-class="org.ofbiz.core.entity.GenericHelperDAO"

JIRA Documentation

Page 30Copyright © 2002-2005 Atlassian All rights reserved.

Page 31: Jira Manual

field-type-name="hsql"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"><jndi-jdbc jndi-server-name="default"jndi-name="java:comp/env/jdbc/JiraDS" />

</datasource>

Possible values include cloudscape, db2, firebird, hsql, mckoidb, mysql, mssql, oracle, postgres,postgres72, sapdb, and sybase

For Postgres 7.3+ and DB2 you also need to set a schema-name attribute (see the Postgres and DB2pages).

More details on JIRA's database access layer are available on the EntityEngine configuration page.

3. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line in the$JIRA_HOME directory. This will produce the deployable WAR file in the$JIRA_HOME/dist-tomcat directory.

Note:The Tomcat developers, bless them, have bundled commons-logging.jar in common/lib/, causing problems for webapps like JIRA thatalso use commons-logging. For this reason, we generate a separate webapp for Tomcat (in the dist-tomcat/ directory) that does notcontain commons-logging.jar. Please be sure to deploy the correct webapp.

Warning:If you want to copy the WAR file somewhere else, be sure to customise the path to it in jira.xml below. Do not copy this WAR file toTomcat's webapps/ (or server/webapps/) directory, as it would be auto-deployed there in an unconfigured state.

Note:Following an upgrade, some users have encountered exceptions regarding velocity templates that cannot be found. Comments on issuesare also not available - instead the warning "Velocity template generation failed" is displayed. A workaround to this issue is tomanually extract the .war file.

4. Update Tomcat Libraries

Tomcat does not come with some libraries required to run JIRA. To fix this, downloadjira-jars-tomcat.zip (1.2Mb), and copy the contained jars to Tomcat's common/lib/ directory.

If using Tomcat 4.1.27 or earlier: JIRA requires commons-dbcp and commons-pool 1.1 or above.These are included in the extra jars package. Tomcat 4.1.27 and earlier provide old versions of theselibraries, which you will need to remove.

Warning:Since Jira 3.1, Jira has been using a newer version of the javax.mail and javax.activation packages than are shipped with Tomcat 4.1.x. Ifyou run Jira with the shipped jars in place you will encounter a known bug described here when trying to send email. The solution to theproblem is to remove the mail.jar and activation.jar from the TOMCAT_HOME/common/lib directory and replace it with the jars that Jiraships with. Full instructions and details can be found here.

5. Configure Tomcat

A JIRA 'context' now needs to be set up in Tomcat. To do this:

1. Copy dist-tomcat/tomcat-4/jira.xml from the built JIRA distribution to your Tomcat's

JIRA Documentation

Page 31Copyright © 2002-2005 Atlassian All rights reserved.

Page 32: Jira Manual

webapps/ directory.2. Customize the copied jira.xml as follows:

<Context path="/jira" docBase="path/to/atlassian-jira-3.5.2.war" debug="0"><Logger className="org.apache.catalina.logger.FileLogger"

prefix="atlassian-jira." suffix=".log" timestamp="true"/><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/><ResourceParams name="jdbc/JiraDS"><parameter><name>driverClassName</name><value>org.hsqldb.jdbcDriver</value>

</parameter><parameter><name>url</name><value>jdbc:hsqldb:path/to/jira_database</value>

</parameter><parameter><name>username</name><value>sa</value>

</parameter><parameter><name>password</name><value></value>

</parameter>

<!-- NOTE: If NOT using hsqldb, delete the next two parameters --><!-- Give unused connections 4 secs before eviction. --><parameter><name>minEvictableIdleTimeMillis</name><value>4000</value>

</parameter><!-- Check for evictions every 5 secs. --><parameter><name>timeBetweenEvictionRunsMillis</name><value>5000</value>

</parameter><parameter><name>factory</name><value>org.apache.commons.dbcp.BasicDataSourceFactory</value>

</parameter></ResourceParams>

<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"/><ResourceParams name="UserTransaction"><parameter><name>factory</name><value>org.objectweb.jotm.UserTransactionFactory</value>

</parameter><parameter><name>jotm.timeout</name><value>60</value>

</parameter></ResourceParams>

</Context>

The paths (denoted as path/to/) will be correct by default, assuming you want to deploy the .warfrom the dist-tomcat/ directory.

Note:If you are not using hsqldb, make sure you comment out the minEvictableIdleTimeMillis andtimeBetweenEvictionRunsMillis params, or JIRA will run slower than normal.

If you are installing in Windows, make sure that the paths you specify for the location of theWAR file and database are full paths with drive letters (e.g. c:\yourdb\tomcatdb). N.B. the lastpart of the path is the name of the database and is not a directory.

JIRA Documentation

Page 32Copyright © 2002-2005 Atlassian All rights reserved.

Page 33: Jira Manual

Note:Currently JIRA's HTTP sessions may contain objects which cannot be serialized to disk. Tomcat tries to serialize existing sessions bydefault during shutdown. You can add the following configuration parameter between the <Context> tags to disable this:<Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false"/>

Note:So that user and group names in JIRA can contain internationalized characters the property useBodyEncodingForURI within theconnector definition for your http protocol must be set to true. This is the default value for tomcat 4, so you do not need to modify anyvalues, this is not the case for tomcat 5.0.x and 5.5.x. Please note that there is a bug in tomcat versions prior to 4.1.31 that ignores thisvalue. If you want to use i18n characters in JIRA running in tomcat 4 please make sure you are using version 4.1.31 or higher.

Configure the database connection

The example context shown above uses the HSQL in-memory database. To use a different database,copy its JDBC driver jar to common/lib/, and change the context XML appropriately (see thedatabase doc).

Start Tomcat

JIRA should now be ready to run in Tomcat. To start using JIRA, first start (or restart) the Tomcatserver with Tomcat's bin/startup.(sh|bat) scripts, and point your browser tohttp://localhost:8080/jira

You should now see the Setup Wizard, which will take you through the brief setup procedure.

Troubleshooting

It is easy to make a mistake in this process, and even more so if you are trying to connect to adatabase other than hsqldb. First, check that you have followed the process described above:

• If you are using an external database (not hsqldb), have you set the field-type-name attribute in$JIRA_HOME/edit-webapp/WEB-INF/classes/entityengine.xml? (step 1)

• Have you previously started JIRA with an incorrect field-type-name value? If so, the databaseschema would have been created incorrectly.

• Have you copied the extra Tomcat jars (step 4)? Check if you havecommon/lib/objectweb-datasource-1.4.3.jar present.

• If using an external database, did you copy the JDBC driver jar to common/lib/ (step 5)?• Is the path to the .war file in webapps/jira.xml correct?• Have you copied the .war file to Tomcat's webapps/ directory? This is almost guaranteed to

cause pain - please move it elsewhere, and delete any JIRA subdirectories created in webapps/from previous Tomcat starts.

• Have you configured JIRA centrally in conf/server.xml instead of in webapps/jira.xml? This isfine, but then be sure you don't also have a webapps/jira.xml present.

• The log files are usually vital to debugging problems. On Windows, these will appear in theconsole window that loads when running startup.bat, or in one of the log files in thelogs/ directory. On Linux/Unix, logs will appear in a log file in logs/, usuallylogs/catalina.out. Check the log file for errors after startup.

If you're stuck, please raise a support request, and attach your logs, configuration files, plus anythingelse relevant, and we'll get back to you as soon as possible. If you have a general question, try thejira-user mailing list (which Atlassian staff monitor).

2.6.3.7. Installing JIRA on Tomcat 5.0

This section describes how to install JIRA on Tomcat 5.0.x, a popular open-source server from the

JIRA Documentation

Page 33Copyright © 2002-2005 Atlassian All rights reserved.

Page 34: Jira Manual

Apache Jakarta project.

These instructions have been tested with Tomcat 5.0.16, 5.0.19, 5.0.27 and 5.0.28, and areexpected to work with all 5.0 versions.

Tomcat can be downloaded the Apache site.

1. Unpack JIRA

Unzip the JIRA WAR (Webapp ARchive) distribution. A new directory containing JIRA will becreated, hereafter referred to as $JIRA_HOME

2. Configure JIRA

JIRA needs to be told what type of database you'll be using. The database is specified in$JIRA_HOME/edit-webapp/WEB-INF/classes/entityengine.xml. Locate the<datasource> tag near the bottom, and change the field-type-name attribute value:

<datasource name="defaultDS"helper-class="org.ofbiz.core.entity.GenericHelperDAO"field-type-name="hsql"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"><jndi-jdbc jndi-server-name="default"jndi-name="java:comp/env/jdbc/JiraDS" />

</datasource>

Possible values include cloudscape, db2, firebird, hsql, mckoidb, mysql, mssql, oracle,postgres, postgres72, sapdb, and sybase

For Postgres 7.3+ and DB2 you also need to set a schema-name attribute (see the Postgres andDB2 pages).

More details on JIRA's database access layer are available on the EntityEngine configurationpage.

3. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line in the$JIRA_HOME directory. This will produce the deployable WAR file in the$JIRA_HOME/dist-tomcat directory.

Warning:If you want to copy the WAR file somewhere else, be sure to customise the path to it in jira.xml below. Do not copy this WAR fileto Tomcat's webapps/ (or server/webapps/) directory, as it would be auto-deployed there in an unconfigured state.

4. Update Tomcat Libraries

Tomcat does not come with some libraries required to run JIRA. To fix this, downloadjira-jars-tomcat5.zip (1.2Mb), and copy the contained jars to Tomcat's common/lib/ directory.

5. Configure Tomcat

A JIRA 'context' now needs to be set up in Tomcat. To do this:

1. Copy dist-tomcat/tomcat-5/jira.xml from the built JIRA distribution to your Tomcat's

JIRA Documentation

Page 34Copyright © 2002-2005 Atlassian All rights reserved.

Page 35: Jira Manual

conf/Catalina/localhost/ directory.2. Customize the copied jira.xml as follows:

<Context path="/jira" docBase="path/to/atlassian-jira-3.5.2.war" debug="0"><Logger className="org.apache.catalina.logger.FileLogger"

prefix="atlassian-jira." suffix=".log" timestamp="true"/><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/><ResourceParams name="jdbc/JiraDS"><parameter><name>driverClassName</name><value>org.hsqldb.jdbcDriver</value>

</parameter><parameter><name>url</name><value>jdbc:hsqldb:path/to/jira_database</value>

</parameter><parameter><name>username</name><value>sa</value>

</parameter><parameter><name>password</name><value></value>

</parameter>

<!-- NOTE: If NOT using hsqldb, delete the next two parameters --><!-- Give unused connections 4 secs before eviction. --><parameter><name>minEvictableIdleTimeMillis</name><value>4000</value>

</parameter><!-- Check for evictions every 5 secs. --><parameter><name>timeBetweenEvictionRunsMillis</name><value>5000</value>

</parameter><parameter><name>factory</name><value>org.apache.commons.dbcp.BasicDataSourceFactory</value>

</parameter></ResourceParams>

<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"/><ResourceParams name="UserTransaction"><parameter><name>factory</name><value>org.objectweb.jotm.UserTransactionFactory</value>

</parameter><parameter><name>jotm.timeout</name><value>60</value>

</parameter></ResourceParams>

</Context>

The paths (denoted as path/to/) will be correct by default, assuming you want to deploy the .warfrom the dist-tomcat/ directory.

Note:If you are not using hsqldb, make sure you comment out the minEvictableIdleTimeMillis andtimeBetweenEvictionRunsMillis params, or JIRA will run slower than normal.

If you are installing in Windows, make sure that the paths you specify for the location of the WARfile and database are full paths with drive letters (e.g. c:\yourdb\tomcatdb). N.B. the last part of thepath is the name of the database and is not a directory.

JIRA Documentation

Page 35Copyright © 2002-2005 Atlassian All rights reserved.

Page 36: Jira Manual

Configure the database connection

The example context shown above uses the HSQL in-memory database. To use a differentdatabase, copy its JDBC driver jar to common/lib/, and change the context XMLappropriately (see the database doc).

Modify Tomcat server.xml

In order for JIRA to correctly display internationalized characters in user and group names youneed to modify your Tomcat distributions conf/server.xml file. You need to set theproperty useBodyEncodingForURI="true" within the connector definition for your httpprotocol. The connector block should look very much like this:

<Connector port="8080"maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" redirectPort="8443" acceptCount="100"debug="0" connectionTimeout="20000"disableUploadTimeout="true"/>

You should modify the block to contain the addition of the useBodyEncodingForURIproperty:

<Connector port="8080"maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" redirectPort="8443" acceptCount="100"debug="0" connectionTimeout="20000"disableUploadTimeout="true" useBodyEncodingForURI="true"/&gt;

Note:Because you must define this property in at the connector level this setting will effect all web-applications you have deployed underthe connector. This should not adversely effect the other web-applications but please be aware of this. JIRA will run fine without thisproperty set but you will run into issues if a user or group is created which contains international characters. It is best to set thisproperty to true.

Start Tomcat

JIRA should now be ready to run in Tomcat. To start using JIRA, first start (or restart) theTomcat server with Tomcat's bin/startup.(sh|bat) scripts, and point your browser tohttp://localhost:8080/jira

You should now see the Setup Wizard, which will take you through the brief setup procedure.

Troubleshooting

It is easy to make a mistake in this process, and even more so if you are trying to connect to adatabase other than hsqldb. First, check that you have followed the process described above:

• If you are using an external database (not hsqldb), have you set the field-type-name attributein $JIRA_HOME/edit-webapp/WEB-INF/classes/entityengine.xml? (step 1)

• Have you previously started JIRA with an incorrect field-type-name value? If so, thedatabase schema would have been created incorrectly.

• Have you copied the extra Tomcat jars (step 4)? Check if you havecommon/lib/objectweb-datasource-1.4.3.jar present.

• If using an external database, did you copy the JDBC driver jar to common/lib/ (step 5)?• Is the path to the .war file in conf/Catalina/localhost/jira.xml correct?• Have you copied the .war file to Tomcat's webapps/ directory? This is almost guaranteed to

cause pain - please move it elsewhere, and delete any JIRA subdirectories created inwebapps/ from previous Tomcat starts.

JIRA Documentation

Page 36Copyright © 2002-2005 Atlassian All rights reserved.

Page 37: Jira Manual

• Have you configured JIRA centrally in conf/server.xml instead of inconf/Catalina/localhost/jira.xml? This is fine, but then be sure you don't also have aconf/Catalina/localhost/jira.xml present.

• The log files are usually vital to debugging problems. On Windows, these will appear in theconsole window that loads when running startup.bat, or in one of the log files in thelogs/ directory. On Linux/Unix, logs will appear in a log file in logs/, usuallylogs/catalina.out. Check the log file for errors after startup.

If you're stuck, please raise a support request, and attach your logs, configuration files, plus anythingelse relevant, and we'll get back to you as soon as possible. If you have a general question, please trythe jira-user mailing list (which Atlassian staff monitor).

2.6.3.8. Installing JIRA on Tomcat 5.5

This section describes how to install JIRA on Tomcat 5.5, a popular open-source server from theApache Jakarta project.

These instructions have been tested with Tomcat 5.5.4 and JDK 1.5.0-b64. Tomcat can bedownloaded the Apache site.

Note:The JIRA 'Standalone' download is JIRA preconfigured with a copy of Tomcat 5.5.9. If you have JIRA Standalone, you don't need tofollow these docs.

1. Unpack JIRA

Unzip the JIRA WAR (Webapp ARchive) distribution. A new directory containing JIRA will becreated, hereafter referred to as $JIRA_HOME

2. Configure JIRA

JIRA needs to be told what type of database you'll be using. The database is specified in$JIRA_HOME/edit-webapp/WEB-INF/classes/entityengine.xml. Locate the<datasource> tag near the bottom, and change the field-type-name attribute value:

<datasource name="defaultDS"helper-class="org.ofbiz.core.entity.GenericHelperDAO"field-type-name="hsql"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"><jndi-jdbc jndi-server-name="default"jndi-name="java:comp/env/jdbc/JiraDS" />

</datasource>

Possible values include cloudscape, db2, firebird, hsql, mckoidb, mysql, mssql, oracle, postgres,postgres72, sapdb, and sybase

For Postgres 7.3+ and DB2 you also need to set a schema-name attribute (see the Postgres and DB2pages).

Also in entityengine.xml, locate the section:<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory"> <user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/> <transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/> </transaction-factory>

and change this to:<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">

JIRA Documentation

Page 37Copyright © 2002-2005 Atlassian All rights reserved.

Page 38: Jira Manual

<user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/><transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/>

</transaction-factory>

More details on JIRA's database access layer are available on the EntityEngine configurationpage.

3. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line in the$JIRA_HOME directory. This will produce the deployable WAR file in the$JIRA_HOME/dist-tomcat directory.

4. Update Tomcat Libraries

Tomcat does not come with some libraries required to run JIRA. To fix this, downloadjira-jars-tomcat5.zip (1.2Mb), and copy the contained jars to Tomcat's common/lib/ directory.

5. Configure Tomcat

A JIRA 'context' now needs to be set up in Tomcat. To do this:

1. Copy dist-tomcat/tomcat-5.5/jira.xml from the built JIRA distribution to your Tomcat'sconf/Catalina/localhost/ directory.

2. Customize the copied jira.xml as follows:

<Context path="/jira" docBase="path/to/atlassian-jira-enterprise-3.5.2.war" debug="0">

<!-- NOTE: If you use a database other than hsqldb:* delete the minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis attributes* change the database type in atlassian-jira/WEB-INF/classes/entityengine.xml--><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"

username="sa"password=""driverClassName="org.hsqldb.jdbcDriver"url="jdbc:hsqldb:path/to/database/jiradb/"minEvictableIdleTimeMillis="4000"timeBetweenEvictionRunsMillis="5000"/>

<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>

The paths (denoted as path/to/) will be correct by default, assuming you want to deploy the .warfrom the dist-tomcat/ directory.

Note:If you are not using hsqldb, make sure you comment out the minEvictableIdleTimeMillis andtimeBetweenEvictionRunsMillis params, or JIRA will run slower than normal.

If you are installing in Windows, make sure that the paths you specify for the location of theWAR file and database are full paths with drive letters (e.g. c:\yourdb\tomcatdb). N.B. the lastpart of the path is the name of the database and is not a directory.

The above example assumes you are using hsql (an in-memory database - a good choice for afirst attempt). Here is an example using MySQL:

<Context path="/jira" docBase="path/to/atlassian-jira-3.5.2.war"><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"username="jirauser"password="mypassword"driverClassName="com.mysql.jdbc.Driver"

JIRA Documentation

Page 38Copyright © 2002-2005 Atlassian All rights reserved.

Page 39: Jira Manual

url="jdbc:mysql://localhost/jiradb?autoReconnect=true"/><Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"factory="org.objectweb.jotm.UserTransactionFactory"jotm.timeout="60"/>

<Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false"/></Context>

Notice the lack of minEvictableIdleTimeMillis andtimeBetweenEvictionRunsMillis parameters - those should only be used with hsql. Ifusing a different database than hsql, remember to update the field-type-name (see above) copy theJDBC driver jar to common/lib/ (see the database configuration guide).

Modify Tomcat server.xml

In order for JIRA to correctly display internationalized characters in user and group names you needto modify your Tomcat distributions conf/server.xml file. You need to set the propertyuseBodyEncodingForURI="true" within the connector definition for your http protocol. Theconnector block should look very much like this:

<Connector port="8080" maxHttpHeaderSize="8192"maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" redirectPort="8443" acceptCount="100"connectionTimeout="20000" disableUploadTimeout="true"/>

You should modify the block to contain the addition of the useBodyEncodingForURI property:

<Connector port="8080" maxHttpHeaderSize="8192"maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" redirectPort="8443" acceptCount="100"connectionTimeout="20000" disableUploadTimeout="true" useBodyEncodingForURI="true"/>

Note:Because you must define this property in at the connector level this setting will effect all web-applications you have deployed under theconnector. This should not adversely effect the other web-applications but please be aware of this. JIRA will run fine without this propertyset but you will run into issues if a user or group is created which contains international characters. It is best to set this property to true.

Start Tomcat

JIRA should now be ready to run in Tomcat. To start using JIRA, first start (or restart) the Tomcatserver with Tomcat's bin/startup.(sh|bat) scripts, and point your browser tohttp://localhost:8080/jira

You should now see the Setup Wizard, which will take you through the brief setup procedure.

Troubleshooting

It is easy to make a mistake in this process, and even more so if you are trying to connect to adatabase other than hsqldb. First, check that you have followed the process described above:

• If you are using an external database (not hsqldb), have you set the field-type-name attribute in$JIRA_HOME/edit-webapp/WEB-INF/classes/entityengine.xml? (step 1)

• Have you previously started JIRA with an incorrect field-type-name value? If so, the databaseschema would have been created incorrectly.

• Have you copied the extra Tomcat jars (step 4)? Check if you havecommon/lib/objectweb-datasource-1.4.3.jar present.

• If using an external database, did you copy the JDBC driver jar to common/lib/ (step 5)?• Is the path to the .war file in conf/Catalina/localhost/jira.xml correct?• Have you copied the .war file to Tomcat's webapps/ directory? This is almost guaranteed to

cause pain - please move it elsewhere, and delete any JIRA subdirectories created in webapps/from previous Tomcat starts.

JIRA Documentation

Page 39Copyright © 2002-2005 Atlassian All rights reserved.

Page 40: Jira Manual

• Have you configured JIRA centrally in conf/server.xml instead of inconf/Catalina/localhost/jira.xml? This is fine, but then be sure you don't also have aconf/Catalina/localhost/jira.xml present.

• The log files are usually vital to debugging problems. On Windows, these will appear in theconsole window that loads when running startup.bat, or in one of the log files in thelogs/ directory. On Linux/Unix, logs will appear in a log file in logs/, usuallylogs/catalina.out. Check the log file for errors after startup.

If you're stuck, please raise a support request, and attach your logs, configuration files, plusanything else relevant, and we'll get back to you as soon as possible. If you have a generalquestion, please try the jira-user mailing list (which Atlassian staff monitor).

2.6.3.9. Installing JIRA on Caucho Resin 3.x

These instructions will help you install JIRA on Caucho Resin 3.0.9 and above, a high-quality,free (GPL'ed) servlet container from Caucho Technology.

These instructions have been tested with Resin 3.0.9, 3.0.11 and 3.0.15. For Resin 2 releases, seethe Resin 2 install docs. Please let us know if you have any problems on the mailing list.

1. Install Resin

(if you don't already have Resin installed)

Download Resin from http://www.caucho.com/download/index.xtp and expand the distributionto a directory.

2. Configure Resin

2.1 Add extra Resin jars

Resin does not come with a few libraries that JIRA needs to run properly. These files have beenplaced in a zip file that you can download here. Unzip the jars in this file into the resin/libdirectory.

2.2 Define database connection

You'll need to define a database connection (datasource) in Resin for JIRA to use. Openconf/resin.conf and search for 'database' to locate the correct section (after '</web-app-default>').Exactly what text to add depends on what database you use (see database configurations). Herewe assume hsqldb:

<database><jndi-name>jdbc/JiraDS</jndi-name><driver><type>org.hsqldb.jdbcDriver</type><url>jdbc:hsqldb:/tmp/jiradb</url><user>sa</user><password></password>

</driver></database>

Ensure the database driver jar file is in the lib/ directory. The hsqldb jar file (containingorg.hsqldb.jdbcDriver used in the example above) should already be present. Otherdatabase notes and driver details are listed here.

Resin 3.0.9 bugs

Note:

JIRA Documentation

Page 40Copyright © 2002-2005 Atlassian All rights reserved.

Page 41: Jira Manual

Ignore this section if you are running Resin 3.0.11 or above

Resin 3.0.9 has a bug (fixed in 3.0.11) that prevents JIRA CSS stylesheets being used. To workaround this, add the following to conf/app-default.xml, below the similar 'resin-jsp'definition:<servlet servlet-name="jsp"

servlet-class="com.caucho.jsp.JspServlet"><load-on-startup/>

</servlet>

Another Resin 3.0.9 bug causes the logout page to be untranslated. This is fixed in Resin 3.0.11, orsee the workaround on JRA-2685.

3. Configure JIRA

Open the edit-webapp/WEB-INF/classes/entityengine.xml file, and make thefollowing changes:

3.1 Modify transaction factory attribute

Make the following changes (in bold) to the <transaction-factory> tag:

<transaction-factoryclass="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="java:comp/UserTransaction" />

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:comp/TransactionManager" />

</transaction-factory>

3.2 Modify datasource attributes

Lower down in entityengine.xml, check that the field-type-name attribute specifies thecorrect type of database in use, and that the JNDI name (jdbc/JiraDS) is the same as that specifiedin the database definition, eg:

<datasource name="defaultDS" field-type-name="hsql"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"check-indices-on-start="true"><jndi-jdbc jndi-server-name="default" jndi-name="java:comp/env/jdbc/JiraDS"/>

</datasource>

4. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command-line. Thiswill produce the web application to deploy in the dist-generic directory.

5. Deploy JIRA in Resin

You can add the JIRA WAR to resin/resin.conf manually, or just copy it to theresin/webapps directory.

Placing the WAR in the resin/webapps directory should cause Resin to deploy it automaticallywhen Resin starts.

JIRA Documentation

Page 41Copyright © 2002-2005 Atlassian All rights reserved.

Page 42: Jira Manual

Start Resin as follows:export JAVA_ARGS="-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl"cd bin./httpd.sh

Setting JAVA_ARGS avoids a bug in Resin's built-in XML parser which breaks JIRA dataimports.

JIRA should now be accessible at http://localhost:8080/(insert name of yourWAR file).

If certain pages break with errors like this:

Note: sun.tools.javac.Main has been deprecated./jira/secure/views/browser/browseproject.jsp:34: Variable pageContext maynot have been initialized.pageContext.write(_jsp_string4, 0, _jsp_string4.length);^

The solution is to change Resin's compiler from 'internal' to 'javac'. See this Resin FAQ for morebackground.

2.6.3.10. Installing JIRA on Jetty

These instructions will help you install JIRA on Jetty.

These instructions have been tested against Jetty 4.2.9, 4.2.22, 5.0 and 5.1.2, and should apply toother 4.x and 5.x versions. We have not been successful with running JIRA on JettyPlus.

Please let us know if you have any problems (or it works with other versions) on the mailing list.JIRA can also be deployed on JBoss 3 with embedded Jetty - see the JBoss 3.0 guide.

1. Install Jetty

(optional - if you don't already have Jetty installed)

Download Jetty from http://jetty.mortbay.org/jetty/download.html. Get the regular distribution,not the -all distribution. Expand the distribution into a directory.

3. Configure JIRA

3.1 Install extra jars

Jetty does not come with built-in support for DataSources. You will need to download thedependent Jetty jars zip file and unzip into the edit-webapp/WEB-INF/lib directory.

3.2 Install JDBC driver jar

Download the JDBC driver for your database (consult this page), and place the jar file inedit-webapp/WEB-INF/lib/

3.3 entityengine.xml: Change transaction factory

Then edit edit-webapp/WEB-INF/classes/entityengine.xml and locate the<transaction-factory> tag:

<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/>

JIRA Documentation

Page 42Copyright © 2002-2005 Atlassian All rights reserved.

Page 43: Jira Manual

<transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/></transaction-factory>

Replace this with:<transaction-factory class="org.ofbiz.core.entity.transaction.JotmFactory"/>

3.4 entityengine: set database details

Now go to the bottom of entityengine.xml, where you will find the datasource tag. This is wheredatabase details must be specified. Here is what entityengine.xml's datasource section should looklike if using hsqldb:

<datasource name="defaultDS"field-type-name="hsql"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true" >

<inline-jdbc jdbc-driver="org.hsqldb.jdbcDriver"jdbc-uri="jdbc:hsqldb:path/to/jiradb"jdbc-username="sa"jdbc-password=""isolation-level="ReadUncommitted" />

</datasource>

Here is entityengine.xml's datasource section configured for Postgres:

<datasource name="defautDS"helper-class="org.ofbiz.core.entity.GenericHelperDAO"field-type-name="postgres" check-on-start="true"add-missing-on-start="true"><inline-jdbcjdbc-driver="org.postgresql.Driver"jdbc-uri="jdbc:postgresql://127.0.0.1/jira"jdbc-username="postgres"jdbc-password="postgres"isolation-level="Serializable"/>

</datasource>

For the details of other databases, see this page.

4. Build JIRA

Now build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line, in thedirectory you extracted JIRA to. This will produce the deployable WAR file in the$JIRA_HOME/dist-generic directory.

5. Deploy JIRA in Jetty

Placing the WAR in Jetty's webapps/ directory should cause Jetty to deploy it automatically whenJetty starts if you are using the default Jetty configuration file etc/jetty.xml.

To run Jetty using the jetty.xml file use the following command. java-Djava.home=%JAVA_HOME% -jar start.jar etc/jetty.xml

JIRA should now be accessible at http://yourhost.com/atlassian-jira-2.6.1/

6. Running Notes

JIRA Documentation

Page 43Copyright © 2002-2005 Atlassian All rights reserved.

Page 44: Jira Manual

When running Jetty on Redhat 9, be aware that cron periodically deletes the /tmp directory,breaking Jetty.

2.6.3.11. Installing JIRA on BEA WebLogic

BEA Weblogic 7 & 8.1

These instructions will help you install JIRA on Weblogic 7 Service Pack 2 and Weblogic 8.1Service Pack 2. JIRA will not run on previous versions of Weblogic due to Weblogic bugs.(Specifically CR112484 on 8.1). To avoid performance problems, be sure to read theweblogic.xml modifications section.

1. Install WebLogic 7 on your machine (referred herein as $WEBLOGIC_INSTALL)2. Upgrade to Service Pack 23. Create a domain named atlassian using the Domain Configuration Wizard4. Create a server for this domain named jira5. Change the server listener port to 806. Create an admin user for this domain (name = weblogic password = weblogic)7. Create directory "$WEBLOGIC_INSTALL\user_projects\lib"8. Download a JDBC driver for your database (see the external databases list). Copy the JDBC

driver jar file to the directory created in the previous step. In this guide we assume use ofhsqldb, an in-memory database that is a good choice for a first installation. The hsqldb jar(including JDBC driver) is available here or from the hsqldb site.

9. Add the following to the config.xml (here we assume hsqldb; customize for your database:

<Application Deployed="true" Name="_appsdir_jira_dir"Path=".\applications" StagedTargets=""StagingMode="nostage" TwoPhase="true">

<WebAppComponent Name="jira" Targets="jira" URI="jira"/></Application><JDBCConnectionPool DriverName="org.hsqldb.jdbcDriver" Name="hsql"

Properties="user=sa" Targets="jira"URL="jdbc:hsqldb:./database/defaultdb"/>

<JDBCTxDataSource JNDIName="jdbc/JiraDS" Name="hsqlTx"PoolName="hsql" Targets="jira"/>

10.Add the path to the JDBC driver jar file to the Weblogic classpath, by editing"$WEBLOGIC_INSTALL\user_projects\atlassian\startWebLogic.cmd"

set SERVER_NAME=jiraset WLS_USER=weblogicset WLS_PW=weblogicset CLASSPATH=%CLASSPATH%;$WEBLOGIC_INSTALL\user_projects\lib\hsqldb-1.7.1.jar

11.Copy the exploded Atlassian Jira Web App to the directory"$WEBLOGIC_INSTALL\user_projects\atlassian" and make sure the name of the rootdirectory of this project is "jira"

12.Run "$WEBLOGIC_INSTALL\user_projects\atlassian\startWebLogic.cmd"

BEA WebLogic 8.1

These instructions will help you install JIRA on WebLogic 8.1.

1. Configure JIRA

Modify the transaction factory tag in the entityengine.xml file, located in theedit-webapp\WEB-INF\classes directory.

Ensure the <transaction-factory>...</transaction-factory> tag contains:

JIRA Documentation

Page 44Copyright © 2002-2005 Atlassian All rights reserved.

Page 45: Jira Manual

<transaction-factoryclass="org.ofbiz.core.entity.transaction.JNDIFactory"><user-transaction-jndi jndi-server-name="default"jndi-name="java:comp/UserTransaction"/>

<transaction-manager-jndi jndi-server-name="default"jndi-name="java:comp/UserTransaction"/>

</transaction-factory>

Now configure the JNDI path where JIRA will expect to find a database connection factory. This isdone by editing the <datasource> tag at the bottom of entityengine.xml. For example, using mssql,your <datasource> entry would be:

<datasource name="defaultDS" field-type-name="mssql"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true" use-foreign-keys="false"use-foreign-key-indices="false" check-fks-on-start="false"check-fk-indices-on-start="false" add-missing-on-start="true">

<jndi-jdbc jndi-server-name="default" jndi-name="JiraDS"/></datasource>

See the Entity Engine documentation for full details.

2. Generate Weblogic WAR file

Edit build.xml and customise the bea.home or wl.home properties. Then run build.shweblogic.war (Unix) or build.bat weblogic.war (Windows) to generate a WAR file indist-weblogic/

3.Create a datasource on weblogic server

(use console for this)

4. Deploy app to weblogic server

(use console for this)

weblogic.xml settings

Weblogic supports some additional webapp configuration parameters in the weblogic.xml file.This file should be created in the edit-webapp/WEB-INF/ directory of the JIRA distribution.Here is a typical example for Weblogic 8.1:<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 8.1//EN"

"http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd"><weblogic-web-app>

<jsp-descriptor>

<jsp-param><param-name>pageCheckSeconds</param-name><param-value>-1</param-value>

</jsp-param>

<jsp-param><param-name>precompile</param-name><param-value>false</param-value>

</jsp-param>

<jsp-param><param-name>workingDir</param-name><param-value>./jsp_precompile_dir/jira</param-value>

</jsp-param>

JIRA Documentation

Page 45Copyright © 2002-2005 Atlassian All rights reserved.

Page 46: Jira Manual

</jsp-descriptor>

<container-descriptor><servlet-reload-check-secs>-1</servlet-reload-check-secs>

</container-descriptor>

<context-root>jira</context-root>

</weblogic-web-app>

The full weblogic.xml syntax is described in BEA's documentation. Here we describe someimportant parameters you should consider setting.

Disabling JSP reload checks

JIRA's performance is considerably affected by Weblogic's tendency to scan JSPs for changes onevery page load. This can be disabled by setting pageCheckSeconds to -1.

Disabling servlet reload checks

Similar to the JSP reload checks, Weblogic will scan servlets for modifications every second (bydefault), hurting performance. This can be prevented by setting the servlet-reload-check-secselement to -1.

Avoiding JSP recompiles on redeploy

If you Weblogic instance is often restarted, performance can be improved by explicitly setting adirectory to save compile JSPs to (the workingDir parameter), and setting precompile to'false'.

Final notes

• JIRA will not work on WebLogic 6.1. WebLogic 6.1 has filter issues among other things andit is not J2EE 1.3 compliant.

• A user reports, "I am using Weblogic Servers mssql driver and have created an XAconnection pool. To get JIRA to work, you need to have the "Supports Local Transaction"option enabled. This option specifies whether the XA driver used to create physical databaseconnections supports SQL without global transactions.

2.6.3.12. Installing JIRA on IBM Websphere 5

These instructions will help you install JIRA on IBM Websphere 5, noting some deviations fromthe generic install instructions. These tips were provided by a helpful user, and have not yet beentested by Atlassian. Please ask on the mailing list if you need help, or would like to report yourexperiences.

JIRA works on:

• Websphere 5.0• Patched versions of Websphere 5.0.1, 5.0.2 and 5.0.3 (for instance, 5.0.2.3). The unpatched

releases all suffer from a Websphere bug described in JRA-2510, resulting in a blank screenwhen JIRA is deployed

• Websphere 5.1 with the latest fixpacks applied.• Later versions (one presumes)

1. Configure JIRA

Modify ear-application.xml

JIRA Documentation

Page 46Copyright © 2002-2005 Atlassian All rights reserved.

Page 47: Jira Manual

In the unpacked JIRA WAR distribution, edit etc/ear-application.xml, and replace:

<web><web-uri>atlassian-jira-web.war</web-uri><context-root>/jira</context-root>

</web>

With:

<web><web-uri>atlassian-jira-web.war</web-uri><context-root>jira</context-root>

</web>

The / for the context root has been removed as Websphere apparently has problems recognisingthis.

Modify web.xml

Copy webapp/WEB-INF/web.xml to edit-webapp/WEB-INF/web.xml, and add thefollowing section at the end, just before the closing </web-app> tag:

<!-- resource references --><resource-ref><description>Database for JIRA</description><res-ref-name>jdbc/JiraDS</res-ref-name><res-type>javax.sql.DataSource</res-type><res-auth>SERVLET</res-auth>

</resource-ref>

This defines a data source for the JIRA database. This datasource is bound to a concrete JNDI namein the application deployment phase.

Step 3: Configure entityengine.xml

Now edit-webapp/WEB-INF/classes/entityengine.xml may need to be modified tospecify the type of database you will connect to. Here is a snippet of entityengine.xml, with sectionsyou may need to modify in bold.<datasource name="defaultDS" field-type-name="hsql"

helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true"use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"check-indices-on-start="true"><jndi-jdbc jndi-server-name="default" jndi-name="java:comp/env/jdbc/JiraDS"/>

</datasource>

The jndi-jdbc/jndi-name attribute maps to the resource-ref/res-ref-name element defined in web.xml.

2. Build JIRA

Now build JIRA by typing 'build ear' ('./build.sh ear' on Unix) on the command line. This willproduce the deployable EAR file in the dist-generic/ directory.

3. Configure the Websphere datasource

The data source for the database should now be configured in Websphere, and mapped to thejdbc/JiraDS JNDI key.

JIRA Documentation

Page 47Copyright © 2002-2005 Atlassian All rights reserved.

Page 48: Jira Manual

4. Deploy JIRA in Websphere.

The JIRA EAR file can now be deployed to Websphere.

2.6.3.13. Installing JIRA on IBM Websphere 5.1

These instructions will help you install JIRA on IBM Websphere 5.1, noting some deviationsfrom the generic install instructions.

Warning:Please install WebSphere Application Server 5.1 Cumulative Fix 5. Actually, JIRA should only need PQ80592 (and its prerequisites)and PQ87029 applied. PQ80592 resolves a bug that makes all JIRA pages appear blank (JRA-2510). PQ87029 ensures thatimporting data works correctly (JRA-8442). Please note that only Websphere 5.1.0.5 has been tested.

1. Configure JIRA

Unpack JIRA

Unpack JIRA EAR/WAR distribution into a temporary directory.

Configure entityengine.xml

The edit-webapp/WEB-INF/classes/entityengine.xml file needs to be modifiedto specify the correct database field type. The example below is configured for MS SQL Server.

Please ensure that the value of the jndi-jdbc/jndi-name attribute has the "java:comp/env/" prefix.The prefix should be in the file by default.

<datasource name="defaultDS" field-type-name="mssql"helper-class="org.ofbiz.core.entity.GenericHelperDAO"check-on-start="true" use-foreign-keys="false"use-foreign-key-indices="false"check-fks-on-start="false"check-fk-indices-on-start="false"add-missing-on-start="true"><jndi-jdbc jndi-server-name="default" jndi-name="java:comp/env/jdbc/JiraDS"/>

</datasource>

Modify web.xml

Edit webapp/WEB-INF/web.xml file and remove lines:

<!-- Uncomment for WebSphereUncomment for WebSphere -->

which appear towards the bottom of the file. After removing the lines the <resource-ref>entry should look like:

<!-- resource references --><resource-ref>

<description>Database for JIRA</description><res-ref-name>jdbc/JiraDS</res-ref-name><res-type>javax.sql.DataSource</res-type><res-auth>SERVLET</res-auth><res-sharing-scope>Unshareable</res-sharing-scope>

</resource-ref>

JIRA Documentation

Page 48Copyright © 2002-2005 Atlassian All rights reserved.

Page 49: Jira Manual

Please ensure that the res-sharing-scope is set to Unshareable.

2. Build JIRA

Now build JIRA by running the build script for your platform (e.g. build.bat on Windows or build.shon a Unix or Linux system). This will produce the deployable WAR file in the dist-generic directory.

3. Configure the Websphere datasource

The datasource for the database should now be configured in Websphere using the WebsphereAdministration Colsole. When defining the datasource map it to the jdbc/JiraServerDS JNDIkey. Please ensure that the JNDI key is set to jdbc/JiraServerDS and not jdbc/JiraDS.

4. Deploy JIRA in Websphere

The JIRA WAR file can now be deployed to Websphere (by e.g. using the Websphere'sAdministration Console).

When deploying the JIRA WAR file please bind JIRA's jdbc/JiraDS datasource to Websphere'sjdbc/JiraServerDS entry.

Note:Please use the WAR file in dist-generic directory and NOT the dist-tomcat directory.

Warning:Please ensure that WebSphere's "Servlet Caching" is turned off. Otherwise JIRA will die with ClassCastExceptions.

2.6.3.14. Generic Server Installation Guide

If you configure JIRA using a server other than Orion, Oracle, Tomcat or JBoss we want tohear from you!

JIRA should be able to work on any J2EE 1.3 compliant application server or Servlet 2.3 compliantweb container.

The main installation issues are always to do with getting the right files in the right place for theserver so the classpaths are all working correctly, and finding the JNDI locations of various objects.

We're actively seeking JIRA users on other application servers so that we can work through anyinstallation issues with them and provide detailed instructions for their server in the distribution.

If you have problems following this guide on your server, please let us know on the mailing list andwe'll try to help you work them out. Also debugging JIRA might give you some extra helpfulinformation.

We'll now go through the general steps required to install JIRA from the WAR (Webapp ARchive)distribution.

1. Unpack JIRA

Unzip the JIRA WAR (Webapp ARchive) distribution. A new directory containing JIRA will becreated, hereafter referred to as $JIRA_HOME

2. Configure JIRA

JIRA Documentation

Page 49Copyright © 2002-2005 Atlassian All rights reserved.

Page 50: Jira Manual

As described above, we need to edit entityengine.xml to tell JIRA about its database andtransaction manager. Edits should be made toedit-webapp/WEB-INF/classes/entityengine.xml, which will be baked into the.war file when build.(sh|bat) is run. You will need to know the JNDI locations of:

• the javax.transaction.UserTransaction andjavax.transaction.TransactionManager objects, for the transaction manager

• the location of your datasource (if configured via the server).

3. Build JIRA

JIRA can now be built by typing build (Windows) or ./build.sh (Unix) on the command line inthe $JIRA_HOME directory. This will produce the deployable WAR file in the$JIRA_HOME/dist-* directories.

4. Deploy JIRA

Deploy the JIRA EAR or WAR in your application server - consult your server specificdocumentation for how to do this.

5. Bind the JIRA website

JIRA has a single web module called atlassian-jira-web (for later versions, the modulename is the same as the name of the WAR or EAR file that is generated from the ant process).You may need to configure this as a web module within your server.

If you have done these steps properly, the Setup Wizard should show up when you access thepath at which you have deployed JIRA via your web browser.

Again, if you have problems following this guide on your server, please let us know on themailing list and we'll try to help you out.

2.7. Web Server Integration

2.7.1. Integrating with IIS

This page describes how to configure Microsoft's IIS web server and JIRA such that IIS forwardsrequests on to JIRA, and responses back to the user. This is useful if you already have IISrunning serving web pages (eg. http://mycompany.com), and wish to integrate JIRA as justanother URL (eg. http://mycompany.com/jira).

JIRA is written in Java, and needs a Java Application Server (servlet container) to run. As IISdoes not provide services of a Java Application Server, it is not possible to deploy JIRA directlyinto IIS. It is possible, however, to configure IIS to proxy requests for JIRA to an applicationserver where JIRA is deployed. Therefore, if your main website is running in IIS, it is possible tointegrate JIRA into this website.

If you need to integrate JIRA with IIS, JIRA needs to be deployed into a Java Application Serverthat provides IIS integration capability. Apache Tomcat is one of these application servers. TheStandalone distribution of JIRA ships with Apache Tomcat, so if you are using the Standalonedistribution or have deployed JIRA WAR into your own Tomcat instance, please follow thisdocument.

If you are not using the Standalone distribution or Apache Tomcat, please consult yourapplication server's documentation to determine whether it is possible to integrate with IIS andhow to achieve it.

JIRA Documentation

Page 50Copyright © 2002-2005 Atlassian All rights reserved.

Page 51: Jira Manual

To integrate JIRA with IIS you will need to:

1. Configure JIRA and test that it works on its own accord.2. Configure Tomcat to accept proxied requests from IIS.3. Configure IIS to proxy requests to Tomcat (JIRA)

2.7.1.1. Configuring JIRA

1. Follow the JIRA Standalone install guide to install and configure the Standalone distribution ofJIRA or deploy the WAR distribution into Apache Tomcat. JIRA can be installed on the samemachine as IIS, however this is not necessary.

2. Change the context path of the JIRA web application:

To allow IIS to proxy requests to JIRA, JIRA web application must be deployed with a contextpath (eg. the /jira in http://localhost:8080/jira) in Tomcat. The context path must be set to thepath in the URL that IIS will use to proxy requests. For example, if your website is running withaddress www.example.com in IIS, and you would like to make JIRA available underwww.example.com/jira, you will need to set JIRA's context path to "/jira" in Tomcat.

To do this edit the conf/server.xml file if you are using JIRA Standalone or thejira.xml file if you are using the WAR distribution of JIRA. Change the path attribute ofthe Context element to "/jira".

For example, in JIRA Standalone 3.3 and later the Context element would look like:

<Context path="/jira" docBase="${catalina.home}/atlassian-jira"swallowOutput="true" reloadable="false">

3. Restart JIRA after changing the context path.4. Test that JIRA works correctly by pointing your web browser directly at Tomcat (eg.

http://localhost:8080/jira) and going through JIRA's Setup Wizard. If you have completed theSetup Wizard previously, try creating an issue or editing one. Please ensure that no errors occur.

2.7.1.2. Configure Tomcat to accept proxied requests

1. Enable AJP/1.3 Connector in Tomcat:

To allow Tomcat to accept requests for JIRA from IIS, edit the conf/server.xml file andensure that the AJP/1.3 Connector is enabled (i.e. not commented out).

To enable the AJP/1.3 Connector in JIRA Standalone, Tomcat 5.5.x or Tomcat 5.0.x, remove thecomment symbols (<!-- and -->) around the following section in the conf/server.xml file:

<Connector port="8009"enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

If you are using JIRA Standalone 3.2 or earlier or running JIRA in Tomcat 4.1.x the AJP/1.3Connector definition in the conf/server.xml file looks like:

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"port="8009" minProcessors="5" maxProcessors="75"enableLookups="true" redirectPort="8443"acceptCount="10" debug="0" connectionTimeout="0"useURIValidationHack="false"protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>

The above example configures Tomcat to listen for proxied IIS requests on port 8009. If thisport is already in use on the machine where JIRA is running, please change to another port.

JIRA Documentation

Page 51Copyright © 2002-2005 Atlassian All rights reserved.

Page 52: Jira Manual

2. Restart Tomcat and ensure that no errors regarding used ports appear in the logs or in theTomcat Console.

3. Ensure that the AJP Connector is listening on the specified port (8009 by default). One wayto do this is to use the "netstat -na" command in the command window and see if port8009 is listed in the output:

AJP Connector listening on port 8009

2.7.1.3. Configuring IIS

On the machine where IIS is deployed:

1. Download the ISAPI Redirect installer from the apache site. When downloading, choose theversion of Windows that IIS is running on (either win32 or win64), and then choose the latestavailable jk version. The file to download is called isapi_redirect.msi.

2. Run the installer by executing the downloaded file. By default the files are installed into the"C:\Program Files\Apache Software Foundation\Jakarta IsapiRedirector" directory.

3. In the "C:\Program Files\Apache Software Foundation\Jakarta IsapiRedirector\conf" directory you will need to modify theuriworkermap.properties and the workers.properties.minimal files.

The workers.properties.minimal file tells IIS where (IP address and port) Tomcatis running. The uriworkermap.properties tells IIS what requests to proxy to Tomcat.

To edit these files please follow these steps:1. Edit the uriworkermap.properties and comment out (by adding the '#' character

at the beginning of each line) all the mappings except for /jkmanager=jkstatus.2. Add mapping for JIRA by adding the line /jira/*=wlb at the end of the file. The last

lines of the file should look like:

/jkmanager=jkstatus/jira/*=wlb

Note:The mapping (e.g. /jira/*) must be the same as the context path that JIRA has been deployed with in Tomcat as described in theConfiguring JIRA section of this document.

JIRA Documentation

Page 52Copyright © 2002-2005 Atlassian All rights reserved.

Page 53: Jira Manual

3. Edit the workers.properties.minimal file and modify theworker.ajp13w.host property if necessary. This property should be set to the hostname or the IP address of the machine where Tomcat (with JIRA) is running. If Tomcat isrunning on the same machine as IIS then you can leave the property set to localhost. Ifyou have specified a host name as the value of this property, please ensure that the IISmachine can correctly resolve it to the appropriate IP address.

4. If you have modified the port for the AJP Connector you will need to modify theworker.ajp13w.port property. Here is an example of the file with Tomcat running onthe same machine as IIS and using the default port (8009) for AJP:

worker.list=wlb,jkstatus

## Defining a worker named ajp13w and of type ajp13# Note that the name and the type do not have to match.#worker.ajp13w.type=ajp13worker.ajp13w.host=localhostworker.ajp13w.port=8009

## Defining a load balancer#

worker.wlb.type=lbworker.wlb.balance_workers=ajp13w

## Define status worker#

worker.jkstatus.type=status

4. If using IIS 5.0 you will need to restart IIS. The best way to ensure that IIS is restarted and readsthe configuration files you have modified is to navigate to Control Panel, then to AdministrativeTools and open Services. Find a service with name "World Wide Web Publishing", right click onit and choose "Stop". When the service stops, restarted by right-clicking and choosing "Start".

5. Open Control Panel, then Administrative Tools and open Internet Information Services.6. If using IIS 6.0 you will need to add an ISAPI Filter.

1. Right-click on Default Web Site (or the Web Site that should be responsible for proxyingrequests to JIRA), and click on Properties

2. Click on the ISAPI Filters tab3. Check if there is a Filter that points to the isapi_redirect.dll file and that it is in the

right location. If not, click on Add and create one. Enter tomcat as the Filter Name andthen enter the location of the isapi_redirect.dll file for the executable.

4. Click on Apply and then OK.7. Create a virtual directory for JIRA in IIS.

1. Right-click on Default Web Site (or the Web Site that should be responsible for proxyingrequests to JIRA), choose New and then Virtual Directory.

2. Go through the creation wizard. Set the alias as the value of the context path (withoutslashes) that was set in the Configure JIRA section. In our example this is jira.

3. This can point to any directory.4. Complete the wizard.

Note:Creating a virtual directory is required so that requests without the trailing slash still work. For example, if you are deploying JIRA underhttp://www.example.com/jira/ without the virtual directory the requests to http://www.example.com/jira will fail.

8. If using IIS 6.0 you will also need to add the dll as a Web Service Extension.1. Right-click on Web Service Extensions and choose Add a new Web Service Extension...

JIRA Documentation

Page 53Copyright © 2002-2005 Atlassian All rights reserved.

Page 54: Jira Manual

2. Enter tomcat for the Extension Name and then add the isapi_redirect.dllfile to the required files.

3. Check the Set extension status to Allowed and then click on OK.9. You are done! To test the configuration point your web browser at IIS and append JIRA's

context path to the URL. For example, if your website is running under the address ofhttp://www.example.com and you have deployed JIRA with context path of jira,point your browser at http://www.example.com/jira.

2.7.2. Integrating with Apache

This page describes how to integrate an Apache web server with JIRA (via mod_proxy), suchthat Apache forwards requests on to JIRA, and responses back to the user. This is useful if youalready have Apache serving web pages on port 80 (eg. http://mycompany.com), and wish tointegrate JIRA as just another URL (eg. http://mycompany.com/jira).

2.7.2.1. Step 1: Configure JIRA's application server

Here we assume you are using the JIRA Standalone distribution, which comes with Tomcat 5.5.We need to make two changes in Tomcat's conf/server.xml file:<Server port="8005" shutdown="SHUTDOWN">

<Service name="Catalina">

<Connector port="8080"maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true"proxyName="mycompany.com" proxyPort="80" />

<Engine name="Catalina" defaultHost="localhost"><Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">

<Context path="/jira" docBase="${catalina.home}/atlassian-jira" reloadable="false"><Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"....

The changes above assume JIRA will be running on http://mycompany.com/jira. They are:

• Tell Tomcat that it is running behind a proxy with the proxyName and proxyPort attributes.• Set the context path to something non-empty ('/jira').

Restart Tomcat, and ensure you can still access JIRA normally (eg. athttp://mycompany.com:8080/jira).

2.7.2.2. Configure Apache

Assuming an Apache 2 installation, the following needs to be done:

Enable mod_proxy

Here (on a Debian server) it is done by symlinking some files:teacup:/etc/apache2/mods-enabled# lscgid.conf cgid.load userdir.conf userdir.loadteacup:/etc/apache2/mods-enabled# ln -s ../mods-available/proxy.* .teacup:/etc/apache2/mods-enabled# lscgid.conf cgid.load proxy.conf proxy.load userdir.conf userdir.load

Configure mod_proxy

Here we create a config file snippet, conf.d/jira:teacup:/etc/apache2/mods-enabled# cd ../conf.dteacup:/etc/apache2/conf.d# cat > jira

JIRA Documentation

Page 54Copyright © 2002-2005 Atlassian All rights reserved.

Page 55: Jira Manual

<Proxy *>Order deny,allowAllow from all</Proxy>

ProxyRequests OffProxyPreserveHost OnProxyPass /jira http://localhost:8080/jiraProxyPassReverse /jira http://localhost:8080/jira

ServerAdmin [email protected]

teacup:/etc/apache2/conf.d#

Note that the path '/jira' must be the same as the path in JIRA.

Restart Apache, and watch the logs for errors.

You should now be able to access JIRA through http://mycompany.com/jira/.

2.7.2.3. Troubleshooting

On Fedora Core 4, people have reported 'permission denied' errors when trying to get mod_proxy(and mod_jk) working. Disabling SELinux (/etc/selinux/config) apparently fixes this.

In general, if you are having problems:

1. Ensure that JIRA works as expected when running directly from Tomcat onhttp://localhost:8080/jira

2. Watch the log files (usually in /var/log/httpd/ or /var/log/apache2/). Check that you have aLogLevel directive in your httpd.conf, and turn up logging ('LogLevel debug') to get more info.

2.7.2.4. For more details..

For more advanced mod_webapp configurations (eg. SSL), see this mod_proxy guide.

3. Concepts

3.1. JIRA Concepts — Issues

JIRA tracks issues, which can be bugs, feature requests, or any other tasks you want to track.

Each issue has a variety of associated information including:

• the issue type• a summary• a description of the issue• the project which the issue belongs to• components within a project which are associated with this issue• versions of the project which are affected by this issue• versions of the project which will resolve the issue• the environment in which it occurs• a priority for being fixed• an assigned developer to work on the task• a reporter - the user who entered the issue into the system• the current status of the issue• a full history log of all field changes that have occurred• a comment trail added by users• if the issue is resolved - the resolution

JIRA Documentation

Page 55Copyright © 2002-2005 Atlassian All rights reserved.

Page 56: Jira Manual

3.1.1. Issue Types

JIRA can be used to track many different types of issues. The default issues are listed below, butyou can add your own at the administration section.

bug iconBugA problem which impairs or prevents the functions of the product.

new feature iconNew FeatureA new feature of the product, which has yet to be developed.

task iconTaskA task that needs to be done.

improvement iconImprovementNot a new feature, rather an enhancement of an old one.

custom issue iconCustom IssueThis icon is used for your own custom issue types.

3.1.2. Priority Levels

An issue has a priority level which indicates its importance. The default priority levels are listedbelow. In addition, you can add your own priority levels at the administration section.

'blocker' priority iconBlockerBlocks development and/or testing work.

'critical' priority iconCriticalCrashes, loss of data, severe memory leak.

'major' priority iconMajorMajor loss of function.

'minor' priority iconMinorMinor loss of function, or other problem where easy workaround is present.

'trivial' priority iconTrivial

JIRA Documentation

Page 56Copyright © 2002-2005 Atlassian All rights reserved.

Page 57: Jira Manual

cosmetic problem like misspelled words or misaligned text.

3.1.3. Statuses

Each issue has a status, which indicates the stage of the issue. Issues generally start as being open,and then will progress to resolved and then closed. Depending on circumstances, it may alsoprogress to the other statuses.

'open' status iconOpenThis issue is in the initial 'Open' state.

'in progress' status iconIn ProgressThis issue is being actively worked on at the moment by the assignee.

'resolved' iconResolvedA resolution has been taken, and it is awaiting verification by reporter. From here issuesare either reopened and become reopened, are marked verified, or are closed for goodand marked closed.

'reopened' iconReopenedThis issue was once resolved, but the resolution was deemed incorrect. For example, aCannot Reproduce issue is reopened when more information shows up and the issue isnow reproducible. From here issues are either marked In Progress, Resolved or Closed.

'closed' iconClosedThe issue is considered dead, the resolution is correct. Any zombie issues who chooseto walk the earth again must do so by becoming reopened.

3.1.4. Resolutions

An issue can be resolved in many ways, only one of them being "fixed". The default resolutions arelisted below. You can also add your own in the administration section.

FixedA fix for this issue is checked into the tree and tested.Won't FixThe problem described is an issue which will never be fixed.DuplicateThe problem is a duplicate of an existing issue. Marking an issue duplicate requires theissue# of the duplicating issue and will at least put that issue number in the descriptionfield.IncompleteThere is not enough information to work on this issue.Cannot ReproduceAll attempts at reproducing this issue were futile, or not enough information wasavailable to reproduce the issue. Reading the code produces no clues as to why this

JIRA Documentation

Page 57Copyright © 2002-2005 Atlassian All rights reserved.

Page 58: Jira Manual

behaviour would occur. If more information appears later, please reopen the issue.

3.2. JIRA Concepts — Projects

A single JIRA installation contains a number of projects. These usually equate to products or'development projects' which you want to track issues on. Every issue belongs to one project.Each project has a name (eg. Website Issues) and a key (eg. WEB) which becomes the first partof that project's issue names (eg. WEB-100, WEB-101 etc).

See the Project Management page for information on how to create and administer projects.

3.2.1. Versions

Within a project, there are a number of versions - for example 1.0 alpha, 1.0 beta, 1.0, 1.2, 2.0.

Issues have two version fields:

• The 'Affects' version - this is the version(s) an issue 'applies' to. For instance, a bug mightaffect versions 1.1 and 1.2.

• The 'Fix for' version - this is the version the issue was or will be fixed in. For instance, thebug affecting 1.1 and 1.2 might be fixed in 2.0.

Versions can be in one of three states: released, unreleased. and archived. The state affectswhere in version drop-down lists the version appears.

Versions also have a Release Date, which shows up in certain reports.

See the Version Management page for information on how to create, delete and administerproject versions.

3.2.2. Components

Each project also consists of a number of components - for example Documentation, Backend,Email Subsystem, GUI etc.

Each issue can be assigned to zero or more components.

4. Configuration

4.1. Configuring JIRA

JIRA has a number of configuration options that allow the system to be customised for usewithin your organisation.

These configuration options can be accessed via the Administration interface. The currentconfiguration setup will appear as follows:

JIRA Documentation

Page 58Copyright © 2002-2005 Atlassian All rights reserved.

Page 59: Jira Manual

Screenshot of JIRA configuration settings and options

4.1.1. Editing Configuration

JIRA Documentation

Page 59Copyright © 2002-2005 Atlassian All rights reserved.

Page 60: Jira Manual

Clicking Edit Configuration will allow you to edit the current configuration.

The following sections detail the configuration options available and their effect on the system.

4.1.2. Settings

Setting Description

Title This is the title that will be displayed to userslogging into JIRA. It helps identify yourinstallation and its purpose.

Mode JIRA can operate in two modes:

public The default operation mode for JIRA. Anyonecan sign themselves up and create issues.

private Useful for internal issue tracking systems whereyou do not want public users to login. Signup isdisabled, only Administrators can create newusers.

Base URL This is the base URL of this JIRA installation.

It is used in outgoing emails and notifications toconstruct valid links.

Email From Header Specifies the From: header format in notificationemails. Default is of the form "John Doe (JIRA)<[email protected]>". Available variables are$'{fullname'}, $'{email'} and $'{email.hostname'}.

Introduction A short introduction message displayed on thedashboard.

It is possible to include HTML, but ensure all tags arecorrectly closed and that the HTML is well formed.

4.1.3. Internationalisation

Setting Description

Character Encoding The character encoding for input and viewing ofinformation within JIRA. For most westernlanguages, the default ("UTF-8") is suitable.

If you change this setting - ensure that you alsochange your database's encoding.

View a list of supported encodings. However, pleaseuse the IANA preferred MIME name (such as'iso-8859-1' instead of 'ISO8859_1') to ensure XMLbackups have the correct encoding string.

Indexing Language JIRA uses Lucene, a high-performance text searchengine library, in full-text searches over theinformation stored in JIRA.

This option should be set to the language thatinformation is entered in JIRA. It is necessary tore-index JIRA if this value is changed.

JIRA Documentation

Page 60Copyright © 2002-2005 Atlassian All rights reserved.

Page 61: Jira Manual

Installed Languages This section lists all language packs availablewithin the JIRA system.

Default Language This is the language used throughout the JIRAinterface (as selected from the list displayed in theInstalled Languages section).

This language setting is overridden by the Localesetting for each user profile.

4.1.4. Options

Setting Description

Voting Controls whether voting is enabled. Voting allowsusers to indicate a preference for issues they wouldlike to be completed or resolved.

Default: ON

Watching Controls whether watching enabled. Users can'watch' issues which they are interested in. Userswatching an issue will be notified of all changes to it.

Default: ON

Allow unassigned issues When turned on, JIRA will allow issues to beunassigned or assigned to 'no-one'.

When turned off, issues will always be assigned tosomeone - by default, the assignee will be the projectlead as defined for each project.

Default: OFF

External User Management When turned on, JIRA will assume that you are usinguser management from outside JIRA. JIRA will notdisplay options for users to change their password, oredit their profile.

Note: JIRA's LDAP integration is currently limited toexternal password management, so this flag shouldbe left OFF when using LDAP.

Default: OFF

External Password Management When turned on, JIRA will assume that you are usingpassword management from outside JIRA. JIRA willnot display options for users to change theirpassword, or display the forget your password link.

Note: With the default osuser LDAP provider, thisshould be turned ON, as accounts are not yet storedin LDAP and this property only hides the passwordfeatures within JIRA.

Default: OFF

Logout Confirmation Controls whether to obtain user's confirmation whenlogging out.

cookie means prompt for confirmation if the user was

JIRA Documentation

Page 61Copyright © 2002-2005 Atlassian All rights reserved.

Page 62: Jira Manual

automatically logged in (via a cookie).

Default: NEVER

Use GZip Compression Controls whether to use gzip compression tocompress JIRA's web pages. This is useful if JIRA isbeing run over slow networks. It incurs a slightperformance penalty, and may not work fornon-English languages.

Default: OFF

Allow remote API access Controls whether to allow remote client access (viaXML-RPC or SOAP) to this JIRA installation forauthenticated users.

Default: OFF

User Email Visibility Controls how user email addresses are displayed inthe user profile page.

Public - visible to all.

Hidden - email addresses hidden for all users.

Masked - the email address is masked ([email protected] = user at example dot com).

Logged in Users Only - only users logged in to JIRAcan view the email addresses

Default: PUBLIC

Exclude email header "Precedence: bulk" Controls whether to prevent the Precedence: Bulkheader on JIRA notification emails. This optionshould only be enabled when when notifications goto a mailing list which rejects 'bulk' mails. In normalcircumstances, this header prevents auto-replies (andhence potential mail loops).

Default: OFF

Cache Issues Controls internal system caching of projects, versionsand components.

Note: As of Jira 3.3 this option is no longer relevant,this should always be left off, unless explicitly askedto change the value by Atlassian support.

Default: OFF

4.1.5. Advanced properties

There are a handful of other properties (usually storing defaults of little interest to most JIRAusers) in the WEB-INF/classes/jira-application.properties file, which you may want to edit.

4.2. Internationalisation

4.2.1. Overview

Most user-visible pages in JIRA are now internationalized. Russian, German, Danish, Spanish,

JIRA Documentation

Page 62Copyright © 2002-2005 Atlassian All rights reserved.

Page 63: Jira Manual

French and Brazilian Portuguese translations are available (at time of writing), with more indevelopment (see below).

When JIRA is first installed, the default language may be chosen by clicking on a flag:

Choose LanguageIf you already have JIRA installed, you will need to go to the Administration page, and go to"General Configuration" (under the "Global Settings" subheading on the left). Clicking on "EditConfiguration" and select the language you have installed in the drop-down box next to "DefaultLocale".

Editing default locale

4.2.1.1. Per-user language selection

As a user, you can personalise your JIRA account to use a language of your choosing (provided that

JIRA Documentation

Page 63Copyright © 2002-2005 Atlassian All rights reserved.

Page 64: Jira Manual

it's been installed by an admin already).

To do this, follow the "Profile" link on the top of the page, and then to "View Preferences". Nowselect the language you want from the "Locale" drop down list.

Update Locale in User Preferences

4.2.2. Translating JIRA

JIRA's internationalization is an ongoing effort, and we'd love your help. If you would like totranslate JIRA into your language, the rest of this document describes how to do so.

In order to get JIRA to appear in your language you need to translate all the properties fileslocated inside language_default.jar. The language_default.jar is found insideWEB-INF/lib directory.

Note:The latest properties files for the next (unreleased) JIRA version are available fromhttp://www.atlassian.com/software/jira/translations.

4.2.2.1. Where to begin?

Translating JIRA's default English property files begins with extracting the contents of thelanguage_default.jar into a temporary directory (using a standard Unzip utility of 'jarxvf' from the command-line). After extracting the jar, make a copy of each property file, giving ita new name that contains locale information. For example, if you are translating theDashboard.properties file into French, save all changes to a separate Dashboard_fr_FR.propertiesfile. That is, the format of name is:<Default Name>_<Language Code>_<Country Code>.properties

See translating to multi-byte languages for a slight modification to this procedure, if applicable.

The "Language Code" is a valid ISO Language Code. These codes are the lower-case, two-lettercodes as defined by ISO-639.

The "Country Code" is a valid ISO Country Code. These codes are the upper-case, two-lettercodes as defined by ISO-3166.

Note:

JIRA Documentation

Page 64Copyright © 2002-2005 Atlassian All rights reserved.

Page 65: Jira Manual

The original directory structure of the property files should be preserved. For example, when creatingcom/atlassian/jira/web/action/Dashboard_fr_FR.properties file, it must be placed in com/atlassian/jira/web/action directory (relative to thetemporary directory you are working in).

4.2.2.2. Translating words

Properties files contain many "entries" for each of the words and sentences used in JIRA. The entryfor the common word "Project" looks like this:common.concepts.project = Project

To translate this into French (for example), you would replace the English word "Project" with"Projet".i.e. common.concepts.project = Projet

Note:Not all entries for a particular page in JIRA will appear in the natural properties file associated with that page. For example, on the"Create Issue" page, entries for "Project" and "Issue Type" cannot be found in the CreateIssue.properties file. Some words in JIRA appearin more than one place and have therefore been placed in a single properties file. This saves you from having to translate common wordsmore than once. The name of this file is JiraWebActionSupport.properties.

4.2.2.3. Translating sentences

Some sentences in JIRA have certain words that are HTML links OR constitute database data. Forexample:issue.operations.move = {0}Move{1} this issue to another project

ORroadmap.issuesresolved = {0} of {1} issues have been resolved

In the first example, the word "Move" links to the "Move Issue" page. The HTML code for this linkis passed in using {0} and {1}. In the second example, {0} is the number of resolved issues and {1}is the total number of issues. When translating sentences, ensure that you do not omit these elements.A French translation of the above might look like this:issue.operations.move = {0}Déplacer{1} cette demande vers un autre projet

4.2.2.4. Packaging the Translation

The properties files for each locale are collected into language bundles. Once you have finishedtranslating all the properties files, a language descriptor file has to be created. This file "tells" JIRAthat a new language is available. The file MUST be called language-descriptor.xml andshould be located at the root of the language bundle (i.e. directly in the temporary directory). Thelanguage-descriptor.xml tells JIRA which locale (language and country) the property files representand what version of JIRA the translation was last updated for. The file looks like:

<language><locale>en_UK</locale><version>2.6</version>

</language>

The locale tag must contain a proper Java locale name. The locale name is made up of theLanguage Code and Country Code (Please see the Where to begin? section for more details).

Set the value of the contents of the locale tag to the locale that your translation represents and setthe contents of the version tag to the version of JIRA for which you are doing the translation.

Create a jar ('jar cvf language_<locale>.jar ...') which contains all the translated property files(remember to preserve the directory structure) and the language-descriptor.xml file. While notnecessary, it is a good idea to call this file language_<locale>.jar, where <locale> is the

JIRA Documentation

Page 65Copyright © 2002-2005 Atlassian All rights reserved.

Page 66: Jira Manual

contents of the locale tag of the file. For example, for French call the filelanguage_fr_FR.jar.

4.2.2.5. How do I install my new translation?

To make JIRA aware of your translation, you will need to copy the jar file you have created inthe previous step into WEB-INF/lib directory found under JIRA's web application directory.

If you would like JIRA to display a flag for your translation during the setup process place a GIFimage with the same name as the locale into the /images/flags directory under JIRA webapplication directory. For example, for the French translation place a file called fr_FR.gifinto the /images/flags directory.

If you are installing JIRA for the first time, the first page of setup should now display yourinstalled language.

Choose LanguageClicking on your language/flag will allow you to set up JIRA in your language.

4.2.2.6. Submitting a translation

JIRA Documentation

Page 66Copyright © 2002-2005 Atlassian All rights reserved.

Page 67: Jira Manual

If you would like your translation to be included in JIRA, please create an issue on jira.atlassian.comand attach the jar containing the properties files.

4.2.3. Translating with multi-byte languages

Languages like Chinese and Russian are represented with native two-byte encodings like gb2312 orkoi8. Java .properties files are assumed to be Unicode encoded as ISO-8859-1. Therefore enteringChinese or Russian characters directly into the .properties files will not work.

The solution is to create the translation is a separate files:<Default Name>_<Language Code>_<Country Code>-native.txt

Once completed, these can be transformed into regular .properties files with the 'native2ascii'command. Eg, for Russian:native2ascii -encoding cp1251 JiraWebActionSupport_ru_RU-native.txt

JiraWebActionSupport_ru_RU.properties

4.2.4. Issue Field Translations

Further extending JIRA as an internationalisable issue manager, it is possible to configure atranslation set for each locale for each issue constant - i.e. Issue Type, Resolution, Status and Priorityname and description fields. Further details on configuring the issue constant translations areavailable here.

4.3. Configuring Look & Feel in JIRA

You can easily customise JIRA's look and feel to suit your needs.

The current configuration can be viewed via the Administration interface. It should look like this:

Screen shot of JIRA look and feel settings

JIRA Documentation

Page 67Copyright © 2002-2005 Atlassian All rights reserved.

Page 68: Jira Manual

Clicking Edit Configuration will allow you to edit the current configuration. To reset to thedefault look and feel of JIRA, simply click on the 'Reset Default' button.

Here is a list of the different configuration options available, and what they do.

4.3.1. Logo

Option Explanation

URL This URL points to the absolute or relative path ofthe image that you wish to display at the top of thepage. If the URL begins with 'http://' or 'https://'then the URL is treated as an absolute URL.Otherwise it will be treated as a relative URL, andwill have to be packaged in the war file when youbuild JIRA.

Preview When an image is selected, a preview will beshown here.

Logo Width The width of the image, usually in pixels. Youcan use any width that is valid in an image tag.eg. '100px', '80%'

Logo Height The height of the image, usually in pixels. Youcan use any height that is valid in an image tag.eg. '25px', '30%'

4.3.2. Colours

The colours you choose for each of the sections can be anything that is valid for both a font tag,and a stylesheet's 'color:' attribute.

When choosing a colour - you can use the pop-up colour chooser, or specify your own. eg.'#FFFFFF', 'red'.

To return to the original colour scheme, just clear any values that you have set.

Option Explanation

Top Bar Colour The background colour of the top bar (the onethat includes the image).

Top Text Colour The colour of the text that sits inside the top bar(such as your user name when you are loggedin).

Menu Bar Colour The background colour of the bar that containsthe links to 'HOME' and 'BROWSE PROJECT'.

Menu Bar Text Colour The text color of the links in the menu bar (suchas 'HOME').

Menu Bar Higlight Colour The colour of the menu bar when it is selectedor when the mouse hovers over it.

Menu Bar Text Highlight Colour The colour of the menu bar text when it ishighlighted or when the mouse hovers over it.

Link Colour The colour of the text links.

Link Active Colour The colour of the text links when it is selected.

JIRA Documentation

Page 68Copyright © 2002-2005 Atlassian All rights reserved.

Page 69: Jira Manual

Heading Colour The colour of the text headings (such as 'Logo').

4.3.3. Issue Field Descriptions

These are small descriptions which appear below each text field in the 'Create Issue' and 'Edit Issue'forms. They are useful for explaining the meaning of certain input fields for reporters.

Option Explanation

Issue Type The description which appears under the 'IssueType' input field.

Summary The description which appears under the'Summary' input field.

Priority The description which appears under the'Priority' select field.

Components The description which appears under the'Components' select field.

Versions The description which appears under the'Versions' select field.

Fix For Version The description which appears under the 'FixFor Versions' select field.

Assignee The description which appears under the'Assignee' select field.

Environment The description which appears under the'Environment' text field.

Description The description which appears under the'Description' text area.

Estimated Time Tracking The description which appears under the'Original Estimation' text field. This text field isonly visible if Time Tracking is on.

4.3.4. Time Formats

All time formats in JIRA are configurable. On the first look and feel page, you can preview how thecurrent date and time are being formatted using the default formats.

View Time FormatsYou can edit these defaults by clicking on the "Edit Configuration" link down at the bottom. Forexample, you may wish to change the day/month/year format to show the month first. Simply enterMM/dd/yy beside the day/month/year format field, and preview by clicking the "update" button.

JIRA Documentation

Page 69Copyright © 2002-2005 Atlassian All rights reserved.

Page 70: Jira Manual

Edit Time FormatThe preview page should show the current time in the new format.

Updated date format showing month first

4.4. Issue Constant Translations

Further extending JIRA as an internationalisable issue manager, it is possible to specify atranslated name and description for each issue constant - i.e all Issue Type, Status, Resolutionand Priority fields.

This functionality allows the administrator to specify an issue constant translation set for eachavailable locale - providing each user with a more complete translation in their own chosenlanguage. The translated issue constant names and descriptions appear throughout JIRA; inreports, portlets and all issue views.

4.4.1. Issue Constant Translation

Each issue constant can be configured to have a translation set for each available locale. Thedefault issue constant name and description are displayed if no translation has been configured.

1. The issue constant translation operation is accessed through the Translate link located oneach issue constant management screen.

JIRA Documentation

Page 70Copyright © 2002-2005 Atlassian All rights reserved.

Page 71: Jira Manual

Issue Constant Translation Link2. The issue constant translation screen displays the translation set for the currently selected locale.

In order to view/update a translation set for a specific locale, select the required locale from thelist at the top of the screen and click the View button.

Issue Constant Translation Screen

JIRA Documentation

Page 71Copyright © 2002-2005 Atlassian All rights reserved.

Page 72: Jira Manual

3. The currently selected locale is displayed above the translation set table.4. A translated name and description set can be specified for each type of issue constant. Once

all translations have been entered, the translation set can be saved by clicking the Updatebutton at the bottom of the translation table.

5. The process can be repeated for the all types of issue constants - i.e. Issue Type, Status,Resolution and Priority fields.

6. The translated issue constant name and description will be displayed throughout JIRA; inreports, portlets and all issue views.

Issue Constant Translation - Create Issue

Note:The default issue constant name and description are displayed if a translation has not been specified.

4.5. Field Configuration and Screens

4.5.1. Field Configuration and Screens: Overview

JIRA enables you to manipulate the display and behaviour of fields. This is achieved through twokey concepts, Field Screens and Field Configurations. You can reorder, show or hide, makerequired and change the description of fields. Below we provide an overview to the key conceptsrelevant for each version of JIRA.

4.5.1.1. Basic Configuration: Standard Edition

Under standard edition, you can reorder and add / remove fields through Field Screens. You haveone global Field Screen Scheme to associate screens to various actions (e.g. Create, Edit, View).Field Configurations allow you to hide fields across all screens, make them required and changethe field description. In Standard Edition, any changes you make to the screens or fieldconfigurations are applicable across all projects.

4.5.1.2. Screens Per Project: Professional Edition

Professional Edition introduces an additional concept of multiple Field Screen Schemes. Eachscreen scheme can have different screens linked to different actions. For example, you can havedifferent edit screens from one project to another. Once you've set up the schemes, you can reusethe same scheme for multiple projects.

JIRA Documentation

Page 72Copyright © 2002-2005 Atlassian All rights reserved.

Page 73: Jira Manual

Professional Edition

4.5.1.3. Schemes Per Project and Issue Type: Enterprise Edition

JIRA adds further flexibility for Enterprise Editions by adding different schemes per issue types.Issue Type Screen Schemes allows you to associate Field Screen Schemes to an issue type. Thisallows you to specify different screens for the same operation (e.g. Create Issue) in the same projectfor issues of different issue types.

Enterprise Edition

4.5.2. Field Configurations

A Field Configuration provides the ability to change field behaviour. A configuration essentiallytells JIRA how to handle a particular field. For example, should the field be ignored (hidden) orvalidated that it has been given a value (required)? Field Configuration also allow administrators tocustomise field descriptions. The description appears under a field when an issue is edited.

Please note, that in the Enterprise edition it is possible to create multiple Field Configurations. FieldConfigurations can then be organised into Field Configuration Schemes on per issue type basis.Once created, a Field Configuration Scheme can be associated with one or more projects, allowingadministrators to control fields on per project, per issue type basis.

For more information on how to create, edit and remove Field Configurations in the Enterpriseedition of JIRA please read this section.

In the Standard and Professional editions of JIRA only one Field Configuration exists. Thisconfiguration affects all projects and issue types in the system.

4.5.2.1. Changing Behaviour of Fields

JIRA Documentation

Page 73Copyright © 2002-2005 Atlassian All rights reserved.

Page 74: Jira Manual

To change the behaviour of fields, one needs to navigate to a Field Configuration first. The waythis is done slightly varies on the edition of JIRA:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. For Standard and Professional editions:Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose"Issue Fields" from the list.

Standard and Professional Edition Sub Menu for Issue Fields

For Enterprise edition:Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose"Field Configurations" from the list. Select the field configuration of interest.

Enterprise Edition Sub Menu for Issue Fields4. This will bring you to the Field Configuration Screen.

The Field Configuration screen lists all system and custom fields in a table as shown in the figurebelow. The "Operations" column lists all the operations that are available for each field.

JIRA Documentation

Page 74Copyright © 2002-2005 Atlassian All rights reserved.

Page 75: Jira Manual

These operations could be:

• Edit - change the field's description• Hide/Show - hide the field from view or show it• Require/Optional - set a field to be required, so that whenever a field is edited it must be given a

value, or turn the field back to being "optional".

Field Configuration: View Issue Fields

4.5.2.2. Editing Field's Description

Fields can be given descriptions to better identify the meaning of the field. These descriptions areusually displayed under the field on the creation of an issue and whenever it is edited. An example ofthis, is shown below.

JIRA Documentation

Page 75Copyright © 2002-2005 Atlassian All rights reserved.

Page 76: Jira Manual

Field Description ExampleTo edit the description of a field please follow the steps outlined below:

1. In the Field Configuration screen click on the "Edit" link next to the field you want to change.This will bring you to the "Edit Field Description" page.

2. On this page you can edit the field's description3. Press the "Update" button.

Edit Issue Field Description

4.5.2.3. Hiding/Showing a field

If your organisation or project has no use for a particular field you have the option to hide it.Hiding a field will ensure that the the field does not appear anywhere (e.g. issue views,transitions screens, operations) where the Field Configuration applies.

Hiding a field in the Field Configuration is distinct from not adding a field to a screen throughField Screens. Fields hidden through the configuration will be hidden in all applicable screens,regardless of whether they appear on the screen or not.

To hide a field please follow these steps:

1. In the Field Configuration Screen click the "Hide" link next to a field you no longer want.The field will then fade to grey to signify that it has been hidden.

2. As per the image above, the "Environment" field has been hidden. You can make this fieldvisible again anytime by pressing on the "Show" link.

Note:The fields "summary" and "issue type" cannot be hidden and as such there is no hide option available for these fields.

4.5.2.4. Required/Optional fields

Certain fields within your organisation may be compulsory for issues. In this case you can set afield to be required, so that JIRA validates that the field has been given a value whenever anissue is edited. If a required field has not been given a value JIRA will return an error informingthe user that the field should be filled.

JIRA Documentation

Page 76Copyright © 2002-2005 Atlassian All rights reserved.

Page 77: Jira Manual

Field required errorPlease follow these steps to make a field required:

1. In the Field Configuration screen click the "Required" link next to the appropriate field. The text"Required" will appear next to the field.

2. As per the image above, the "Fix Versions" field has been made required. You can make thisfield optional again anytime by pressing on the "Optional" link.

Note:Fields that are hidden cannot be set to required. Making a hidden field required will make it "shown" as well.

4.5.2.5. Field Configurations

In Enterprise edition it is possible to create multiple field configurations for use on separate projectsand issue types. Multiple field configurations are organised into Field Configuration Schemes basedon issue type. A scheme can be associated with one or more projects allowing administrators tocontrol fields on per project per issue type basis.

Therefore, in the Enterprise edition it is possible to create, edit, delete and copy field configurations.All these operations are available from the View Field Configuration page. To navigate to this page:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose"Field Configurations" from the list.

4. You will now see a list of all your current field configurations

JIRA Documentation

Page 77Copyright © 2002-2005 Atlassian All rights reserved.

Page 78: Jira Manual

View Issue Field Configurations

4.5.2.6. Adding a Field Configuration

1. The "Add" new field configuration form is located at the bottom of the View FieldConfiguration Page

2. Enter the name of the new configuration on this form.3. You can optionally add a description to this configuration for better identification.4. Click on the "Add" button to submit the form. The page will be automatically updated with

your new field configuration added.

4.5.2.7. Editing a Field Configuration

1. In the Field Configuration page click on the "Edit" link next to the desired fieldconfiguration.

2. You will now see the "Edit Field Configuration" page. Here it is possible to edit theconfiguration name and description.

3. Click on the "Update" button.4. On completion you will be returned to the page where you can view your changes.

4.5.2.8. Deleting a Field Configuration

1. In the Field Configuration page click on the "Delete" link next to the desired fieldconfiguration.

2. Click on the "Delete" button to confirm this operation.3. The View Field Configuration Page will now show the updated list of the field

configurations.

Note:You can only delete a field configuration that is not associated with a field configuration scheme.

Note:The Default Field Configuration cannot be deleted.

4.5.2.9. Copying a Field Configuration

1. Click on the "Copy" link next to the field configuration you wish to copy

JIRA Documentation

Page 78Copyright © 2002-2005 Atlassian All rights reserved.

Page 79: Jira Manual

2. This will bring you to the "Copy Field Configuration" page.3. Enter the name and description of the new field configuration.4. Click on the "Copy" button.5. You will now be directed back the Field Configuration page with your new field configuration

added. The field settings on the original and the new field configurations will be identical.

Copy Field Configuration

4.5.2.10. Default Field Configuration

When JIRA Enterprise is installed only the Default Field Configuration is created. All new projectsare associated with this configuration. This configuration is also used for projects that are notassociated with a Field Configuration Scheme.

Note:It is not possible to delete the Default Field Configuration.

4.5.3. Field Configuration Schemes

In the Enterprise edition of JIRA it is possible to define field configurations for a particular issuetype of a given project using Field Configuration Schemes. Field Configuration Schemes map fieldconfigurations to issue types. Once created, a Field Configuration Scheme can be associated withone or more projects. This means that, for example, it is possible to have a separate fieldconfiguration for the Bug issue type and for Improvement for the Test Project. If you're afterschemes for Field Screens then you should look at Field Screen Schemes.

Please note that schemes can be associated with more than one project allowing administrators toreuse the same field configuration to issue type mappings between projects.

4.5.3.1. Field Configuration Schemes

Scheme operations are available from the View Field Configuration Scheme page. To reach thispage follow these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 79Copyright © 2002-2005 Atlassian All rights reserved.

Page 80: Jira Manual

Link to Administration section

3. Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose"Field Configuration Schemes" from the list.

4. You will be directed to the page "View Field Configuration Schemes" with a list of all theconfiguration schemes currently configured. From this page you can:

• Add - create a new configuration scheme• Configure - add or remove issue type associations with field configurations• Edit - edit the name and description of the configuration scheme.• Delete - remove a configuration scheme• Copy - create a new configuration scheme with the same details

Note:To make the most of field configuration schemes you will need to add a field configuration.

4.5.3.2. Adding a Field Configuration Scheme

1. The Add new field configuration scheme form is located at the bottom of the View FieldConfiguration Scheme page

2. On this form enter the name of the new scheme.3. You can optionally add a description to the scheme for better identification.4. Click on the "Add" button. The field configuration scheme list will be updated automatically

with the new scheme.

View Field Configuration Scheme

4.5.3.3. Configure a Field Configuration Scheme

With this operation you can associate, un-associate or change an association of a fieldconfiguration to a particular issue type. To do this please follow these steps:

1. Click on the "Configure" link in the same row as the field configuration scheme you wish toconfigure.

JIRA Documentation

Page 80Copyright © 2002-2005 Atlassian All rights reserved.

Page 81: Jira Manual

2. The "Configure Field Configuration Scheme" page will appear showing the current fieldconfiguration to issue type mapping of this scheme.

3. The operations available when configuring a field configuration scheme are:• Associate an issue type to a field configuration• Remove an association between an issue type and a field configuration• Edit an association between an issue type and a field configuration

Note:If you have not added any field configurations you will only have the Default Field Configuration to work with.

Configure Field Configuration Scheme

Associating a field configuration with an issue type

To associate an issue type with a field configuration:

1. Select the issue type you wish to associate.2. Select the field configuration you wish to associate with this issue type3. Click on the "Add" button. The table will above will be automatically updated with the the issue

type in the left most column and the associated field configuration in the central column.

Note:An issue type can only have one association within a given configuration scheme.

Note:If an issue type does not have an association in the scheme, the field configuration associated with the Default entry in the scheme will beused for issues of that type.

Removing an association between a field configuration and an issue type

1. Click on the "Remove" link next to the issue.2. The issue type association will automatically be removed from the field configuration scheme.

JIRA Documentation

Page 81Copyright © 2002-2005 Atlassian All rights reserved.

Page 82: Jira Manual

Note:The Default entry cannot be removed the scheme.

Editing an association between a field configuration and an issue type

1. Click on the "Edit" link next to the issue2. Select the new field configuration you would like to associate with this issue type3. Click on the "Update" button4. The Issue Type will now be associated with the new field configuration.

Edit association between field configuration and issue type.

4.5.3.4. Editing a Field Configuration Scheme

To change the name or description of a Field Configuration Scheme:

1. Click on the "Edit" link next to the desired field configuration scheme. You will now see the"Edit Field Configuration Scheme" page.

2. Change the name and/ord description as necessary.3. Click on the "Update" button.

4.5.3.5. Deleting a Field Configuration Scheme

To delete a Field Configuration Scheme:

1. Click on the "Delete" link next to the desired field configuration scheme. You will now seethe "Delete Field Configuration Scheme" page.

2. Confirm that you would like to delete the scheme by clicking the "Delete" button.

4.5.3.6. Copying a Field Configuration Scheme

To copy a Field Configuration Scheme:

1. Click on the "Copy" link next to the field configuration scheme you wish to copy. This willbring you to the "Copy Field Configuration Scheme" page.

2. Enter the name and description of the new field configuration scheme.3. Click on the "Copy" button.4. You will now be directed back the View Field Configuration Scheme page with your new

scheme added. The new scheme will have the same configuration as the copied scheme.

JIRA Documentation

Page 82Copyright © 2002-2005 Atlassian All rights reserved.

Page 83: Jira Manual

Copy Field Configuration Scheme

4.5.3.7. Associating a Field Configuration Scheme with a Project

Once you have configured the field configuration scheme to your desired settings, you can nowassociate it with a project. An association means that the field configuration scheme will now beapplied to the chosen project. The issues in that project will use the field configuration that ismapped to their issue type by the scheme.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the administration page is a list of projects which this user is allowed to manage. Select theproject of interest.

4. Click on the "select scheme" link beside the Field Configuration Scheme caption.

Project Admin Page5. This will bring up a list of all existing field configuration schemes. Select the scheme you want

to associate with this project.

Associate Field Configuration Scheme to Project

JIRA Documentation

Page 83Copyright © 2002-2005 Atlassian All rights reserved.

Page 84: Jira Manual

Note:Selecting None will make all the issues in the project use the Default Field Configuration.

6. Click on the "Associate" button. You will be returned to the project admin page with theproject now associated with selected field configuration scheme.

Note:As mentioned above, new projects are not associated with any Field Configuration Schemes and hence use the Default FieldConfiguration for all issues.

4.5.4. Screens

4.5.4.1. Overview

Screens group multiple issue fields. Using Screens administrators can control which fields aredisplayed, and the vertical order that the fields are displayed with, during issue operations such asCreate Issue and Edit Issue or a workflow transition, such as Resolve Issue. In the Enterpriseedition it is also possible to split issue fields on a Screen into multiple tabs.

For example, the figure below shows a simple Screen that only shows issue summary anddescription on the first tab, and affected versions and components on the second tab.

Sample ScreenScreens overlap slightly with Field Configurations in regards to field visibility. One must notethat when a Screen is displayed to a user, for example, during issue creation, the user will seeonly the issue fields that:

1. The user has permissions to edit2. Are present on the Screen that is associated with Create Issue operation for this issue.3. Are not hidden in the Field Configuration applicable to the issue.

Please note that a Field Configuration affects all views, issue operations and workflow transitions

JIRA Documentation

Page 84Copyright © 2002-2005 Atlassian All rights reserved.

Page 85: Jira Manual

for an issue. If a field is hidden in a Field Configuration, the field will not appear anywhere forissues that "map" to that Field Configuration. A Screen simply allows to select which field could beshown when the screen is displayed. A field can never be shown on a Screen if it is hidden in anappropriate Field Configuration.

Due to this functionality, if a particular field needs to be hidden, it is simpler to hide the field in anapplicable Field Configuration rather than remove it from all screens.

A Screen is not very useful until it has been associated with an issue operation using a ScreenScheme or with a workflow transition. Screen Schemes map issue operations (e.g. Create Issue) toScreens. Once you have organised Screens into Screen Schemes, what you need to do depends onthe edition of JIRA that you are using. For more information on Screen Schemes please read thisdocument.

As mentioned previously, it is also possible to select which fields are displayed on Workflowtransitions using Screens by either modifying the Screen that is associated with a workflow transitionor in the Professional and Enterprise editions associating a transition with a different Screen alltogether.

For more information on how to administer and use Screens please read the sections that follow.

4.5.4.2. View Screens Page

Most of operations concerning Screens can be performed from a the View Screens page. To navigateto this page please follow these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose"Screens" from the list.

4. You will then be directed to the "View Screens" Page.

Note:The screenshot below is only common in Standard edition. Professional and Enterprise editions will have a different layout but includesthe same functionality.

JIRA Documentation

Page 85Copyright © 2002-2005 Atlassian All rights reserved.

Page 86: Jira Manual

View Screens Page

From this page you are able to:

• Add a new field screen.• Configure a field screen.• Edit a field screen.• Delete a field screen.• Copy a field screen.

4.5.4.3. Add Screen

1. The "Add Screen" form is located at the bottom of the View Screens page.2. Enter the name of the new Screen.3. You can optionally add a description.4. Click on the "Add" button. The page will automatically update the Screen list with the new

Screen.

4.5.4.4. Configuring Screen

To configure the fields on a Screen from the View Screens page:

1. Click on the "Configure" link next to the Screen of interest.2. You will now see the "Configure Screen" page.

Note:The screenshot below is common between Standard and Professional editions, the Enterprise edition screen includes the tabsfunctionality.

JIRA Documentation

Page 86Copyright © 2002-2005 Atlassian All rights reserved.

Page 87: Jira Manual

Configure Screen Page

Add Field to Screen

1. The "Add Field" form is located at the bottom of Configure Screen page.2. Select the field/s that you wish to add to the screen.3. You can also specify which position the field will be placed in.

Note:If you have selected multiple fields and specified a position, the topmost field selected will be placed in the corresponding position andthe other fields directly below it.

JIRA Documentation

Page 87Copyright © 2002-2005 Atlassian All rights reserved.

Page 88: Jira Manual

4. Click on the "Add" button"

Remove Field from Screen

1. From the Configure Screen page, select the checkboxes next the the fields you wish toremove.

2. Click on the "Remove" button located at the bottom of the table.3. The fields will be removed from the Screen and will become available in the "Add Field"

form at the bottom of the screen.

Reorder Fields in Screen

1. Specify the position you wish to move a field to in the text box in the "Move to Position"column next to the desired field.

2. You can repeat this for multiple fields specifying a different position for each field.3. Click on the "Move" button located at the bottom of the table in the "Move to Position"

column.4. All the fields will be placed in the specified positions.

Note:Alternatively, you can click on the arrows next to the desired field to move the field up, down, to the first position or to the lastposition.

4.5.4.5. Edit Field Screen

To change Screen's name and/or description you can edit a Screen by following these steps:

1. Click on the "Edit" link next to the appropriate screen.2. You will now be directed to the "Edit Screen" page where you can edit the name and/or

description of the Screen.3. Click on the "Update" button. You will be brought back to the View Screens page with your

updates now applied to the Screen.

Edit Screen Page

4.5.4.6. Delete Field Screen

To entirely remove a Screen from the system:

1. Click on the "Delete" link next to the Screen you wish to delete.2. Click on the "Delete" button to confirm this action. You will be brought back to the View

Screens page with the Screen removed from the list of Screens.

JIRA Documentation

Page 88Copyright © 2002-2005 Atlassian All rights reserved.

Page 89: Jira Manual

Delete Screen Page

Note:Field screens that are associated with at least one Screen Scheme or at least one workflow transition cannot be deleted.

4.5.4.7. Copy Field Screen

1. Click on the "Copy" link next to the Screen you wish to copy. You will now be directed to the"Copy Screen" page.

2. Enter a name and a description for the new Screen.3. Click on the "Copy" button. You will be brought back to the View Screens page and the newly

added Screen will have the same issue fields and field positions as the original field screen.

Copy Screen Page

4.5.4.8. Screen Tabs

The Enterprise edition allows to split Screens into multiple tabs. The affect of this is almost the sameas having multiple screens on the same page when an issue operation is being performed. Thisfunctionality is very useful for organising complex Screens, as you can place less used fields, forexample, attachment and environment, onto separate tabs. Field tabs can also help to group relatedfields together on a Screen.

JIRA Documentation

Page 89Copyright © 2002-2005 Atlassian All rights reserved.

Page 90: Jira Manual

Example of a field tabScreen tabs are available from the Configure Screens page.

Configure Screen Page with Field Tabs

4.5.4.9. Add Field Tab

1. The "Add Field Tab" is located on the bottom right of the Configure Screen page.2. Enter the name of the new tab on this form.3. Click on the "Add" button.

4.5.4.10. Moving fields between Tabs

1. In the "Move to Tab" column next to the field you wish to move, select the desired tab.2. Repeat this for all the fields you wish to move.3. Click on the "Move" button located at the bottom of the table in the "Move to Tab" column.4. All the selected fields will be moved to the appropriate tabs.

4.5.4.11. Navigate between tabs

To navigate between the tabs of a field screen, simply click on the links on the top left of theconfigure screen form.

4.5.4.12. Delete a Tab

1. Navigate to the tab you wish to remove.2. Click on the "Delete" tab link. You will now be directed to the "Delete Tab" confirmation

page.3. Click on the "Delete" button to confirm. You will now be returned to the "Configure Screen"

Page

JIRA Documentation

Page 90Copyright © 2002-2005 Atlassian All rights reserved.

Page 91: Jira Manual

Delete Tab Page

4.5.4.13. Rename a Tab

1. Navigate to the desired tab.2. The "Rename" text field is located in the top left of the "Configure Screen Tab" form.3. Enter the new name of the tab.4. Press 'Enter'.

4.5.4.14. Reorder Tabs

It is possible to configure the horizontal order of a tabs by clicking on the arrows to move theselected tab left or right.

4.5.5. Screen Schemes

Screen Schemes allow to configure which Screen will be shown for a particular issue operation, suchas creating an issue or editing an issue. Screens Schemes therefore, allow one to configure JIRA touse different screens for creating and editing issues. If you're after a schemes for field configurationsgo to Field Configuration Schemes.

Once you have created a new Screen you will now need to add to a Screen Scheme, and then activatethe scheme. The method of activation differs for each edition of JIRA:

• Standard Edition - only supports one (default) screen scheme, so all Screens are activated byadding it to the default Screen Scheme.

• Professional Edition - allows for project specific Screen Schemes, so after creating a ScreenScheme one should associate it with a project.

• Enterprise Edition - adds extra flexibility by supporting Screen Schemes per project per issuetype, using Issue Type Screen Schemes. After creating a Screen Scheme one needs to associate itwith an Issue Type Screen Scheme, which can then be associated with a project.

4.5.5.1. Issue Operations to Screen Associations

Screen Schemes are used to map a field screen to an issue operation view and therefore controlwhich Screen is shown to the user when they are performing that operation. The issue operations thatcan have a mapping to a Screen are:

• Create Issue - a Screen that is shown when an issue is being created• Edit Issue - the Screen that is shown when an issue is edited.• View Issue - the Screen that is shown when a user views an issue

To access this functionality you need to access the Configure Screen Scheme page:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

JIRA Documentation

Page 91Copyright © 2002-2005 Atlassian All rights reserved.

Page 92: Jira Manual

Link to Administration section

Link to Administration section

3. Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose"Screen Schemes" from the list.

4. If you are using the Standard Edition you will be brought to the Configure screen for theDefault Field Screen. If you are using the Professional or Enterprise Editions you will bebrought to the "View Screen Schemes" page and you will need to select a Screen Scheme byclicking on the "Screens" link next to one of the schemes.

5. You will now be brought to the Configure Screen Scheme page.

Configure Field Screen Scheme page

4.5.5.2. Associate an Issue Operation to a Field Screen

1. The "Add Issue Operation to Screen Association" is located at the bottom of the configurescreen scheme page.

2. Select an issue operation you wish to associate a Screen with.3. Select the desired Screen.4. Click the "Add" button and the new association will be added to the association list.

Note:The View Issue operation only allows one to control the layout of custom fields in the middle of the View Issue page. The ViewIssue page ignores all the non-custom fields on the Screen.

JIRA Documentation

Page 92Copyright © 2002-2005 Atlassian All rights reserved.

Page 93: Jira Manual

Note:There can only be one association for a issue operation per Screen Scheme. If all operations have been associated with a Screen use the'Edit' link next to each operation to change the Screen it is associated with.

Note:If an issue operation does not have a specific mapping to a Screen, the screen that is associated with the Default entry will be used for thatoperation. The Default entry cannot be deleted from a Screen Scheme. You can use the "Edit" link next to the Default entry to change theScreen that it associated with it.

4.5.5.3. Edit an Association

1. Click on the "Edit" link next to the issue operation you wish to edit.2. You will be brought to the "Edit Screen Scheme Item" page.3. Select the screen you wish to change the association to.4. Click on the "Update" button and you will be returned to the screen scheme page.

Edit Screen Scheme Item Page

4.5.5.4. Delete an Association

1. Click on the "Delete" link next to the issue operation you wish to remove.2. The association will be automatically removed from the list.

4.5.5.5. Screen Schemes

In Professional and Enterprise Editions it is possible to create multiple Screen Schemes, in theStandard Edition you can only edit the Default Screen Scheme. The Screen Scheme operations areavailable from the View Screen Schemes page.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose

JIRA Documentation

Page 93Copyright © 2002-2005 Atlassian All rights reserved.

Page 94: Jira Manual

"Screen Schemes" from the list.4. This will bring you to the "View Screen Schemes Page".

View Screen Schemes Page

Add a Field Screen Scheme

1. The "Add Screen Scheme" form is located at the bottom of the Field Screen Schemes Page.2. Enter the name of the new field screen.3. You can optionally add a description of the field screen.4. Select a default field screen. The default screen will be used for views that do not have an

association.5. Click on the "Add" button. The screen will automatically update the field screen schemes list

with the new field screen scheme.

Edit a Field Screen Scheme

1. Click on the "Edit" link next to the selected Screen Scheme.2. You will now be directed to the "Edit Screen Scheme" page where you can edit the Screen

Scheme's name and description and the Screen that is associated with the Default Entry of thescheme.

3. Click on the "Update" button.4. You will be brought back to the Screen Schemes page with your updates now applied to the

Screen Schemes list.

JIRA Documentation

Page 94Copyright © 2002-2005 Atlassian All rights reserved.

Page 95: Jira Manual

Edit Screen Scheme Page

Delete a Field Screen Scheme

1. Click on the "Delete" link next to the Screen Scheme you wish to delete.2. Click on the "Delete" button to confirm this action.3. You will be brought back to the Screen Schemes page with the Screen Scheme removed from the

screen schemes list.

Delete Screen Scheme Page

Note:Screen Schemes that are associated with at least one project in the Professional Edition or are used in an Issue Type Screen SchemeEnterprise Edition, cannot be deleted.

Copy a Field Screen Scheme

1. Click on the "Copy" link next to the Screen Screen you wish to copy.2. You will now be directed to the "Copy Screen Scheme" page.3. Enter the name and description of the new Screen Scheme.4. Click on the "Copy" button.5. You will be brought back to the Screen Schemes page and the newly added Screen Scheme will

have the same settings as the original Screen Scheme.

Copy Screen Scheme Page

4.5.5.6. Associating a Screen Scheme with a project in Professional Edition

In Professional Edition Screen Schemes are associated directly with projects. To associate a ScreenScheme with a project please follow these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

JIRA Documentation

Page 95Copyright © 2002-2005 Atlassian All rights reserved.

Page 96: Jira Manual

Link to Administration section

Link to Administration section

3. On the administration page is a list of projects which this user is allowed to manage. Selectthe project of interest.

4. Click on the "Select Scheme" link on the beside the Screen Scheme caption.

Project Admin Page5. Select the screen scheme you wish to associate with this project.

Associate Screen Scheme to Project6. Click on the "Associate" button.

4.5.5.7. Default Screen Scheme in Standard Edition

The Standard Edition of JIRA supports only one Screen Scheme. As soon as the Default ScreenScheme is modified the changes affect all projects and issue types in the system.

4.5.6. Issue Type Screen Schemes

The Enterprise Edition of JIRA provides further flexibility with Issue Type Screen Schemes.Issue Type Screen Schemes associate Screen Schemes to an issue type and hence allow tospecify different Screen for the same operation (e.g. Create Issue) in the same project for issuesof different issue type.

To configure and manage an Issue Type Screen Scheme you need to access the "View Issue TypeScreen Schemes" page:

1. Login as a user with global administrator access.

JIRA Documentation

Page 96Copyright © 2002-2005 Atlassian All rights reserved.

Page 97: Jira Manual

2. Bring up the administration page by clicking either on the "Administration" link on the top bar orthe title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Click the "Issue Fields" sub-menu on the left hand side if it is not open already, and choose"Issue Type Screen Schemes" from the list.

4. This will bring you to the "View Issue Type Screen Schemes" Page.

View Issue Type Screen Schemes Page

4.5.6.1. Add an Issue Type Screen Scheme

1. The "Add Issue Type Screen Scheme" form is located at the bottom of the Issue Type ScreenSchemes page.

2. Enter the name for the new scheme.3. You can optionally add a description.4. Select a Screen Scheme for the Default entry in the new scheme. The Screen Scheme mapped to

the Default entry will be used for issue types that do not have a specific mapping in the scheme.

JIRA Documentation

Page 97Copyright © 2002-2005 Atlassian All rights reserved.

Page 98: Jira Manual

5. Click on the "Add" button. The screen will automatically update the Issue Type ScreenSchemes list with the new Issue Type Screen Scheme.

4.5.6.2. Edit an Issue Type Screen Scheme

1. Click on the "Edit" link next to the selected Issue Type Screen Scheme.2. You will now be directed to the "Edit Issue Type Screen Scheme" page where you can edit

the Issue Type Screen Scheme's name and description as well as the Screen Scheme of theDefault entry.

3. Click on the "Update" button.4. You will be brought back to the Issue Type Screen Schemes Page with your updates now

applied to the Issue Type Screen Schemes list.

Edit Issue Type Screen Scheme Page

4.5.6.3. Delete an Issue Type Screen Scheme

1. Click on the "Delete" link next to the Issue Type Screen Scheme you wish to delete.2. Click on the "Delete" button to confirm this action.3. You will be brought back to the Issue Type Screen Schemes Page with the Issue Type Screen

Scheme removed from the Issue Type Screen Schemes list.

Delete Issue Type Screen Scheme Page

Note:Issue Type Screen Schemes that are associated with a project cannot be deleted.

4.5.6.4. Copy an Issue Type Screen Scheme

1. Click on the "Copy" link next to the field screen you wish to copy.2. You will now be directed to the "Copy Issue Type Screen Scheme" page.3. Enter the name and description of the new Issue Type Screen Scheme.4. Click on the "Copy" button.5. You will be brought back to the Issue Type Screen Schemes Page and the newly added Issue

Type Screen Scheme will have the same scheme settings as the original Issue Type ScreenScheme.

JIRA Documentation

Page 98Copyright © 2002-2005 Atlassian All rights reserved.

Page 99: Jira Manual

Copy Issue Type Screen Scheme Page

4.5.6.5. Configure Issue Type Screen Scheme

The configuration of an Issue Type Screen Scheme involves associating an issue type to a particularScreen Scheme. For example, associating the Bug issue type to the "Default Screen Scheme" andthen associating Improvement to the "Improvement Screen Scheme".

To configure a given Issue Type Screen Scheme click on the "Configure" link next to the selectedIssue Type Screen Scheme from the "View Issue Type Screen Schemes" Page. You will then bedirected to the Configure Issue Type Screen Scheme Page

Configure Issue Type Screen Scheme Page

Associate an Issue Type to a Screen Scheme

1. The "Add Issue Type to Screen Scheme Association" is located at the bottom of the ConfigureIssue Type Screen Scheme Interface.

2. Select an issue type you wish to associate a Screen Scheme with.3. Select the desired scheme.4. Click the "Add" button and the new association will be added to the association list above.

Note:

JIRA Documentation

Page 99Copyright © 2002-2005 Atlassian All rights reserved.

Page 100: Jira Manual

There can only be one association for each issue type. If all issue types have been associated with a Screen Scheme you can use the'Edit' link next to each entry to change the Screen Scheme that is associated with it.

Note:If there is no specific entry for an issue type, the Screen Scheme associated with the Default entry will be used.

Edit an Association

1. Click on the "Edit" link next to the issue type you wish to edit.2. You will be brought to the "Edit Issue Type Screen Scheme Entry" page.3. Select the screen you wish to change this association to.4. Click on the "Update" button and you will be returned to the Issue Type Screen Scheme

interface.

Edit Issue Type Screen Scheme Entry Page

Delete an Association

1. Click on the "Delete" link next to the issue operation you wish to remove.2. The association will be automatically removed from the table.

Note:The Default entry is used for all issue types that do not have a specific entry in the scheme. It cannot be deleted.

4.5.6.6. Associate Issue Type Screen Scheme with Project

Once you have created and configured an Issue Type Screen Scheme to your desired settings youcan now associate the scheme with a Project. This will apply the correct Screen Scheme to eachissue type within the selected project.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 100Copyright © 2002-2005 Atlassian All rights reserved.

Page 101: Jira Manual

Link to Administration section

3. On the Administration page is a list of projects which this user can manage. Select the project ofinterest.

4. Click on the "Select Scheme" link on the beside the Issue Type Screen Scheme caption.

Project Admin Page Enterprise5. Select the screen scheme you wish to associate with this project.

Associate Issue Type Screen Scheme to Project6. Click on the "Associate" button.

4.6. Email notifications

JIRA can send email notifications of all events within the system to users. To enable emailnotifications in JIRA, you must first set up a SMTP Mail Server.

Then, you must set up notification schemes to decide on which events mail notifications are sent andto whom for each project. It is possible to customise your email content. The email address fromwhich notifications are sent from the server can also be configured.

4.6.1. Configuring SMTP Mail Server

Adding a new SMTP Mail Server is done in the Mail Server administration interface.

To add a new SMTP Mail Server, click on "Configure a new SMTP Server". Mail servers take in anumber of parameters as follows:

Name This is the name you assign to this particularmail server. It can be anything you wish to callthis server. (Required)

Description This provides more detail for this particular mailserver.

From address This is the address which email notificationsfrom JIRA will be sent from. (Required)

Email prefix A prefix that will be added to the beginning ofevery email subject. This is useful for your users

JIRA Documentation

Page 101Copyright © 2002-2005 Atlassian All rights reserved.

Page 102: Jira Manual

so that they can filter their email. (Required)

Host Name The hostname or IP address of your SMTPserver (Either this or JNDI Location isrequired, but not both)

Username The user name used to log into your SMTPserver if one is required. (This is required onlyif you require a user name for your SMTPhost.)

Password The password used to log into your SMTPserver if one is required. (This is required onlyif you require a password for your SMTPhost.)

JNDI Location The JNDI location of a javax.mail.MailSessionobject to use when sending email. (Either thisor mail.server is required but not both)

4.6.2. Using Notification Schemes

You can set up notification schemes in the Notification Schemes area of the administrationsection. After setting up the notification scheme, you must add that notification scheme to theproject which you wish the scheme to apply to. To do this, follow the steps below:

1. Select a project in the administration section of JIRA which you wish to set up a notificationscheme for.

2. Then, click on the "select scheme" link

select a notification scheme3. Select, from the drop down box of all available schemes, the one which you wish to apply to

this project.4. Click on 'Associate' button.

The notification scheme should now apply to all issues within that project.

4.6.3. Disabling Email Notifications

To disable email notifications for a project, you can remove the notification scheme from theproject by associating 'None' Notification scheme with the project in the project administrationpage.

Alternatively, you can edit the scheme so that no emails are sent.

4.6.4. Configure Project Email Settings

It is possible to configure the project email address that notifications are sent from. A SMTPMail Server must be configured in order to access this functionality.

JIRA Documentation

Page 102Copyright © 2002-2005 Atlassian All rights reserved.

Page 103: Jira Manual

By setting the "sender" email address for a project, all notifications will be sent from this address.This setting is specific to the project selected and will not affect the configuration of the otherprojects. The default address specified in the SMTP Mail Server configuration is used as the default"sender" address for all projects.

The "sender" email address can be configured as follows:

1. From the Administration view, select "Projects" to view all projects. Select the project to beconfigured.

2. Select "Edit Configuration" from the "Mail Configuration" entry in the project detail list.3. Enter a valid email address in the "sender" field and click "Confirm" to complete the process.

This email address will now be used as the "sender" address in all notifications for this project.4. The default email address as specified in the SMTP Mail Server can be reinstated by clicking the

"Reset" button.

Note:This option is not accessible unless a SMTP Mail Server has been previously configured.

4.7. Permissions

From version 1.2, you can secure various functions (for example adding comments or browsingprojects) via the permissions system. Using the permissions system you can configure exactly whocan access JIRA, and exactly who can do what within JIRA.

Each permission has a permission type (see below for table) and a group to which it applies (or it canapply to everyone).

Anonymous permissions can be created. To create an anonymous permission, set the group to"Anyone". For example creating an anonymous Browse Project permission for a particular projectwill mean that anyone accessing JIRA can browse that project.

There are two types of permissions, global permissions and project specific permissions.

4.7.1. Global Permissions

There are some permissions which are system wide. These are known as global permissions andapply to every project and are edited via "Global Permissions" in administration interface.

These permissions are non project specific and generally refer to the administration of JIRA itself.Examples of global permissions are 'JIRA Administrators' which allows people to administer JIRAand 'JIRA Users' which allows people to user JIRA

This table lists the different global permissions and what functions they secure.

Permission Type Explanation

JIRA Administrators Permission to administer this installation ofJIRA.

JIRA Users Permission to log into JIRA. Note that these'users' cannot actually do anything other thanlogin and logout without other permissions.

Browse Users Permission to allow the browsing of all the usersin the system in a popup screen. Used forselecting usernames

Create Shared Filter Permission to allow user to share a filter globallyor with groups of users.

JIRA Documentation

Page 103Copyright © 2002-2005 Atlassian All rights reserved.

Page 104: Jira Manual

Manage Group Filter Subscriptions Permission to allow user to manage (create anddelete) group filter subscriptions.

4.7.2. Project specific permissions

All other permissions are Project specific permissions and are created using Permission Schemeswhich are then assigned to projects

This table lists the different types of permissions and what functions they secure.

Permission Type Explanation

Administer Projects Permission to administer a project in JIRA

Browse Project Permission to browse projects, use the IssueNavigator and view individual issues.

Create Issue Permission to create issues. Note these userscannot create attachments without Edit Issuepermission.

Edit Issue Permission to edit issues and manage attachments.Note these users cannot delete attachments withoutthe Delete Issue permission.

All updates are saved in the issue change history,hence you will usually want to give this permission toany groups with the Create Issue permission (perhapsthe only exception to this is if you give everyone theability to create issues - you then want to thinkcarefully whether you want to give everyone theability to edit too).

Move Issue Permission to move issues from one project toanother. Note the user can only move issues toa project they have create permission for

Assign Issue Permission to assign issues to other users. (Seealso Assignable User permission below)

Assignable User Permission to be assigned issues. Note these userscannot necessarily assign issues to other users, thatrequires Assign Issue permission.

This permission will usually include your developers.

Schedule Issues Permission to add and edit Due Date of issues.

Resolve Issue Permission to resolve and reopen issues. Thisalso includes the ability to set the FixFor versionfor issues.

Close Issue Permission to close issues. Often useful whereyour developers resolve issues, and a QAdepartment closes them

Add Comments Permission to add comments to issues. Notethat these users cannot delete comments (seeDelete Issue permission).

Delete Issue Permission to delete issues, comments andattachments. Think carefully about which groupsyou assign this permission to - usually it will just

JIRA Documentation

Page 104Copyright © 2002-2005 Atlassian All rights reserved.

Page 105: Jira Manual

be for administrators of the system.

Work On Issue Permission to log work done against an issue.Only useful if time tracking is turned on.

Link Issues Permission to link issues together and createlinked issues. Only useful if issue linking isturned on.

Create Attachments Permission to attach files to an issue.

View Version Control Permission to view the version control (commit)information for issues. Note that to view theVersion Control information the project needs tobe associated with at least one Repository.

Set Issue Security Permission to set the security level on issue tocontrol who can access the issue.(EnterpriseEdition only)

Modify Reporter Permission to modify the reporter when creatingor editing an issue.

View Voters and Watchers Permission to view the voter and watcher list ofan issue.

Manage Watcher List Permission to manage (i.e. view/add/removeusers) the watcher list of an issue.

4.7.3. Permission Schemes

4.7.3.1. What is a Permission Scheme

A Permission Scheme is a set of user permissions that can be applied to any project. This preventshaving to duplicate permissions for different projects.

Once a scheme is set up it can be applied to as many projects as you need

4.7.3.2. Why Permission Schemes?

In the majority of cases a lot of projects will have the same needs as regards permission. i.e Thesame people need to have the same access rights for more than one project.

With permission schemes you only need to set the scheme up once and then it can be applied to asmany projects as you want, giving all these projects the exact same permissions

There will of course be times when different projects will require a different set of permissions. e.gyou might only want a certain department to have access to this project if it is a departmental project.In this case all you need to do is add a new permission scheme for this or any other project

4.7.4. Creating a Permission Scheme

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

JIRA Documentation

Page 105Copyright © 2002-2005 Atlassian All rights reserved.

Page 106: Jira Manual

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Features", click on the link labelled "PermissionSchemes".

View Permission Schemes

4. This will display the "Permission Schemes" page. This page lists all of the PermissionSchemes that JIRA currently has. Click on the "Add Permission Scheme" link.

View Permission Schemes

5. In the "Add Permission Scheme" form, enter a name for the scheme, and a short descriptionof the scheme. Click on the "Add" button.

JIRA Documentation

Page 106Copyright © 2002-2005 Atlassian All rights reserved.

Page 107: Jira Manual

Add a Permission Scheme

6. You will return to the "Permission Schemes" page which now contains the newly added scheme.

View Permission Schemes

4.7.5. Assigning a Permission Scheme to a Project

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. A list of projects is displayed

JIRA Documentation

Page 107Copyright © 2002-2005 Atlassian All rights reserved.

Page 108: Jira Manual

List of Projects

4. Select the project you want by clicking on the project name. This will display the projectdetails

5. Click on the "select scheme" link beside the Permission Scheme caption.

Project Details

6. This will bring up a list of Permission Schemes. Select the Permission Scheme that you wantto associate with this project.

Select Scheme

7. Click the "Associate" button to associate the project with the permission scheme.

4.7.6. Adding Users/Groups to a Permission

1. On the panel on the left, under the title "Features", click on the link labelled "PermissionSchemes".

JIRA Documentation

Page 108Copyright © 2002-2005 Atlassian All rights reserved.

Page 109: Jira Manual

View Permission Schemes

2. Click on the "Permissions" link or on the name of the Permission Scheme to show a list ofpermissions

edit Permissions

3. Click the "Add" link in the "Edit Permissions" header at the top of the page.

Add Users to Permissions

4. This will display the "Add Permission" page. After selecting one or more permissions to add andwho to add the selected permissions to, click the "Add" button. The users/groups will now beadded to the selected permissions

JIRA Documentation

Page 109Copyright © 2002-2005 Atlassian All rights reserved.

Page 110: Jira Manual

Add Users to Permission

(note: screenshot from JIRA Enterprise; in JIRA Professional/Standard only 'Group' isavailable)

5. Repeat the last 2 steps until all required users/groups have been added to the permissions

6. To delete a user/group from a permission click on the "Del" link in the "groups" column

JIRA Documentation

Page 110Copyright © 2002-2005 Atlassian All rights reserved.

Page 111: Jira Manual

Add Users from Permission

4.7.7. Deleting a Permission Scheme

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Features", click on the link labelled "PermissionSchemes".

View Permission Schemes

4. This will display the "Permission Schemes" page. This page lists all of the Permission Schemesthat JIRA currently has. Click on the "Del" link for the scheme that you want to delete.

JIRA Documentation

Page 111Copyright © 2002-2005 Atlassian All rights reserved.

Page 112: Jira Manual

Delete Permission Schemes

5. A confirmation screen will appear. To delete click "Delete" otherwise click "Cancel".

Delete Permission Scheme

6. The scheme will be deleted and all associated projects will be associated to the defaultpermission scheme.

**Note that you cannot delete the default permission scheme.

4.7.8. Copying a Permission Scheme

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 112Copyright © 2002-2005 Atlassian All rights reserved.

Page 113: Jira Manual

Link to Administration section

3. On the panel on the left, under the title "Features", click on the link labelled "PermissionSchemes".

View Permission Schemes

4. This will display the "Permission Schemes" page. This page lists all of the Permission Schemesthat JIRA currently has. Click on the "Copy" link for the scheme that you want to copy.

Copy Permission Schemes

5. A new scheme will be created with the same permissions and the same users/groups assigned tothem.

JIRA Documentation

Page 113Copyright © 2002-2005 Atlassian All rights reserved.

Page 114: Jira Manual

Copy Permission Schemes

4.8. Issue Management

4.8.1. Defining New Resolutions

Resolutions are the ways in which an issue can be closed. JIRA ships with a set of standardresolutions, but you can add your own. To do so, follow the following steps.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Issue Settings", click on the link labelled"Resolutions".

4. This will bring up the View Resolutions page. The page lists the standard resolutions, alongwith a form underneath to add new resolutions.

JIRA Documentation

Page 114Copyright © 2002-2005 Atlassian All rights reserved.

Page 115: Jira Manual

Screenshot of page for adding new Resolutions5. To add a new resolution, fill in the Add New Resolution form. For the name put a short phrase

that best describes your new resolution. For the description, put a sentence or two to describewhen this resolution should be used.

6. The View Resolutions table can be used to edit, delete, set as default, and re-order the resolutionsas they are displayed to the user who is resolving an issue.

4.8.2. Defining New Priorities

Priorities are the level at which an issue should be dealt with. JIRA ships with a set of defaultpriorities, but you can add your own. To do so, follow the following steps.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

JIRA Documentation

Page 115Copyright © 2002-2005 Atlassian All rights reserved.

Page 116: Jira Manual

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Issue Settings", click on the link labelled "Priorities".4. This will bring up the View Priorities page. The page lists the standard Priorities, along with

a form underneath to add new Priorities.

'Add New Priority' screen5. To add a new Priority, fill in the Add New Priority form. For the name put a short phrase that

best describes your new Priority. For the description, put a sentence or two to describe whenthis Priority should be used. For the Icon URL you need to supply the path of a 16 by 16image that has been placed somewhere inside JIRA's opened .war. We suggest you place it in/images/icons:

JIRA Documentation

Page 116Copyright © 2002-2005 Atlassian All rights reserved.

Page 117: Jira Manual

Directory view of icons dir in a JIRA webapp

6. The View Priorities table can be used to edit, delete, set as default, and re-order the Priorities asthey are displayed to the user who is creating, or re-prioritizing, an issue.

4.8.3. Defining New Statuses

Statuses are used to represent the position of the issue in its workflow. A workflow represents abusiness process, or in other words a set of stages that an issue goes through to reach a final or oneof the final stages. Each stage in the workflow (called workflow step) is linked to one issue status,and an issue status can be linked to only one workflow step in a given workflow.

JIRA ships with a few default statuses that are used by the default workflow, but in JIRA Enterpriseand Professional editions you can add your own statuses and customise the workflow. To do so,follow the following steps.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Open the left-hand sub-menu titled "Issue Settings" if it is not open already and click on the linklabelled "Statuses".

4. This will bring up the View Statuses page. The page lists the existing Statuses, along with a formunderneath to add a new Status.

JIRA Documentation

Page 117Copyright © 2002-2005 Atlassian All rights reserved.

Page 118: Jira Manual

'Add New Status' screen5. To add a new Status, fill in the Add New Status form. For the name put a short phrase that

best describes your new Status. For the description, put a sentence or two to describe whatstage this Status represents. For the Icon URL you need to supply the path of a 16 by 16image that has been placed somewhere inside JIRA's opened .war. We suggest you place it in/images/icons:

Directory view of icons dir in a JIRA webapp

JIRA ships with a number of images that can be used as status icons. These images arelocated in the /images/icons directory inside the JIRA .war and include:

• status_assigned.gif• status_closed.gif• status_document.gif• status_down.gif• status_email.gif• status_generic.gif• status_information.gif• status_inprogress.gif• status_invisible.gif• status_needinfo.gif• status_open.gif

JIRA Documentation

Page 118Copyright © 2002-2005 Atlassian All rights reserved.

Page 119: Jira Manual

• status_reopened.gif• status_resolved.gif• status_trash.gif• status_unassigned.gif• status_up.gif• status_visible.gif

6. The View Statuses table can be used to edit and delete Statuses. Please note that only statusesthat are not used in any workflow can be deleted.

4.8.4. Configuring File Attachments

To Configure File Attachments takes two steps. The first step is configuring JIRA to allowattachments. This is a global setting, and requires space on the server to save the attachments in. Thesecond step is to grant the "Create Attachments" permissions to relevant projects (indirectly, bymodifying Permission Schemes).

4.8.4.1. Step 1: Turning on Attachments.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Global Settings", click on the link labelled"Attachments".

4. You will be shown a status page stating whether attachments are on or off:

JIRA Documentation

Page 119Copyright © 2002-2005 Atlassian All rights reserved.

Page 120: Jira Manual

Page for enabling attachments

Attachments can be enabled and configured by editing the configuration. Image attachmentthumbnails can also be enabled from this screen.

4.8.4.2. Step 2: Allowing attachments in a Permission Scheme.

The "Create Attachments" permission now needs to be enabled in the Permission Scheme ofprojects you wish to enable attachments for.

1. Go to the Administration Page.2. Go to the "Permission Schemes" page, accessible from under "Schemes" in the navigation

pane on the left of the screen.3. In the permission scheme for relevant projects, click the "Permissions" link to edit the

scheme.

Permission Schemes4. In the Permission drop down, find "Create Attachments", and click "Add".

JIRA Documentation

Page 120Copyright © 2002-2005 Atlassian All rights reserved.

Page 121: Jira Manual

Adding a permission to a scheme5. In the User Group drop down, select an appropriate group, eg "Anyone" or "jira-users".

Adding a permission to a scheme

4.8.4.3. Changing the attachment size limit

The default maximum attachment size is 10Mb. This can be changed, but not yet through the webinterface (see JRA-2994). To change this, editatlassian-jira/WEB-INF/classes/webwork.properties and change thewebwork.multipart.maxSize parameter.

4.8.4.4. Attachments on Issue Creation

In order to attach a file on issue creation - it is necessary to:

• Ensure that the 'Attachment' field is not hidden within the field layout associated with the specifcissue type

• Enable 'Attachments'

4.8.4.5. Multiple Attachments

JIRA Documentation

Page 121Copyright © 2002-2005 Atlassian All rights reserved.

Page 122: Jira Manual

JIRA allows multiple files to be attached to an issue in one operation. From the 'Attach File'page, the user can toggle between multiple and single attachment screens by selecting the'Attach multiple' files link. The attachment form will retain the multiple/single attachmentpreference for that specific user for the duration of the user's session or until manually changed.

The number of attachment 'boxes' to be displayed on the multiple attachment screen can beconfigured through the property jira.attachment.number in thejira-application.properties file. This setting is configured to 3 by default. It isnecessary to restart JIRA in order for a property change to take effect.

4.8.5. Issue Scheduling

4.8.5.1. Enabling Issue Scheduling

By default JIRA ships with Issue Scheduling feature disabled. To enable Issue Scheduling atleast one group of users has to be given the "Schedule Issues" permission. To assign thispermission to one or more groups please refer to the Permissions documentation

4.8.5.2. Scheduling An Issue

An issue can be scheduled when it is created, or at a later stage using the edit issue feature, bypopulating the "Due Date" field of the issue. Keep in mind that only users with "Schedule Issues"permission can populate the "Due Date" field.

4.8.5.3. Searching

It is possible to search for issues using the Issue Navigator. Choose "Find Issues" in the title barmenu to bring up the Issues Navigator. There are two ways to search for issues based on the "DueDate" field. The first way is using fixed date values, the second is using periods that are relativeto the current date.

Fixed Date Searchers

There are two text fields in the Issue Navigator that allow searching based on the "Due Date"field. To perform a search for all issues that are due after a certain date enter the date into the"Due After" text field of the Issue Navigator. For example to find all issues that are due after 1stJune 2003, enter 1-6-2003 into the "Due After" field. It is also possible to use the Calendar popupto select a date by clicking the calendar icon on the right of the "Due After" text field. To searchfor issues that are due before a certain date, enter the date into the "Due Before" date. Forexample, to find all issues that are due before 1st July 2003, enter 1-7-2003 into the "DueBefore" text field. It is also possible to search for issues that are due between two dates bypopulating the "Due After" and the "Due Before" text fields.

Relative Period Search

It is possible to perform a search that is relative to the time when it is run. These kind of searchesare more useful when they are saved. For more instructions on how to save search filters pleaserefer to saving search filters. For example, it is possible to do a search for issues that are dueseven days from now. To do this, enter 7d into the "Due Date To" text field of the IssueNavigator. If the search is saved and run the next day, the issues that are due in seven days fromthe time that the search is run will be retrieved. Thus, this search will find all issues that are duewithin a week every time it is run.

The values that are entered into the "Due Date From" and "Due Date To" fields have to conform

JIRA Documentation

Page 122Copyright © 2002-2005 Atlassian All rights reserved.

Page 123: Jira Manual

to a special syntax (described below). However it is also possible to use the Due Date popup byclicking the icon to the right of the "Due Date To" text field to specify the search period.

Due Date Popup

The Due Date popup is shown below.

Due Date selector• To search for issues that are overdue at the time of the search select the first radio button and

click "OK".• To search for issues that are overdue by more than a certain number of days, populate the text

field in the second row, (select the second radio button, if it is not selected for you automatically)and click OK.

• To search for issues that are due in the next certain amount of days and are not overdue at thetime of the search, populate the text field in the third row with the number of days, and choose"and not" from the select box in the third row. Select the third radio button, if one it was notselected automatically, and click "OK".

• To search for issues that are due in the next certain amount of days and are overdue at the time ofthe search, populate the text field in the third row with the number of days, and choose "and"from the select box in the third row. Select the third radio button, if one it was not selectedautomatically, and click "OK".

• The fourth row of the popup is used for arbitrary period searches. Use the "to" text field tospecify the upper bound of the search, and the "from" text field to specify the lower bound of thesearch. A blank text field means no bound. Populating the text fields in the fourth row, actuallyhas the same effect as populating the "Due Date From" and "Due Date To" text boxes in theIssue Navigator. The fields in the popup expect entries in the same syntax as the ones in the IssueNavigator. The syntax is described below

JIRA Documentation

Page 123Copyright © 2002-2005 Atlassian All rights reserved.

Page 124: Jira Manual

Relative Period Search Syntax

The "Due Date From" and "Due Date To" fields use a special syntax to denote time periodbounds. The syntax uses numbers and abbreviations that follow the numbers to represent whatthe numbers actually mean. The abbreviations are "w" for weeks, "d" for days, "h" for hours and"m" for minutes. For example, to specify 10 days in the future use "10d" or "1w and 3d". Tospecify a period bound in the past prefix the value with the "-" sign. For example to specify 2days, 4 hours and 3 minutes ago, use "-2d 4h 3m".

4.8.6. Configuring Issue Linking

Issue Linking allows you to create an association between issues. For instance, an issue mayduplicate another, or its resolution may depend on another's.

There are two steps involved in configuring 'Issue Linking'. The first step is configuring JIRA toallow issue links. This is a global setting. The second step is to the create the issue link typesrequired. These are also global.

4.8.6.1. Step 1: Turning on Issue Linking.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Global Settings", click on the link labelled "IssueLinking".

4. You will be shown a status page stating whether linking is enabled. If it is not, click the"Activate" button.

5. You will be shown the status page again, this time stating that Issue Linking is enabled.

4.8.6.2. Step 2: Creating Issue Link Types.

1. On the Issue Linking page there will now be a form titled "Add New Link Type".

JIRA Documentation

Page 124Copyright © 2002-2005 Atlassian All rights reserved.

Page 125: Jira Manual

Form for adding a new link type2. To create a new link type, say Duplicate, proceed as follows:

• enter "Duplicate" in the "Name" text field• enter "duplicates" in the "Outward Link Description" text field• enter "is duplicated by" in the "Inward Link Description" text field

3. Click the add button.4. This returns to the link type management page, with a new section listing the "Duplicate" issue

linking type. Here you can edit or delete the relationship, as required.

List of declared link types

4.8.6.3. Step 3: Linking Issues.

1. To link an issue to another issue, click on the link 'Link this Issue to Another Issue' on the 'View'Issue page.

JIRA Documentation

Page 125Copyright © 2002-2005 Atlassian All rights reserved.

Page 126: Jira Manual

Link Issue2. This will bring up the 'Link Issue' form.

Link Issue3. Select the link type and enter the key of the issue that you want to link to. It is also possible

to link to multiple issues.

You can optionally add a comment.

Click on the "Link" button.

4. You will see the issue page again, with a new section listing the issues that are linked to thisissue

JIRA Documentation

Page 126Copyright © 2002-2005 Atlassian All rights reserved.

Page 127: Jira Manual

List of linked issues

4.8.7. Sub-task Issues

Sub-task issues are usually used to split up a parent issue into a number of tasks which can beassigned and tracked separately. Splitting issues into smaller tasks often provides a better picture ofthe progress on the issue and allows each party that needs to be involved in resolving the issue tobetter understand what part of the process they are responsible for. Sub-tasks have all the propertiesof regular issues such as summary, reporter, assignee, fix versions, etc. Their "issue type" must beone of the sub-task issue types rather than one of the regular issue types.

Please note that:

• Sub-tasks are only supported in Professional and Enterprise editions of JIRA• At the moment JIRA upports only "one-level" of sub-tasks. That is sub-tasks cannot have

sub-tasks of their own.• Sub-tasks always belong to the same project as their parent issue.

4.8.7.1. Enabling sub-tasks

Sub-tasks are disabled by default. To enable sub-tasks:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Open the Global Settings sub-menu on the left hand side if it is not open already, and chooseSub-Tasks from the list.

4. After the Sub-Tasks administration screen loads please click the "Enable" link. The page shouldreload and inform you that the sub-tasks are now enabled. A default sub-task issue type has alsobeen automatically created. You can edit it by selecting the Edit link in the Operations column.

4.8.7.2. Sub-task issue types

Sub-tasks must be assigned one of the sub-task issue types which are different to regular issue types.Sub-task issue types can be customised on the Sub-Tasks administration screen (which is describedin the previous section). The administration screen allows to create, edit and delete sub-task issue

JIRA Documentation

Page 127Copyright © 2002-2005 Atlassian All rights reserved.

Page 128: Jira Manual

types. Please note that you must have at least one sub-task issue type to take advantage of JIRA'ssub-task support.

4.8.7.3. Creating sub-tasks

Please note, that a user must have the Create Issue permission in the parent issue's project to beallowed to create sub-tasks. To create a sub-task:

1. Navigate to an issue which you would like to be the parent issue for the sub-task you areabout to create.

2. Select "Create sub-task" from the Operations menu on the left-hand side.3. On the presented page select a sub-task issue type for the new sub-task and click "Next"4. On the next screen please fill in the sub-task details. You must at least provide a summary for

the sub-task and any other required fields (which are italicised and highlighted by an asterix).5. Click the "Create" button at the bottom of the page. The sub-task will be created and you

should see the View Issue screen with the sub-tasks details that you have provided. The parentissue's summary and issue key are displayed above the sub-task's summary. You can easilyreturn to the parent issue by clicking its summary or issue key.

4.8.7.4. Working with sub-tasks

The View Issue screen shows a list of all sub-tasks for an issue:

Viewing SubtasksThe sub-task list has two views: All and Open. The All view simply lists all sub-tasks, while theOpen view only shows sub-tasks that have not been resolved (i.e. do not have a resolution). It ispossible to reorder sub-tasks by using the up and down arrows to, for example, organise the listin the order of intended execution or priority. It is also possible to take "actions" on the sub-tasksdirectly from the screen shown above by clicking one of the "Operations" links in the right-mostcolumn.

Please note that if a user has a Create Issue permission in the issue's project, they can also createa sub-task directly from the View Issue screen.

4.8.7.5. Sub-tasks and searching

When sub-tasks are enabled two extra entries should appear in the Issue Navigator's Issue Typefield. These entries are: Standard Issue Types and Sub-Task Issue Types. If no entries are selectedfrom the Issue Type field then the search will return all the regular as well as sub-task issues thatmeet the rest of the search criteria. To search only regular issues please select the Standard Issue

JIRA Documentation

Page 128Copyright © 2002-2005 Atlassian All rights reserved.

Page 129: Jira Manual

Types entry. To search sub-task issues only select the Sub-Task Issue Types entry. Of course, youcan narrow down the search to specific issue types by selecting them in the Issue Type field, ratherthan using the Standard Issue Types or the Sub-Task Issue Types entries.

The search results depict sub-task issues by displaying the parent issue's issue key above thesub-task's summary, as shown below:

Subtasks Searching

Sub-Tasks Issue Navigator column

It is also possible to add a "Sub-Tasks" column to your Issue Navigator results. The "Sub-Tasks"column displays the issue keys of all issue's sub-tasks (if any) as shown in the screenshot above.Please follow instructions in the "Issue Navigator Columns" section to add the "Sub-Tasks" columnto your Issue Navigator.

4.8.7.6. Sub-tasks and workflow

It is possible to restrict the progression of an issue through workflow depending on the state of theissue's sub-tasks. For example, it might be necessary to restrict an issue from being resolved until allof its sub-tasks are resolved. To achieve this a custom workflow will need to be created. In theworkflow please use the Sub-Task Blocking Condition on the transitions that should be restricted bythe sub-tasks' state.

4.8.7.7. Disabling sub-tasks

Sub-tasks are disabled from the sub-task administration screen. To disable sub-tasks please followthe following steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 129Copyright © 2002-2005 Atlassian All rights reserved.

Page 130: Jira Manual

Link to Administration section

3. Open the Global Settings sub-menu on the left hand side if it is not open already, and chooseSub-Tasks from the list.

4. After the Sub-Tasks administration screen loads please click the "Disable" link. The pageshould reload and inform you that the sub-tasks are now disabled.

Note:Sub-tasks cannot be disabled if at least one sub-task exists in the system. Please remove the existing sub-tasks before disabling thisfeature.

4.8.8. Trackback linking

Trackback linking is a means by which a page can tell another page that it has been linked to.

For instance, say that a user writes a URL in a JIRA comment:

Comment containing URL to trackback-enabled siteIf the URL is to a trackback-enabled web application like a weblog, Confluence page or anotherJIRA site, the linked-to page will be told that it was linked to, and can automatically create linkback to the linker:

Linked-to page linking back to the linker

4.8.8.1. Configuring trackbacks

In JIRA, you can configure whether to:

• display links to external pages that link to your pages (accept incoming trackback pings)• notify external pages that they have been linked to (send outgoing pings)

The default configuration is to display incoming links, but not notify linkees:

JIRA Documentation

Page 130Copyright © 2002-2005 Atlassian All rights reserved.

Page 131: Jira Manual

Default trackback configuration

Ensure public visibility

In order for trackbacks to work, the page linked to must be publicly accessible. Eg. it cannot beanother JIRA issue which requires a login to access. Trackback works by parsing the linked-to pageto find a 'trackback ping URL' hidden in a comment. Information about the linker (URL, title,excerpt, sitename) is then posted to the trackback ping URL.

Also, when linking to a JIRA instance, make sure its base URL is correct in Admin -> GeneralConfiguration.

Temporarily disabling trackbacks

Trackback pings can be disabled (eg. during a Bugzilla/Mantis import) by setting thejira.trackback.senddisabled=true flag on startup.

4.8.8.2. Technical Information

If you would like to learn more about how trackback works, please have a look at the Trackbackspecification.

4.8.8.3. Technical Information

If you would like to learn more about how trackback works, please have a look at the Trackbackspecification.

4.8.9. Configure Time Tracking

To enable time tracking in JIRA, you must first activate it and then assign permissions to groups orusers to log work

4.8.9.1. Step 1: Turning on Time Tracking.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

JIRA Documentation

Page 131Copyright © 2002-2005 Atlassian All rights reserved.

Page 132: Jira Manual

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Global Settings", click on the link labelled "TimeTracking".

Activate Time Tracking4. As you can see, by default, time tracking is OFF. To activate, you may first want to configure

the Hours Per Day and Days Per Week fields. We understand that not everyone's work dayis 24 hours long :). Click Activate to turn this feature ON.

Note:To change the Hours Per Day and Days Per Week once Time Tracking is activate you will need deactivate and the reactivate TimeTracking with the new values.

4.8.9.2. Step 2: Allowing users to log work.

To be able to log work on an issue, users or groups must first be assigned permissions. To do so,edit the permission scheme associated with the project you want people to log work against.More detailed instructions:

1. Once you have activated time tracking you should see the following display:

JIRA Documentation

Page 132Copyright © 2002-2005 Atlassian All rights reserved.

Page 133: Jira Manual

Display once time tracking is enabled2. Click the Permission Schemes link.3. Select the relevant permission scheme.

Note:JIRA's Default Permission Scheme or some of your permission schemes may be shared amongst multiple projects. You may not wantusers to be able to log work against ALL of these projects. If not, you should create a new permission scheme and associate this with thespecific project(s) you want work to be logged against.

4. In the row labelled "Work on Issues" click the add button.

Adding the Work on Issues permission5. Then select a group you wish to be able to log work on issues. Then click the "Add" button.

4.9. Issue Types

4.9.1. Managing Issue Types

JIRA ships with a set of default issue types to help your get started with the issue tracker. Everyone'sneeds are different and so JIRA also allows you to add, edit and delete your own custom issue types.

4.9.1.1. Creating, Editing and Deleting Issue Types

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Issue Settings", click on the link labelled "Issue Types".

JIRA Documentation

Page 133Copyright © 2002-2005 Atlassian All rights reserved.

Page 134: Jira Manual

4. This will bring up the Manage Issue Types page. The page lists all issue types, along with aform underneath to add new issue types.

Manage Issue Types Screen5. To add a new Issue Type, fill in the Add New Issue Type form. For the name put a short

phrase that best describes your new Issue Type. For the description, put a sentence or two todescribe when this Issue Type should be used. For the Icon URL you need to supply the pathof a 16 by 16 image that has been placed somewhere inside JIRA's opened .war. We suggestyou place it in /images/icons:

JIRA Documentation

Page 134Copyright © 2002-2005 Atlassian All rights reserved.

Page 135: Jira Manual

Directory view of icons dir in a JIRA webapp

You can edit and delete an existing issue type by clicking on the Edit and Del links on the right.

4.9.1.2. Ordering and setting defaults

1. In Standard Edition, you can edit the defaults and re-order issue types by clicking on the link"Edit order and default issue type". Reordering issue types changes the order they are displayedto the user who is creating an issue. In Professional and Enterprise Editions of JIRA, it ispossible to configure different sets of issue types for each project. Each set can have a differentorder and default issue type. Refer to Managing Issue Type Schemes section for moreinformation.

2. Clicking on the "Edit order and default issue type" link will display the screen below. Here youcan select the issue type that will be selected by default. If you don't select a default issue type,the user will see an option "Please Select..." when they're creating an issue.

Setting defaults and reordering issue types3. To re-order the issue types, drag and drop the issue types into the correct order. Note that none

of the changes are persisted until you click on the Save button. You can revert to the last savedchanges any time by click on the Reset button. Clicking on Cancel will not save any changes.

JIRA Documentation

Page 135Copyright © 2002-2005 Atlassian All rights reserved.

Page 136: Jira Manual

Drag and Drop

4.9.2. Managing Issue Type Schemes

JIRA Professional and Enterprise Editions allow to restrict the set of available issue types foreach project. This is achieved through the use of Issue Type Schemes. Issue Type Schemesrepresent a sub-set of issue types with its own order and default value. An issue type scheme canbe shared across multiple projects so that a group of similar projects can share the same issuetype settings.

For example, in your company all projects may be one of two types, a development project or asupport project. You could then create one scheme called Task with issue types Bug andDevelopment and another called Support Issue Types, with Development Query and SupportRequest. You can then associate each scheme to the appropriate projects, giving your users adifferent set of issue types depending on which projects they decide to create issues in. Usingschemes also gives you added benefit that any change you make to a scheme is seen across allprojects that are associated with the scheme. In this example, adding a new issue type to allsupport projects only requires a simple step of adding the issue type to the Support Issue Typesscheme.

You can find out how to achieve this and more below.

4.9.2.1. Managing Issue Type Schemes

The Issue Type Schemes can be found on the Issue Type Schemes tab on the Issue Type page.Here you can see all existing Issue Type Schemes, their related issue types and the associatedprojects. Each JIRA installation has one Default Issue Type Scheme that contains all existingissue types. This scheme is used for all newly created projects.

JIRA Documentation

Page 136Copyright © 2002-2005 Atlassian All rights reserved.

Page 137: Jira Manual

Manage Issue Types Schemes Screen

Creating a new scheme

1. To create a new scheme, enter the name and description for the new scheme. Ensure that thename is meaningful as this will be visible to other administrators and will allow them to betterreuse the scheme.

2. Click on the Add button and the screen below will be displayed.

Manage Issue Types Scheme3. Set the default for the new scheme from the select list. Add a new issue type to your scheme by

dragging and dropping the issue type from the right hand list to the left. You can similarly

JIRA Documentation

Page 137Copyright © 2002-2005 Atlassian All rights reserved.

Page 138: Jira Manual

reorder the issue types in the desired order by dragging and dropping them into the rightpositions.

Dragging and dropping issue types4. If you need an issue type that does not currently exist, you can add this easily in using the add

issue type form at the bottom of the page. This will add the issue type to the system and alsoadd it to the scheme you're editing.

5. Once you've finished with your scheme. Click on the Save button to persist your changes.Note that unless you click on Save, no scheme will be created.

Editing a scheme

The process of editing a scheme is identical to the creation process. You can set defaults, reorder,add and remove issue types as before. However, if you're removing issue types from the schemeand there are issues associated with that issue type, you will be required to use the Issue TypeMigration Wizard which will move your issues from the obsolete issue type to a valid one. Notethat if you cancel out of this process at any time, your changes will not be committed. See belowfor more information about the migration wizard.

Associating a scheme to projects

You can restrict the issue types available by associating your Issue Type Scheme to variousprojects. Click on the Associate link and simply choose the projects that you wish your scheme toapply to. All selected projects will change from their current scheme to the selected scheme.

If the new scheme does not have an issue type that was present in the old scheme, you will beasked to use the Issue Type Migration Wizard to migrate the issues.

Associated Issue Type Scheme to Project

4.9.2.2. Managing Schemes for a Project

JIRA Documentation

Page 138Copyright © 2002-2005 Atlassian All rights reserved.

Page 139: Jira Manual

When updating a project you may often want to quickly restrict its issue types. However, theavailable Issue Type Schemes may not always be applicable, or you do not know which schemes tochoose. The Select Issue Type Scheme screen makes this process simpler.

1. Click on the select link for Issue Type Scheme on the View Project page.

Select an Issue Type Scheme for Project2. This will bring you the screen below.

Select an Issue Type Scheme for Project3. There are three ways you can select your issue type scheme. Select the radio button that is most

relevant.

1. Choose an existing issue type scheme - If you know the name of you scheme (e.g. SupportIssue Type Scheme), you can immediately choose it from the list. You will see a preview ofissue types that would be available for your project as well as the description of the scheme.

2. Choose a scheme that is the same as an existing project - If you do not know the name of thescheme you would like to use, but you do know the name of the project whose set of issuetypes you wish to use for the project you are editing, please select this option. You will beprompted to select a project and the scheme that is currently associated with the selectedproject will be used for your project as well.

Select scheme same as an existing project3. Create a new scheme and associate with current project - Select this option if you can't find

any existing scheme that fits your needs and would like to quickly create a new scheme.Simply select the relevant issue types for your project and a new scheme will be created with

JIRA Documentation

Page 139Copyright © 2002-2005 Atlassian All rights reserved.

Page 140: Jira Manual

the default name and order. You can edit the name, default value and order of the newlycreated scheme later.

Quickly add a new scheme4. If after you make your changes there are any issues in the selected project that will have

obsolete issue types, they will have to be migrated with the Issue Type Migration Wizard.

4.9.2.3. Issue Type Migration Wizard

This Issue Type Migration Wizard allows you to migrate issues from an obsolete issue type to avalid issue type. The wizard will be triggered whenever an action (e.g. editing a project's issuetype scheme) results in an issue type becoming obsolete (not available in the scheme).

The wizard bears some resemblance to the Bulk Move function except for that you can't changethe project of the issues. The major steps are:

1. Overview - provides a summary of the issues that will require migration2. Choose Issue Type3. Set new status4. Set field values5. Confirmation

Steps 2 to 4 will be repeated for each issue type that requires migration. After you have migratedall the issues you'll see a summary of changes that will occur. If you click on the Confirm button,the wizard will migrate your issues to the new issue types and then complete your action.

Please refer to the Bulk Move documentation for more information on status changes and settingof fields values.

4.10. Custom Fields

4.10.1. Custom Fields Overview

Custom field types were introduced in JIRA 2.0 to allow greater customisability of the types ofdata collected with your issue. In 3.0, the number types have been expanded and you can evenadd your own custom field types. JIRA 3.2 adds a new level of flexibility to your custom fields.You can now configure your custom fields to only appear for certain issue types in certainprojects or multiple issue types over multiple projects! The power is in your hands. On top ofthat, you can even configure each custom field differently for each context. On this page we'lloutline some of the key concepts relating to custom fields.

For building you own custom field types, check out the tutorial.

Note:Custom fields are optional. This means you can add custom fields late in a project, without requiring existing issues to be changed.

JIRA Documentation

Page 140Copyright © 2002-2005 Atlassian All rights reserved.

Page 141: Jira Manual

The current issues contain no value for the custom field, even if a default is defined.

4.10.1.1. Custom Field Types

JIRA 3.3 now ships with over 20 custom field types and you can find more custom field types andother examples in the JIRA Extensions space (e.g. JIRA Toolkit). A sample of the types are listedbelow.

Custom Field Type Description

Cascading Select Multiple select lists where the options for thesecond select list dynamically updates based onthe value of the first

Date Picker Input field allowing input with a date picker andenforcing valid dates

Free Text Field (unlimited text) Multiple line text-area enabling entry of longertext strings

Multi Checkboxes Checkboxes allowing multiple values to beselected

Multi Select Select list permitting multiple values to beselected

Number Field Input field storing and validating numeric(floating point) values

Project Picker Select list displaying the projects viewable bythe user in the system

Radio Buttons Radio buttons ensuring only one value can beselected

Select List Single select list with a configurable list ofoptions

Text Field Basic single line input field to allow simple textinput of less than 255 characters

URL Field Input field that validates a valid URL

User Picker Choose a user from the user base via a popuppicker window.

Version Picker Select list with the all versions related to thecurrent project of the issue

4.10.1.2. Search templates

Search templates are responsible for indexing a custom field as well as making it searchable throughthe issue navigator. Each of the default custom field types have a related pre-configured searchtemplate.

4.10.1.3. Custom field context

The custom field context (introduced in JIRA 3.2) allows your custom field to be configured (that is,enabled) for any numerous different combinations of issue types and projects. You can havedifferent default values in different projects, different options for different projects and the like.

The context is made up of an issue type component and a project component. You can select

JIRA Documentation

Page 141Copyright © 2002-2005 Atlassian All rights reserved.

Page 142: Jira Manual

multiple issue types and multiple projects or declare the custom field to be global.

Issue type contextThe context itself can now be modified at any time. You can change the project or issue typeapplicable for the custom field at any time.

Project context

4.10.1.4. Custom field configuration schemes

If you start digging deeper into custom fields (or indeed, any part of JIRA) you'll notice manyreferences to schemes. Custom field configuration schemes are how JIRA allow you to managecustom field contexts and configuration. A configuration scheme is configuration set for a groupof issue types for a set of projects. If you have two different default values, you'd need twoconfiguration schemes and so on.

JIRA Documentation

Page 142Copyright © 2002-2005 Atlassian All rights reserved.

Page 143: Jira Manual

Project contextSpecific project based configuration schemes will override configurations from a Global projectcontext. So you could configure a default global scheme for all projects and the configure for eachprojects that are different. You may for example, have a global select lists that have values thatapplies for 80 of your 81 projects but is different in the other. You'd configure a one configurationscheme for global context and other for the specific field that is different.

Also note that to avoid conflicts, a project can only be part of a single configuration scheme. Onceyou've selected a specific project to be part of a scheme, it will be removed from the list of selectableoptions

4.10.2. Adding Custom Fields

4.10.2.1. Steps to define a custom field

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 143Copyright © 2002-2005 Atlassian All rights reserved.

Page 144: Jira Manual

Link to Administration section

3. On the menu bar on the left, under "Issue Fields" sub-menu click the Custom Fields link, andthen click on the Add Custom Field link on the presented page.

Custom field creation screen4. Select from the list the appropriate custom field type.

5. Click on the next button.

JIRA Documentation

Page 144Copyright © 2002-2005 Atlassian All rights reserved.

Page 145: Jira Manual

JIRA Documentation

Page 145Copyright © 2002-2005 Atlassian All rights reserved.

Page 146: Jira Manual

Custom field creation screen6. Fill in the Field Name and Field Description. The Field Name will appear as the custom

field's title in both entering and retrieving information on issues. The Field Description isdisplayed beneath the data entry field when entering new issues and editing existing issues,but not when browsing issues.

7. Select an appropriate Search Template. Pre-configured search templates are available foreach shipped custom field type. A description of each search template will appear next to theselect list when you select one.

8. Select one or any number of issue types that this custom field will be applicable for. You canchange this value in the future if you need to.

9. Select the applicable project context. The custom field will be available to the selectedprojects. If issue types were chosen, it will only appear for those issue types for that project

10.Click Finish.

11.This will bring you to the screen association page where you can put your newly createdcustom field onto a screen in JIRA. You can associate the field any screens or tabs in JIRA.You must associate a field to a screen before it will be displayed. New fields will be added tothe end of a tab.

Screen association field12.Clicking Update will return you to the View Custom Fields page that displays a summary of

the custom fields in the system. You can edit, delete or configure custom fields here. Thispage is also directly accessible from the menu bar to the left of all Administration pages.

4.10.3. Configuring Custom Fields

On this page, we show you how you can configure your custom field after you've created them.

4.10.3.1. Configuring Custom Fields

For most custom fields, you can configure its default values and set the options for lists. Whenyou click on the configure link, you'll be faced with a page similar to the one below.

JIRA Documentation

Page 146Copyright © 2002-2005 Atlassian All rights reserved.

Page 147: Jira Manual

Configuring a custom fieldYou'll notice that there is a configuration scheme named Default Configuration Scheme for.... This isthe configuration scheme created automatically by JIRA when you initially added your custom field.The Applicable contexts for scheme refers to context that this scheme will be applied to; whichprojects & issue types the defaults and options will be displayed. For most people this will be onlything you need to know about custom field configuration schemes. You can edit the context byclicking Edit configuration or the edit icon on the top left hand corner.

JIRA Documentation

Page 147Copyright © 2002-2005 Atlassian All rights reserved.

Page 148: Jira Manual

Configuring a custom field configuration schemeHere you can edit the label and description of the configuration scheme. These are used foradministrative purposes only and isn't shown to the end users. You can also change the contextthat this scheme is to be applied to here. It's now easier than ever to change the projects or issuetypes for the configuration context.

JIRA Documentation

Page 148Copyright © 2002-2005 Atlassian All rights reserved.

Page 149: Jira Manual

Options of a custom fieldSelect lists, multi select lists and cascading selects lists can have their options manipulated. You canadd, remove and sort the options alphabetically. You can also have HTML in an option value. Besure to use complete all tag pairs and ensure that it will display correctly.

Defaults of a custom fieldClick the Edit defaults to modify the default value of a custom field for this configuration scheme.Setting the defaults of will take you to a screen that is particular to the issue type. Certain customfields such as calculated custom fields may not allow for defaults to be selected and will not have the"edit defaults" link.

4.10.3.2. Managing multiple configuration schemes

Since JIRA 3.2, it is now possible to configure a custom field differently for different issue types andproject combinations. This can be achieved through configuring different custom field schemes.

1. Click on the Add context link to create a new custom field configuration scheme.

JIRA Documentation

Page 149Copyright © 2002-2005 Atlassian All rights reserved.

Page 150: Jira Manual

Adding a new custom field configuration scheme2. You'll see a screen that very similar to the edit configuration scheme. Here you can select the

applicable context for your new configuration scheme. One difference is that the projectcontext will only show projects and options that have not be previously selected in anotherconfiguration scheme. So if you already have an existing "Global" configuration scheme, thatoption will not be available. Moreover, be aware that project specific configuration schemewill override Global configurations. For example, if you have one global configurationscheme with one default value and a project configuration scheme with a different value, theproject value will be used instead.

JIRA Documentation

Page 150Copyright © 2002-2005 Atlassian All rights reserved.

Page 151: Jira Manual

Setting context for configuration scheme3. Click Add4. You will now have a new configuration scheme that can be reconfigured separately to the default

scheme. You can add different default values and options for each one. In the screen showbelow, the Database custom field have specialised options and defaults for two to the projects,which will over-ride the global options list.

JIRA Documentation

Page 151Copyright © 2002-2005 Atlassian All rights reserved.

Page 152: Jira Manual

Multiple configuration scheme

4.11. Renderers

4.11.1. Renderers Overview

Renderers were introduced in JIRA 3.4 to allow a greater range of expression within text-basedfields such as the description and comment fields. JIRA currently ships with two renderers, thedefault text renderer which preserves the functionality you have come to know and love withinJIRA, and the Atlassian wiki renderer which brings the power of the Confluence wiki engine toJIRA. Renderers can be configured on a per field, per project/issue type level, allowing a flexiblecombination of text and wiki markup. Renderers are implemented 100% as JIRA plugins,meaning that any renderer can be easily added to or removed from use within JIRA, includingany custom renderers that may be developed. On this page we'll outline some the key conceptsrelating to renderers. For details on configuration see the configuration guide.

Note:Renderers affect the rendering (view) of a fields value. This means that you can migrate to a different renderer late in a project

JIRA Documentation

Page 152Copyright © 2002-2005 Atlassian All rights reserved.

Page 153: Jira Manual

without affecting the data, only the view will be changed. It also means that if you do not like the way your issues look using the newrenderer you can simply switch back with no impact on your issue data.

4.11.1.1. Renderable Fields

Potentially any field within JIRA can be a renderable field, but this only really makes sense in thecase of text-based fields (what would a date field look like in wiki-markup). The following tableshows the fields in JIRA that are currently renderable.

Field Type Description

Description The description field of an Issue can have arenderer applied.

Comment The comments field of an Issue can have arenderer applied.

Environment The environment field of an Issue can have arenderer applied.

Custom Field - Free Text Field (unlimited text) Any instance of this type of custom field canhave a renderer applied.

Custom Field - Text Field Any instance of this type of custom field canhave a renderer applied.

4.11.1.2. Renderer Types

JIRA 3.4 currently ships with two renderers, the Atlassian wiki renderer and the default textrenderer.

Atlassian Wiki Renderer

The Atlassian wiki renderer allows a user to enter wiki markup to produce html content. Thisrenderer uses the Confluence wiki renderer engine and therefore uses the Confluence wiki notation.The Confluence notation is easy to learn and allows for all the styles you'd expect:

• Italic, bold, underline and all the other styles you'd expect,• Multiple levels of headings to organise your document,• Bullets, numbering, tables and quotations,• Images, screenshots, and emoticons,• Powerful mini-applications using macros.

A full notation guide can be found here.

Note:The Atlassian wiki renderer can only be used with JDK 1.4 and up. The renderer will not run on JDK 1.3.

The screenshot below is of a rendered description from a JIRA issue which uses some elements ofwiki markup:

JIRA Documentation

Page 153Copyright © 2002-2005 Atlassian All rights reserved.

Page 154: Jira Manual

Sample of description rendered with wiki rendererWhen editing a field setup to use the wiki renderer, it is helpful to be able to preview what therendered version of the wiki markup will look like. To this end, a preview button is included tothe right of the edit element. When in the 'edit' mode, you are presented with a normal input (atextarea or a text box depending on the field). The screen shot below shows the edit mode:

JIRA Documentation

Page 154Copyright © 2002-2005 Atlassian All rights reserved.

Page 155: Jira Manual

Sample of description edited with wiki rendererWhen the preview button is clicked the rendered content dynamically replaces the edit element. Thepreview button is now depressed. To return to the edit mode you can just click the preview buttonagain. The screenshot below shows the preview of the rendered wiki markup in the above text area:

Sample of description previewed with wiki rendererAs is evident in the above screenshots the wiki notation guide is available as a link when editing arenderable field, just click the help icon and a window containing wiki notation help will popup.

Atlassian Wiki Renderer Macro Support

The wiki renderer supports pluggable macros in the same way Confluence does. Macros provide aneasy and powerful extension point to the wiki markup language. JIRA ships with the followingmacros:

Note:JIRA and Confluence can share macros but keep in mind that many Confluence macros are very specific to the Confluence applicationand will therefore not run within JIRA. For example, the Children macro in Confluence shows links to all of a Pages child pages. JIRAhas no concept of page and therefore this macro will not function in JIRA.

Macro Description Enabled by default

Basic Anchor Macro Create an anchor that allowspeople to link to a specific pointin a page.

true

Code Macro Format blocks of source-codeor XML. The code macro inJIRA is configured to highlight

true

JIRA Documentation

Page 155Copyright © 2002-2005 Atlassian All rights reserved.

Page 156: Jira Manual

syntax for Java, Javascript,SQL, Actionscript, and XML.

Quote Macro Generate blockquotes that maycontain multiple paragraphs orcomplex markup.

true

No format Macro Create blocks of text whereother wiki formatting is notapplied.

true

Panel Macro Draw a panel with an optionaltitle and border.

true

Colour Macro Change the colour of thecontained text.

true

Lorem Ipsum Macro Insert paragraphs of "loremipsum" space-filler text.

true

Inline Html Macro Use HTML code within a JiraIssue.

false

Default Text Renderer

The default text renderer, as the name implies, is the default renderer for JIRA. Out of the boxJIRA is configured to use the text renderer for all renderable fields. The text renderer renderers afields content in the same way that JIRA has always rendered its content. If the text contains textthat resolves to a JIRA issue key then an html link will be generated that points to that issue.Below is a sample of how some description text looks when rendered through the default textrenderer.

Sample of description rendered with text renderer

Note:It is not possible to disable the default text renderer plugin as it is required for the system to function properly. If a field is setup touse a renderer that has been disabled it will fall back to this renderer.

4.11.1.3. Implications for Jira operations

The fact that JIRA allows you to configure different renderers across project/issue typeboundaries for the same field implies that we need some rules defining how bulk operations willreact to different renderer types. Also since the wiki renderer inherently creates html as its endproduct we must define how this will behave within the view layers other than the web front-endin JIRA.

Bulk Move

When performing a bulk move operation you can either move issues to an environment(project/issue type) where the renderer types for the fields are the same or where they will bedifferent. If the renderer types for where you are moving to are the same then you will not notice

JIRA Documentation

Page 156Copyright © 2002-2005 Atlassian All rights reserved.

Page 157: Jira Manual

any changes to the way the issues data is displayed once the move has occurred and the moveoperation will not prompt the user with any warnings.

When bulk moving issues to an environment (project/issue type) that has a different renderer typedefined for one of the fields being affected by the move, if any of the issues have a non empty valueassociated with the field, the move operation will present the user with a warning so that you can beaware of the change. The warning does not affect the move operation in any way but it is there toalert you to the fact that the moved issues' affected fields may look different in their newproject/issue type.

This is best illustrated with an example. Lets say you have project 'A' which is configured to use theAtlassian wiki renderer for the description field. Lets say you also have a project 'B' which isconfigured to use the default text renderer for the description field. You have three issues that existin project 'A' and you want to perform a bulk move of the three issues to project 'B'. If none of theissues in project 'A' have a value set for the description field they will be moved and you will notnotice any changes since there is no value to render. If one of the issues has the following value in itsdescription:

{color:green}green text{color}

*this is a test issue*

You would be presented with this screen in the bulk move to alert you that you are changingrenderers as a result of the move.

Example of the bulk move renderer warningThe move operation does nothing to affect the data itself so after the move the wiki markup willdisplay through the default text renderer. In our example the before and after look like this:

JIRA Documentation

Page 157Copyright © 2002-2005 Atlassian All rights reserved.

Page 158: Jira Manual

Before

After

Bulk Edit

When performing a bulk edit operation the only renderable fields you may be able to bulk editare instances of the Text Field, and Free Text Field (unlimited text) custom fields. The bulk editoperation does not allow you to bulk edit the description, environment, or comment fields.

You will only be allowed to bulk edit a renderable field if all the issues selected for edit use thesame renderer type. If the renderer type differs for any of the selected issues you will bepresented with an error message.

This is best illustrated with an example. Lets say you have two global custom fields, 'Custom textarea' and 'Custom text field', whose types are as their names imply. Lets say you have project 'A'which is configured to use the Atlassian wiki renderer for both of the above fields. Lets say youalso have a project 'B' which is configured to use the default text renderer for the 'Custom textarea' field and the Atlassian wiki renderer for the 'Custom text field'. Lets also say that you haveone issue in each project. If you were to perform a bulk edit operation on the two issues in theseprojects you will be presented with the screenshot below.

JIRA Documentation

Page 158Copyright © 2002-2005 Atlassian All rights reserved.

Page 159: Jira Manual

Sample bulk edit screenYou will notice that for the 'Custom text area' field you are presented with an warning that the fieldhas inconsistent renderer types and that it is not available to be selected for bulk edit. This is becausethe fields do not share the same renderer in the two issues. You will also notice that for the 'Customtext field' field you are presented with an editable input that allows for wiki preview. This is becausethe field shares the same renderer in the two issues.

Email Notifications

JIRA allows for extensive configuration in relation to email notifications, full documentation can befound here. JIRA can send out two types of emails, html and text.

HTML Emails

When using the Atlassian wiki renderer the rendered content (what you see on the view issue page)will be sent out in the emails. This will create emails which are as rich as the content makes it. Ifusing the wiki renderer this is the preferred type of email since it is a real representation of what istrying to be expressed by the wiki markup.

Text Emails

When using the Atlassian wiki renderer the actual wiki markup is what will be displayed in the emailnotification. This is obviously less readable than the rendered version of the markup but because themarkups simple syntax the text does remain in a very easy to read format.

Note:The unrendered wiki markup will be shown in text emails for fields that use the wiki renderer.

JIRA Documentation

Page 159Copyright © 2002-2005 Atlassian All rights reserved.

Page 160: Jira Manual

Excel View

JIRA allows the issue navigator view to be exported to an excel spreadsheet. If any of the fieldsbeing exported to excel are using the Atlassian wiki renderer, the value exported to the cell inexcel will be the original wiki markup. Attempting to display complex html within a cell in exceladds rows and columns that make using the data for formulas very difficult.

Note:The unrendered wiki markup will be shown in excel cells for fields that use the wiki renderer.

RSS/XML View

If a field is using the default text renderer its values will be exported in a CDATA section withinthe generated xml. If a field is using the Atlassian wiki renderer its rendered value will be xmlescaped and included in the generated xml. If the xml view is being used as an RSS feed, mostRSS readers will render the generated html so you will see the rich content within your RSSreader.

If you would like to have this view feed out the raw values (unrendered) then you can send anadditional request parameter 'rssMode=raw'. If the original link looks like this:

http://localhost:8080/browse/AAA-1?decorator=none&view=rss

Then the url to have the raw values placed inside a CDATA should look like this:

http://localhost:8080/browse/AAA-1?decorator=none&view=rss&rssMode=raw

Other

This section describes other issues to be aware of in relation to the renderers.

• When editing a renderable custom fields default value, even if it is only ever configured touse the Atlassian wiki renderer you will not be presented with the edit and preview tabs.Unfortunately it is not possible, in that context, to tell which renderer we should use forediting. This said, if you enter a default value using wiki markup then this will rendercorrectly in environments (project/issue type) where the field has been configured to use theAtlassian wiki renderer.

4.11.2. Configuration Renderers

Renderers in JIRA affect the view of a field's content. Fields can be configured on a project/issuetype level. For full information see the doc on issue field configuration. On this page we'll talkabout the specifics of configuring the renderers within JIRA. This consists of two elements, fieldlayout configuration, and plugin configuration.

4.11.2.1. Field Layout Configurations

This section assumes you have read and understood the main doc on issue field configuration.From the 'View Field Configuration' page you will see some information related to renderers forall renderable fields (which fields these are is defined on the overview page).

JIRA Documentation

Page 160Copyright © 2002-2005 Atlassian All rights reserved.

Page 161: Jira Manual

Field Configuration: View Field ConfigurationIn the above screenshot you will notice the grey text '[Wiki Style Renderer]' under the Descriptionfields name. This indicates that the field is currently configured to use the Atlassian wiki renderer.The grey text '[Default Text Renderer]' under the Comment fields name indicates that the field iscurrently configured to use the default text renderer.

To change the renderer type for a specific field you must click on the 'Renderers' link in theoperations column of the screen for the field you want to change. This will take you to a screenwhere you will have the option to select a renderer from all configured and available renderers (thisis managed in the plugin configuration and described in the next section).

JIRA Documentation

Page 161Copyright © 2002-2005 Atlassian All rights reserved.

Page 162: Jira Manual

Renderer configuration screenAs shown above, this screen will warn you if there are issues that will be effected by the change.If no issues will be effected then the warning does not show. From this screen you choose therenderer you wish to use and click 'Update'. You are then presented with a confirmation screen,shown below.

Renderer configuration confirmation screenClick the 'Update' button to finish setting the new renderer on the field.

Note:Keep in mind that change the renderer only effect the view of the data that exists in the system. You can therefore toggle back andforth between renderer types safely.

4.11.2.2. Plugin Configurations

Renderers within JIRA are implemented as JIRA plugins. The macros that the Atlassian wikirenderer uses are also implemented as JIRA plugins. For general information on plugins pleasesee this guide.

Note:Plugins are configured at a site-wide level, it is not possible to configure plugins at a project/issue type level.

Renderer Plugins Configuration

Renderers and their dependant components, except for the default text renderer, can be

JIRA Documentation

Page 162Copyright © 2002-2005 Atlassian All rights reserved.

Page 163: Jira Manual

enabled/disabled via the plugin administration menus. If you navigate, as an administrator, to'Administration' > 'Plugins' and then click on the option 'Renderer Plugin' you will see the followingscreen.

Renderer plugin configuration screen

Note:The plugin titled 'Wiki Style Renderer Webwork Help Action' is a front-end helper for showing the Atlassian wiki renderer notation guideand it can not be disabled.

From this screen you will see all the configured Renderers within JIRA. At the moment only tworenderers exist but if more are created you will see there configuration here. If you click on the'Disable Module' link for the 'Wiki Style Renderer' this will deactivate the renderer for the entireinstance of JIRA.

JIRA Documentation

Page 163Copyright © 2002-2005 Atlassian All rights reserved.

Page 164: Jira Manual

Renderer plugin disabledAny fields that are still setup to use the disabled renderer will fall back to the default textrenderer and when you attempt to edit the field a warning message will alert you to the fact thatyou are configured to use a renderer that is not available.

No such renderer availableWhen a renderer is disabled it will not be available for selection when changing a fields renderer.To enable the renderer just click the 'Enable Module' link. Enabling/Disabling a renderer has noeffect on the renderer settings in the field configurations so it is possible to disable and thenre-enable a renderer without effecting any data.

Macro Plugins Configuration - Atlassian Wiki Renderer

The macros used by the Atlassian wiki renderer can be enabled/disabled via the pluginadministration menus. If you navigate, as an administrator, to 'Administration' > 'Plugins' andthen click on the option 'Wiki Renderer Macros Plugin' you will see the following screen.

JIRA Documentation

Page 164Copyright © 2002-2005 Atlassian All rights reserved.

Page 165: Jira Manual

Atlassian wiki renderer macros plugin configuration screenFrom this screen you will see all the configured macros within JIRA. If a macro is disabled then itwill not be available to the wiki renderer, likewise a macro must be enabled for it to be available tothe wiki renderer. If you deploy any additional macros that you wish to use, they must be enabledhere to be available to the wiki renderer. For more information of writing plugins please see thisguide.

4.12. Issue Level Security

4.12.1. What is Issue Level Security

Issue Level Security is a way of controlling who can and cannot see individual issues.

This works on an issue by issue basis and will override any permissions that may be set up for theproject that the issue is in.

4.12.1.1. Why would I want to use Issue Level Security

Issue Level Security should be used if you want to control the people who can see a certain issue.

Example

A Company may have a public instance of JIRA running. Within this instance they may have several

JIRA Documentation

Page 165Copyright © 2002-2005 Atlassian All rights reserved.

Page 166: Jira Manual

projects that external people (customers) can browse. However the company may not want toshow all issues to the customers. There may be internal issues which the customer really shouldnot know about. To enable this you could do the following:

• Set up an Issue Security Scheme• Create a new Security Level named 'Private' for this scheme• Add the specific groups and users that you want to be assigned to this security level.• Associate the relevant project to the Issue Security Scheme• Set the Security Level of specific issues to 'Private'

This will ensure that only users that are assigned to the Security Level 'Private' in that IssueSecurity Scheme will be able to see any of these issues.

This is a simple example and we recommend you read the following sections before configuringor using Issue Level Security.

Note:Please note that this feature is only available in the Enterprise edition of JIRA.

4.12.2. Security Schemes

Issue Security Schemes allow you to control who can and cannot view issues. A project can beassigned an Issue Security Scheme meaning that all issues within that project can have a level ofsecurity set on them restricting the people who can access the issue.

Issue Security Schemes consist of a number of user defined Security Levels

4.12.2.1. Creating an Issue Security Scheme

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Schemes", click on the link labelled "Issue SecuritySchemes".

JIRA Documentation

Page 166Copyright © 2002-2005 Atlassian All rights reserved.

Page 167: Jira Manual

View Issue Security Schemes

4. This will display the "Issue Security Schemes" page. This page lists all of the Issue SecuritySchemes that JIRA currently has. Click on the "Add Issue Security Scheme" link.

View Issue Security Schemes

5. In the "Add Issue Security Scheme" form, enter a name for the issue security scheme, and a shortdescription of the scheme. Click on the "Add" button.

Add an Issue Security Scheme

6. You will return to the "Issue Security Schemes" page which now contains the newly addedscheme.

JIRA Documentation

Page 167Copyright © 2002-2005 Atlassian All rights reserved.

Page 168: Jira Manual

View Issue Security Schemes

4.12.2.2. Assigning an Issue Security Scheme to a Project

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. A list of projects is displayed

List of Projects

4. Select the project you want by clicking on the project name. This will display the projectdetails

5. Click on the "select scheme" link beside the Issue Security Scheme caption.

JIRA Documentation

Page 168Copyright © 2002-2005 Atlassian All rights reserved.

Page 169: Jira Manual

Project Details

6. This will bring up a list of Issue Security Schemes. Select the Issue Security Scheme that youwant to associate with this project.

Select Scheme

7. If there are no previous secured issues skip the next step.8. If there are any previously secured issues select a new security level for each old level. All issues

with the security level from the old scheme will now have the security level from the newscheme. You can choose 'None' if you want the security to be removed

Select New Level

9. Click the "Associate" button to associate the project with the issue security scheme.

4.12.2.3. Deleting an Issue Security Scheme

JIRA Documentation

Page 169Copyright © 2002-2005 Atlassian All rights reserved.

Page 170: Jira Manual

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Schemes", click on the link labelled "Issue SecuritySchemes".

View Issue Security Schemes

4. This will display the "Issue Security Schemes" page. This page lists all of the Issue SecuritySchemes that JIRA currently has. Click on the "Del" link for the scheme that you want todelete.

Delete Issue Security Schemes

5. A confirmation screen will appear. To delete click "Delete" otherwise click "Cancel".

JIRA Documentation

Page 170Copyright © 2002-2005 Atlassian All rights reserved.

Page 171: Jira Manual

Delete Issue Security Scheme

6. The scheme will be deleted and all associated projects will be associated to the default issuesecurity scheme.

**Note that you cannot delete the default issue security scheme.

4.12.2.4. Copying an Issue Security Scheme

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Schemes", click on the link labelled "Issue SecuritySchemes".

View Issue Security Schemes

4. This will display the "Issue Security Schemes" page. This page lists all of the Issue SecuritySchemes that JIRA currently has. Click on the "Copy" link for the scheme that you want to copy.

JIRA Documentation

Page 171Copyright © 2002-2005 Atlassian All rights reserved.

Page 172: Jira Manual

Copy Issue Security Schemes

5. A new scheme will be created with the same security levels and the same users/groupsassigned to them.

Copy Issue Security Schemes

4.12.3. Security Levels

A Security Level is simply a named grouping of certain users. Each Security Level can have acombination of users/groups assigned to them.

Assigning a user/group to a security level will enable that user/group to view any issues that havetheir security level set to that level.

The types of users/groups that can be assigned to a security level are as follows

Current Reporter: The current reporter of the issue will haveaccess to any issues with this security level

Group: Any user within this group will have access toany issues with this security level

Single User: The specified user will have access to anyissues with this security level

JIRA Documentation

Page 172Copyright © 2002-2005 Atlassian All rights reserved.

Page 173: Jira Manual

Project Lead: The project lead of the issue's project will haveaccess to any issues with this security level

Current Assignee: The current assignee of the issue will haveaccess to any issues with this security level

User Custom Field: Any user specified in the selected SingleUser/Multi User Custom Field will have accessto any issues with this security level

4.12.3.1. Creating a Security Level

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Schemes", click on the link labelled "Issue SecuritySchemes".

View Issue Security Schemes

4. This will display the "Issue Security Schemes" page. This page lists all of the Issue SecuritySchemes that JIRA currently has.

5. Click on the name of any scheme or the link "Security Levels" to bring up the "Edit IssueSecurity Levels" page.

JIRA Documentation

Page 173Copyright © 2002-2005 Atlassian All rights reserved.

Page 174: Jira Manual

View Issue Security Levels

6. This displays a list of the Security Levels within the scheme. Goto the "Add Security Level"and enter a name and description for the level. Click on the button "Add Security Level"

Add Issue Security Levels

7. The new level will now be added

4.12.3.2. Adding Users/Groups to a Security Level

1. Click the "Add" link in the Operations column of the Security Levels table.

JIRA Documentation

Page 174Copyright © 2002-2005 Atlassian All rights reserved.

Page 175: Jira Manual

Add Users to Issue Security Levels

2. This will display the "Add Issue Security" page. After selecting the appropriate option, andfilling in any required information for that option, click the "Add" button. The users/groups willnow be added to that security level

Add Users to Issue Security Levels

3. Repeat steps 1 and 2 until all required users/groups have been added to this level

JIRA Documentation

Page 175Copyright © 2002-2005 Atlassian All rights reserved.

Page 176: Jira Manual

4.12.3.3. Setting Default Security Level for an Issue Security Scheme

A security level can be set to be the default security level for the Issue Security Scheme.

If the reporter of an issue does not have the permission 'Set Issue Security' then the security levelfor the issue will be defaulted to the default Level

If the default Level for the Scheme is set to 'None' and the reporter does not have the permissionthen the security level on an issue will not be set so that anybody can see the issue.

4.12.4. Setting the Security on an Issue

Setting the security level on an issue restricts the access of that issue to only people who are amember of that security level. If you are not a member of that security level then you cannotaccess that issue and it will not appear in any filters, queries or statistics.

The security level of an issue can be set either when the issue is being created or afterwards whenthe issue is being edited.

4.12.4.1. Permissions

To be able to set the Issue Level Security for an issue the user must have the 'Set Issue Security'permission. This is set up by the administrator for the current project as explained in thePermissions section.

4.12.4.2. Creating an Issue

A person can only set the security on an issue to a level that they are a member of. This preventsthe issue from being set to a level that nobody is a member of and effectively becoming "lost"

If the person creating/editing the issue has the permission 'Set Issue Security' then they will bepresented with a drop down of all the security levels that they are a member of. Selecting one ofthese levels sets the security of the issue to this level. The issue will then only be accessible tomembers of that security level

JIRA Documentation

Page 176Copyright © 2002-2005 Atlassian All rights reserved.

Page 177: Jira Manual

Set the Security of an Issue

N.B. If the user does not have the 'Set Issue Security' permission then the default Issue LevelSecurity will be used. This may mean that the issue created is not visible to the person that created it(Issue Level Security should be configured so this does not happen).

4.13. Management

4.13.1. Project Management

To manage projects in JIRA:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Select an existing project, or click on Add Project to add a project.

JIRA Documentation

Page 177Copyright © 2002-2005 Atlassian All rights reserved.

Page 178: Jira Manual

Here is what a project looks like once created:

Project admin pageExplanation of the parts is as follows:

• Key - a 'key' unique to this project (eg. 'WEB'), which specifies the first few letters of thisproject's issue keys (eg. 'WEB-100').

• URL - An optional URL associated with this project, eg. pointing to project documentation.• Project Lead - user fulfilling the role of 'lead developer'. Used as the default assignee, and

potentially elsewhere in JIRA.• Default Assignee - Whom to assign issues to by default. If Allow unassigned issues is on in

the general configuration, this can be changed to 'Unassigned'. In JIRA Enterprise there arealso default component assignees.

• Notification Scheme - the notification scheme determining who gets email notifications ofchanges.

• Permission Scheme - the permission scheme determining who has permissions to view orchange issues in this project.

• Issue Security Scheme (Enterprise only) - which security scheme applies to this project -determining what visibility levels issues can have (see issue-level security).

• Field Configuration Scheme - the Field Configuration Scheme, which determines overallfield visibility, required'ness, formatting (Wiki or plain) and existence on various screens (seefield configuration).

• Issue Type Screen Scheme - the issue type screen scheme in effect, which determines whichscreens to display for different operations (view, edit, create), for different issue types.

• Workflow Scheme - the scheme determining which workflows (issue state transitions) applyto issue types in this project.

• CVS Modules - configures CVS integration for this project.• Issue Type Scheme - a scheme that determines which issue types apply to this project.• Project Category - a category to group this project into.

As well as:

• Components - logical groups that this project's issues can belong to. See the component

JIRA Documentation

Page 178Copyright © 2002-2005 Atlassian All rights reserved.

Page 179: Jira Manual

management page for details.• Versions - versions defined in the project. See the version management page for details.

4.13.2. Version Management

Versions are points in time for a project. They are used in a number of places, eg the Roadmap andthe Changelog. Changelog and Roadmap are driven by the Fix For setting on each issue. Versionscan be:

• Added - make new versions against which issues can be aligned.• Released - marks a version as released. This changes the Roadmap, Changelog and some drop

downs.• Rescheduled - re-arrange the order of versions.• Archived - hide an old version from Roadmap, Changelog, and in the JIRA User Interface.• Merged - take multiple versions and make them one.

4.13.2.1. Project Version Management Area

All version management operations are available from the version management interface. Thus to doall of the above, we first get to the Project Admin page, and then access the management interfacethrough the 'Manage' versions link.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the administration interface is a list of projects which this user is allowed to manage. Selectthe project of interest.

4. You will now see a page displaying the project details. On this page all the configurable actionsavailable on the project are easily accessible. On the lower right, a summary of the versions isdisplayed along with the link to the version management interface. The summary indicates theversion status and the scheduled release date for that version.

JIRA Documentation

Page 179Copyright © 2002-2005 Atlassian All rights reserved.

Page 180: Jira Manual

Project configuration, with Version list highlighted

Note:If you have created a new project and have not assigned a permission scheme with it on creation, then you will not see the abovedisplay. Instead under versions it will say "There are no versions at the moment".

4.13.2.2. Version Management Legend

The version management interface uses a simple legend to denote version status:

• Released - a bundled package• Unreleased - an open package• Archived - a semi-transparent package• Overdue - the release date is highlighted

4.13.2.3. Adding a new Version

1. The "Add" new version form is located at the bottom of the version management interface.2. From here, you enter the name for the version. The name is treated as a plain String by JIRA,

so it can be simple numeric, e.g. "2.1", it can be complicated numeric, e.g. "2.1.3", or it canbe something zany like the projects internal handle, e.g. "Memphis".

3. Optional details such as the version description and release date can be also be specified.4. It is also possible to 'schedule' the new version by selecting its position in the version list. The

new version is added after the selected version - or it can be placed at the start of the list byselecting 'First'.

5. Click on the "Add" button. The version management list is updated immediately, with thenewly created version added in the specified position.

JIRA Documentation

Page 180Copyright © 2002-2005 Atlassian All rights reserved.

Page 181: Jira Manual

Version Management

Note:At present, the version release date is only used to indicate the scheduled release date for a version. JIRA does not use the release dateotherwise - but it is intended to add further functionality to take advantage of this data in future releases.

4.13.2.4. Version Operations

The version operations are available from the operations column within the version list table. Eachoperation affects the corresponding version in that row of the table.

4.13.2.5. Release a Version

1. In the version management interface, click on the 'Release' link available in the operationscolumn for a specific version.

2. If there are any issues set with this version as the 'Fix For' version, JIRA allows you to select ifyou wish to change the 'Fix For' version. Otherwise, the operation will complete withoutmodifying these issues.

3. This operation immediately updates the specific version as 'released' throughout JIRA.4. The version list indicates the version 'released' status with the bundled package icon. The

'Unrelease' operation replaces the 'Release' operation in the operations column.5. To un-release a version, simply click on the 'Unrelease' link in the operations column.

4.13.2.6. Archive a Version

1. In the version management interface, click on the 'Archive' link available in the operationscolumn for a specific version.

2. This operation immediately updates the specific version as 'archived' throughout JIRA.3. The version list indicates the version 'archived' status with a semi-transparent icon. The list of

available operations is replaced with the 'Unarchive' operation. No further changes can be madeto this version unless it is un-archived. Also it is not possible to remove any existing archivedversions from an issue's affected and fix version fields or add any new archived versions.

JIRA Documentation

Page 181Copyright © 2002-2005 Atlassian All rights reserved.

Page 182: Jira Manual

4. To un-archive a version, simply click on the 'Unarchive' link in the operations column.

4.13.2.7. Merge Multiple Versions

1. In the version management interface, click on the 'Merge' link available in the operationscolumn for a specific version.

2. This will take you to the 'Merge Versions' page.

On this page are two select lists - both listing all un-archived versions. The specified versionis highlighted in the 'Merging From Versions' select list on the left. It is possible to selectfurther versions you wish to merge from. Versions selected on this list will be removed fromthe system. All issues associated with these versions will be updated to reflect the newversion selected in the 'Merge To Version' select list on the right. It is only possible to selectone version to merge to.

Merging Multiple Versions3. Click on the 'Merge' button. You will be shown a confirmation Page. Click on 'Merge' to

complete the operation.4. On completion of the merge operation, you are returned to the version management interface.

The version list has been updated to reflect the changes that occurred in the merge operation.

4.13.2.8. Edit Version Details

1. In the version management interface, click on the 'Edit Details' link available in theoperations column for a specific version.

2. This will bring you to "Edit Version: <Version>" page. Here, it is possible to edit the versionname, description and release date.

3. Press the 'Update' button.4. On completion of the update operation, you are returned to the version management screen -

with an updated version list reflecting the changes made.

Editing Version Details

4.13.2.9. Delete a version

1. In the version management interface, click on the 'Delete' link available in the operationscolumn.

2. This will bring you to "Delete Version: <Version>" confirmation page.3. From here, you can specify the actions to be taken for issues associated with the version to be

JIRA Documentation

Page 182Copyright © 2002-2005 Atlassian All rights reserved.

Page 183: Jira Manual

deleted. It is possible to associate these issues with another version or to simply removereferences to the version to be deleted.

4. Press the "Delete" button.5. On completion of the deletion, you are returned to the version management screen - with an

updated version list reflecting the changes made.

Deleting a Version

4.13.2.10. Reschedule a Version

1. In the version management interface, re-scheduling operations are available through the'Schedule' column.

2. It is possible to move a version up/down a position or to the start/end of the list by clicking onthe specific arrow icon associated with the specific version row.

3. The version list is updated immediately with the selected version now occupying the specifiedposition.

Scheduling Versions

4.13.3. Component Management

Components are sub-sections of a project. They are used to group issues within a project into smallerparts. The available operations for components are:

• Add - make new components under which issues can be classed.• Delete - remove a component from a project.• Edit - Update/change the component details from a project.• Select Default Assignee - For enterprise edition you can set the default assignee for a particular

component on issue creation.

JIRA Documentation

Page 183Copyright © 2002-2005 Atlassian All rights reserved.

Page 184: Jira Manual

4.13.3.1. Project Component Management Area

All component management operations are available from the Component Section of the ProjectAdmin Page.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the administration interface is a list of projects which this user is allowed to manage.Select the project of interest.

4. You will now see a page displaying the project details. On this page all the configurableactions available on the project are easily accessible. On the lower left, a summary of thecomponents is displayed along with links to add and remove components.

Project configuration, with Component Summary highlighted

Note:

JIRA Documentation

Page 184Copyright © 2002-2005 Atlassian All rights reserved.

Page 185: Jira Manual

If you have created a new project and have not assigned a permission scheme with it on creation, then you will not see the above display.Instead under components it will say "There are no components at the moment".

4.13.3.2. Adding a New Component

1. Click on the 'Add' new component link located at the top of the Component Summary Pane. Youwill now de redirected to the 'Add a Component' screen.

2. From this screen, you enter the name of the component.

3. You can also optionally enter the component description or assign a user to be the componentlead.

4. Click on the "Add" button. The component summary list is updated immediately and you will beredirected to the project admin page.

Add Component

4.13.3.3. Selecting a Default Assignee

For the enterprise version it is possible to extend the default assignee of an issue to be componentspecific instead of project specific.

1. Click on the 'Select' assignees for components link located at the top of the Component SummaryPane. A 'Select Component Assignee' pane will appear on the Project Admin Page.

2. Select an option for each component, to whom you want to have the issue assigned in thatcomponent.

3. Click on the 'Update' Button. Now assignees will automatically be set to issues created with thiscomponent.

JIRA Documentation

Page 185Copyright © 2002-2005 Atlassian All rights reserved.

Page 186: Jira Manual

Select Default Assignees

Note:In the event that the default assignees of components clash, the assignee will be set to the default assignee of the component that isfirst alphabetically.

4.13.3.4. Default Assignee Options

Option Description

Project Default Issues matching this component will have theassignee set to the same default assignee as the parentproject.

Project Lead The assignee will be set to the project leader.

Condition: If the project leader is not permitted to beassigned to issues in the permission scheme thisoption will be disabled and will say "Project Lead isnot allowed to be assigned issues.".

Component Lead The assignee will be set to the component leader.

Condition:

If the project leader is not permitted to be assigned toissues in the permission scheme this option will bedisabled and will say "Component Lead is notallowed to be assigned issues".

The Component Lead option will also not beavailable if the component does not have a leadassigned to the component. Instead under this optionit will say "Component does not have a lead.".

Unassigned The assignee of the issue will not be set on thecreation of this issue.

Condition: The unassigned option will only beavailable if the unassigned is enabled in the GeneralConfiguration. Instead under this option it will say"Unassigned issues are disabled.".

4.13.3.5. Editing an Existing Component

JIRA Documentation

Page 186Copyright © 2002-2005 Atlassian All rights reserved.

Page 187: Jira Manual

1. In the Component Summary Pane, click on the 'Edit' link available on the right of a specificcomponent.

2. This will bring you to "Edit Component" page. Here, it is possible to edit the version name,description and lead.

3. Press the 'Update' button.

4. On completion of the update operation, you are returned to the project admin page - with anupdated component list reflecting the changes made.

Edit Component

4.13.3.6. Deleting an Existing Component

1. In the Component Summary Pane, click on the 'Delete' link available on the right of a specificcomponent.

2. This will bring you to "Delete Component" page.

3. On this page you can specify the action to be taken on the affected issues. You can eitherassociate these issues to another active component or have the references removed.

4. Press the 'Delete' button.

5. On completion of the delete operation, you are returned to the project admin page - with anupdated component list reflecting the changes made.

Delete Component

4.13.4. Creating project-specific Administrators

A Project Specific admin has the ability to make the following changes to a project:

• Change the full name of the project.

JIRA Documentation

Page 187Copyright © 2002-2005 Atlassian All rights reserved.

Page 188: Jira Manual

• Change the documentation URL.• Change the lead developer.• Change the project description.

There are a lot of settings that affect projects which have global impact, which are thus onlyavailable to users in the group with global Project Administrators permission, which is by defaultjira-administrators.

4.13.4.1. Step 1: Create a new users group - <project>-admins.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Click on the "Group Browser" link on the left, in the "Users & Groups" menu.4. In the Add Group box on the far right of the page, enter the name of the new group. For ease

of understanding, <project>-admins is suggested, where <project> is the name of yourproject. Click on the "Add Group" button.

5. You should get the same page back, with your new group listed in the table in the center ofthe page. Using this table you can view the list of users, or delete the group.

4.13.4.2. Step 2: Add Users to <project>-admins group.

1. Click on User Browser in the sidebar menu. Because we previously created the group<project>-admins, the User Browser will automatically attempt to list users in this group. Aswe have only just created this group, the list should be 0 entries long. So don't panic that allyour users just disappeared...

2. In the form at the top of the page, change the In Group drop-down from <project>-admins toAny, and click on Filter. This will list all users.

Group filters3.

JIRA Documentation

Page 188Copyright © 2002-2005 Atlassian All rights reserved.

Page 189: Jira Manual

Select the user of interest. This will bring up the User's summary information.

Editing a user's configuration4. Click on "Edit Groups". This will bring up a page that has two scroll boxes. The scroll box on

the left contains a list of groups that the user is not in, and the one on the right that the user is in.

Adding a user to a group5. Click on <project>-admins in the left scroll box, and click on the button labelled "Join>>".6. You should be presented with the same page, but with <project>-admins in the right hand scroll

box. This means that the user is now a member of the <project>-admins group.

4.13.4.3. Step 3: Grant the group Project Administration Permissions on the Project.

1. Navigate to the project. This is done by clicking on the View Projects link, while in theAdministration tab.

JIRA Documentation

Page 189Copyright © 2002-2005 Atlassian All rights reserved.

Page 190: Jira Manual

View Project link2. Select the relevant project and then select "edit permissions".

edit permissions3. Check which permission scheme is in use for this project.

Text indicating the project's permission schemeIf the "Default Permission Scheme" is being used, this scheme is probably being shared withother projects. You will probably want to create a Permission Scheme dedicated to thisproject. Follow the instructions in the Permission Schemes section on how to do this.

4. In the Project Administrators permission, click the "Add" link and add the<project>-admins group.

Assigning the <project>-admins group the Project Administrators permission5. You should now see your project group assigned to the "Project Administrators" permission.

JIRA Documentation

Page 190Copyright © 2002-2005 Atlassian All rights reserved.

Page 191: Jira Manual

Showing project group assigned the relevant permission

In summary, you have now:

• Created a new group, containing users you wish to be able to administer the project• If the project did not already have a dedicated Permission Scheme, one was created for it.• Assigned the new group the "Project Administrators" permission.

When a member of <project>-admins logs in, their Administration tab will list only the project theyhave permission to administrate.

What a member of <project>-admins would see when logging in

4.13.5. Configuring Project Keys

JIRA provides the ability to configure the format of project keys within the system. This is achievedby defining a regular expression 'rule' that governs the valid project key format.

4.13.5.1. Project Key Pattern

Through the property jira.projectkey.pattern, the administrator can specify a Perl5regular expression defining the rule for a valid project key. This property can be found in thejira-application.properties file. During project creation, the user must specify a projectkey that conforms to this rule.

JIRA prepends the regular expression specified with '^' and closes it with '$' for an exact matchingrule within the system. The project key must only be allowed to contain ASCII characters, as it isused in HTTP GET requests.

4.13.5.2. Editing the key pattern

This can be done by editing jira-application.properties. You will then need to restart JIRA (JIRAStandalone) or rebuild the JIRA webapp and redeploy in your app server.

4.13.5.3. Project Key Details

The jira-application.properties file also contains the following properties:

• jira.projectkey.description - a configurable description (to match the project keypattern) displayed on project creation

• jira.projectkey.warning - a configurable validation warning (to match the project keypattern)

Note:It is not possible to configure the issue key as JIRA expects this key to conform to specific rules.

Note:Further information on Perl5 is available here.

JIRA Documentation

Page 191Copyright © 2002-2005 Atlassian All rights reserved.

Page 192: Jira Manual

4.14. Email

4.14.1. Notification Schemes

JIRA can generate email notifications for various events that happen during the issue life cycle.The life cycle events are as follows:

Issue Created: An issue has been entered into the system.

Issue Assigned: An issue has been assigned to a new user.

Issue Updated: An issue has had it's details changed.

Issue Commented: An issue's comment log has been added to.

Issue Worklogged: An issue has had hours logged against it.

Issue Resolved: An issue has been resolved, usually after beingworked on and fixed.

Issue Closed: An issue has been closed. This is done usuallyto signify that the issue is dead.

Issue Reopened: An issues has been re-opened, as a previouslyclosed issue has re-appeared.

Issue Moved: An issue was moved into this project.

Issue Deleted: An issue has been deleted.

Generic Event: This can be used by custom workflows to throwtheir own "custom" event. Unfortunately, trulycustomised events cannot be thrown. Thusgeneric event is essentially equivalent to"non-standard" events.

A notification scheme is a saved configuration listing who should be notified for each of theabove events. A notification scheme may apply to one or more projects.

4.14.1.1. Creating a Notification Scheme

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Schemes", click on the link labelled "Notification

JIRA Documentation

Page 192Copyright © 2002-2005 Atlassian All rights reserved.

Page 193: Jira Manual

Schemes".4. This will display the "Notification Schemes" page. This page lists all of the notification schemes

that JIRA currently has. Click on the "Add Notification Scheme" link.5. In the "Add Notification Scheme" form, enter a name for the notification scheme, and a short

description of the scheme. Click on the "Add" button.6. You are then shown the "Edit Notifications" page. This page lists all of the above mentioned

issue life cycle events, along with whom should be notified. It is currently empty.7. Click on the "Add" link in the appropriate life cycle event row.

Editing a new notification scheme8. This will display the "Add New Notification" page. Here you can choose who to notify, from the

list of alternatives.

JIRA Documentation

Page 193Copyright © 2002-2005 Atlassian All rights reserved.

Page 194: Jira Manual

Adding a notification to a scheme

Where:

• Current Assignee is the user assigned to the issue.• Current Reporter is the user who originally created the issue• Current User is the user who performed the action triggering the event in question.• Single Email Address is any email address that you wish to alert.

Note:A Single Email Address notification will only be sent if the issue is publically viewable since you can not perform a security checkon only any email address. Publically viewable issues are issues which have a Permission scheme that gives the 'Browse Projects'permission to 'Anyone'(any non-logged-in users).

• User Custom Field Value is any custom field value of type User Picker or Multi UserPicker that may have been associated with issues. An example of where this can beuseful, you have a custom User field called Tester, you have the tester notified when anissue is resolved.

• (the rest are hopefully self-evident)

9. After selecting the appropriate option, and filling in any required information for that option,click the "Add" button.

10.You will be taken back to the "Edit Notifications" page, with the notification you justspecified now listed against the appropriate issue life cycle event.

11.Repeat steps 7 through 11 until you have specified all the notifications you want to happen.12. If you make a mistake, or you would like to remove person or a group from being notified,

simply do so by clicking on the "del" link beside the person/group.

4.14.2. Customising email content

JIRA generates emails in reaction to events using a templating engine. The templating engine isApache Jakarta's Velocity. This is a relatively easy to use templating language that can pull apartjava objects in useful ways. The mails are generated inside JIRA by invoking Velocity with a setof objects of relevance to the event.

JIRA Documentation

Page 194Copyright © 2002-2005 Atlassian All rights reserved.

Page 195: Jira Manual

To customise email content, please follow this procedure.

1. Open up your JIRA distribution, and navigate to the following paths:• Standalone: atlassian-jira-2.0\atlassian-jira\WEB-INF\classes\templates\email\• Source: jira\src\etc\java\templates\email\• WAR: webapp\WEB-INF\classes\templates\email\

2. Under this directory there are two directories, html and text. The html subdirectory contains thetemplates used to create emails in html, while the text directory the plain text mail outs. Thetemplates are named after the event that will trigger the email.

3. Bring the template up in your favourite text editor. Referring to the Velocity Users Guide, makethe customisations you want.

4.14.3. Issue/Comment Creation from Email

JIRA can be configured to automatically create issues or comments based on incoming emails. Thisis especially useful in a helpdesk or support scenario, where users send support queries via email,which you wish to track with JIRA. Subsequent emails about the issue, for example responses toEmail Notifications, can be automatically recorded as comments.

To set up issue and comment creation via email, you will need to create a mail account on yourserver (usually for each project). For example, for the 'ABC' project, you might establish an [email protected]. This mail box should be accessible via POP, IMAP, or onthe local filesystem. JIRA will periodically scan this mail box, and appropriately create issues orcomments for any emails it finds, and (optionally) new user accounts for senders not previouslyseen.

Once you have established a mail account, here is how to configure JIRA to periodically scan it(POP access assumed):

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Global Settings", click on the link labelled "MailServers".

4. Click on the "Configure new POP mail server" link.5. This will bring up the "Add POP Mail Server" page.

JIRA Documentation

Page 195Copyright © 2002-2005 Atlassian All rights reserved.

Page 196: Jira Manual

Add pop server

Fill in as follows:

• Name: put a short descriptive name, possibly just the email address that will be collectedby this service

• Description: put a short phrase that describes this service, probably 'Email IssueCreation/Comments for <Project>'.

• Hostname: put the name of your POP server• Username and Password use the email account details as created in step 1.

6. This should bring you back to the Email Servers page, where you should see a new POPserver listed. You can edit and delete this server here.

7. On the panel on the left, under the title "System", click on the link labelled "Services".8. This will bring up the "Services" page. It lists the current services running on this system. On

a vanilla system there should be one service running - Mail Queue Service. You cannotdelete the Mail Queue Service. Additionally, if you have enabled the option to automaticallybackup JIRA's data, you will also see the Backup Service listed here too.

9. Fill in the "Add Service" form as follows:

JIRA Documentation

Page 196Copyright © 2002-2005 Atlassian All rights reserved.

Page 197: Jira Manual

Add serviceFor Name enter a descriptive name, eg "Create Issue/Comment Service for <Project>". ForClass, select the appropriate option presented in the drop down list, or entercom.atlassian.jira.service.services.pop.PopService, and the Delay is best left as 1 minute.Click Add Service.

10.This will bring up the "Edit Service" screen to configure the service.

Editing a serviceFor Handler, select "Create Or Comment Handler" from the drop down box. Set Handlerparameters to something like:project=JRA, issuetype=1, [email protected] details on the handler parameters are available here.

JIRA Documentation

Page 197Copyright © 2002-2005 Atlassian All rights reserved.

Page 198: Jira Manual

The Forward Email parameter specifies an email address to which error notifications can beforwarded. Any failures encountered in this process are logged and forwarded in an email tothis address.

It is also possible to specify whether SSL is used or not.

Click the "update" button and the service will be in effect.

4.14.3.1. Issue/Comment Creation

JIRA examines the email subject and the in-reply-to message for an existing issue reference todetermine whether a new issue or comment should be created. A new issue is created if anexisting issue reference is not found - otherwise, a comment is added to the issue referenced inthe email. The email to [email protected] will be processed as follows:

• Issue Creation:• The subject of the email will become the issue summary• The body of the email will be the issue description• A bug (since issue type has been set to 1 in this example) will now be created for project

"JRA" with the above information• Comment Creation:

• The body of the email will become a comment on the issue

Note:The Subject of the email becomes the issue summary. As all issues require a summary, each email intended for issue creation shouldinclude a Subject.

4.14.3.2. Handler Parameters

project parameter is the project key.

These are the numbers associated with the default issue types:

• Bug: issuetype=1• New Feature: issuetype=2• Task: issuetype=3• Improvement: issuetype=4• Sub-task: issuetype=5The catchemail handler parameter is, if present, used to filter the email sent [email protected]. In this example, only email sent to (or Cc'ed or Bcc'ed to)[email protected] will be processed by the system.

You can only specify one catch email address and one issue type.

Additionally, you may add a reporterusername, createusers and ccassignee handlerparameters:

reporterusernameAt the moment, JIRA will reject any emails sent to [email protected] frompersons who do not exist as valid users in JIRA. To allow anonymous users to createissues via email, you can create an anonymous user or dummy account on JIRA andset the reporterusername to point to this account. When the "reporterusername"option is specified, the "from" address of the email is added at the end of thecomment of the issue.createusersIf createusers is set to true, people who don't currently have an account in JIRA willhave it created for them. In JIRA Enterprise, this allows the creator to be notified of

JIRA Documentation

Page 198Copyright © 2002-2005 Atlassian All rights reserved.

Page 199: Jira Manual

subsequent updates to the issue, by configuring the notification scheme to notify the'Reporter' of updates.notifyusersThis parameter is only used if createusers is set to true. If notifyusers is set to falsethey will not receive a notification that their account has been created via email. Thedefault value is true to preserve the behaviour before this parameter was added.ccassigneeIf an email has a Cc address listing a user already present in JIRA, by default JIRA willassign the issue to that user. In JIRA 3.1 and above, if you do not want this behaviour,set ccassignee to false.

E.g. Create a user called "anonymous" and set reporterusername=anonymous.

4.14.4. Configuring JIRA to send mail (SMTP configuration)

This page describes various ways of configuring JIRA to send email via SMTP.

A SMTP mail server connection can be configured in the JIRA Administration section under GlobalSettings -> Mail Servers. Clicking "Configure new SMTP mail server" will bring you to thefollowing form:

JIRA Documentation

Page 199Copyright © 2002-2005 Atlassian All rights reserved.

Page 200: Jira Manual

Adding an SMTP mail server in JIRA

4.14.4.1. Configuring SMTP inside JIRA

The first part of the form has the following fields:

Name An arbitrary name to associate with this serverconfiguration

Description Optional mail server description

From address The email address that outgoing mails willappear to have come from (unless overriddenper project in JIRA Enterprise).

Note that this is just the address part("[email protected]"). JIRA will use it inconstructing the full From header based on thecurrent user ("Joe Bloggs (JIRA)

JIRA Documentation

Page 200Copyright © 2002-2005 Atlassian All rights reserved.

Page 201: Jira Manual

<[email protected]>"). The full From headerformat can be adjusted injira-application.properties with thejira.email.fromheader.format property.

Email prefix The subject of emails sent from this server willuse this string as a prefix.

The second part of the form specifies details of your SMTP server. There are two options: configureSMTP in JIRA, or look up server preconfigured in your application server via JNDI (see below).

Configuring SMTP details in JIRA

Most people configure SMTP details directly in JIRA. The form fields are as follows:

Host Name Hostname of your SMTP server. Eg.mail.yourcompany.com

SMTP Port The SMTP port, usually 25

Username Username to connect as, if authentication isrequired. Most company servers requireauthentication to relay mail to non-local users.

Password Password for username

Once done, click 'Update' and then "Send a Test Email" to test the connection details.

Looking up a mail server via JNDI

As an alternative to specifying mail details directly in JIRA, you can configure them in yourapplication server, and then look up a preconfigured mail session.

This has the following advantages:

• Centralized management - mail details are configured in the same place as database details,and may be configured through (familiar) app server admin tools.

• Better security - the mail details are not available to JIRA admins through the web interface,and aren't stored in JIRA backup files.

• More SMTP options - if you want to use SMTP over SSL you will need to do it this way (seebelow).

The JNDI Location will depend on your application server, and location in the JNDI tree youspecify. For example, in Tomcat 5.5 (JIRA Standalone), you would add this section inconf/server.xml, inside the <Context> node:

<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">....

<Resource name="mail/JiraMailServer"auth="Container"type="javax.mail.Session"mail.smtp.host="mail.yourcompany.com"mail.smtp.port="25"mail.transport.protocol="smtp"mail.smtp.auth="true"mail.smtp.user="jirauser"password="mypassword"/></Context>

Or if you don't require authentication (sending via localhost or only to company employees):

JIRA Documentation

Page 201Copyright © 2002-2005 Atlassian All rights reserved.

Page 202: Jira Manual

<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">....

<Resource name="mail/JiraMailServer"auth="Container"type="javax.mail.Session"mail.smtp.host="localhost"mail.smtp.port="25"mail.transport.protocol="smtp"/></Context>

Then your JNDI Location would be java:comp/env/mail/JiraMailServer. The format for otherapp servers can be inferred from this section.

If you have problems connecting, add a mail.debug="true" parameter, which will let you seeSMTP-level details when testing the connection.

You will also need to ensure that the JavaMail classes are present in your application server'sclasspath, and do not conflict with JIRA's copy. Most J2EE application servers (eg. JBoss,Orion, Weblogic, Websphere) come with JavaMail, and this may conflict with JIRA's copy,resulting in errors like:java.lang.NoClassDefFoundError: javax/mail/Authenticator

or:java.lang.IllegalArgumentException: Mail server at location [java:comp/env/mail/JiraMailServer] is not

of required type javax.mail.Session.

To fix this, remove WEB-INF/lib/javamail-1.3.2.jar andWEB-INF/lib/activation-1.0.2.jar from the JIRA webapp.

Lighter app servers (Tomcat, Resin, Jetty) do not come with JavaMail. For these, you shouldmove WEB-INF/lib/javamail-1.3.2.jar andWEB-INF/lib/activation-1.0.2.jar into the application server's lib/ directory, eg.common/lib/ for Tomcat. This is necessary because the application server is establishing theSMTP connection, not JIRA, and the application server won't see the jars in JIRA's classloader.

SMTP over SSL

You can encrypt email communications between JIRA and your mail server via SSL if your mailserver supports it. To do this, specify 'mail.smtps.*' properties instead of 'mail.smtp.*', eg inTomcat:

<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">....<Resource name="mail/JiraSecureMailServer"auth="Container"type="javax.mail.Session"

mail.smtps.host="mail.yourcompany.com"mail.smtps.auth="true"mail.smtps.port="25"mail.transport.protocol="smtps"mail.smtps.user="jirauser"

mail.smtp.starttls.enable="true"

password="secret"/>

</Context>

This example assumes that a SSL connection is negotiated via TLS over the standard SMTP port

JIRA Documentation

Page 202Copyright © 2002-2005 Atlassian All rights reserved.

Page 203: Jira Manual

(25). The mail.smtps properties configure the connection details once SSL is negotiated, andmail.smtp.starttls.enable property specifies the use of TLS to negotiate SSL (note smtp here notsmtps).

Additionally, as you are connecting to an SSL service, you will need to import the SMTP servercertificate into a Java keystore. The process is described on the Connecting to SSL Services page.

For example on linux, importing a certificate might be done with:$JAVA_HOME/jre/bin/keytool -import -alias jiramailserver -keystore ~/.keystore -file /etc/exim/exim.cert

Enter keystore password: changeitOwner: O=Atlassian, L=Sydney, ST=NSW, C=AUIssuer: O=Atlassian, L=Sydney, ST=NSW, C=AUSerial number: 0Valid from: Wed Dec 29 13:02:52 EST 2004 until: Sat May 15 12:02:52 EST 2032Certificate fingerprints:

MD5: 91:EC:6E:EA:73:7A:7C:4F:88:92:A2:A0:2B:F7:BC:CCSHA1: D8:7C:09:8A:8D:D8:7D:59:C2:28:2A:09:85:90:82:46:78:06:38:D5

Trust this certificate? [no]: yesCertificate was added to keystore

And Tomcat told of the keystore file location by adding to bin/setenv.sh:export JAVA_OPTS="-Djavax.net.ssl.trustStore=$HOME/.keystore"

4.15. Version Control Integration

4.15.1. How to set up CVS and ViewCVS integration

JIRA's CVS integration shows the related CVS commit information for an issue. When a CVScommit message mentions an issue, JIRA picks this up and displays the commit log in a tab in thementioned issue. Features include:

• Ability to interact with a CVS server directly via local access, pserver or external (ssh) protocols,or to parse a CVS log file generated by an external process.

• Access to the version control information in JIRA can be easily controlled using flexiblepermissions. If you are running a public instance of JIRA, and do not want the rest of the worldto see the version control information, JIRA can be configured to restrict access to thatinformation to the chosen users.

• If ViewCVS or Fisheye is available, the files and revisions in JIRA are linked to the relevantpages.

• In JIRA Enterprise, multiple CVS modules can be associated with each project.

4.15.1.1. Version Control Tab and ViewCVS

JIRA Documentation

Page 203Copyright © 2002-2005 Atlassian All rights reserved.

Page 204: Jira Manual

The Version Control tabAs you can see above, it is also possible to configure JIRA to work with ViewCVS. In this case,JIRA will turn the displayed commit information into ViewCVS links as shown above. Clickingthe name of the file will take the user to the ViewCVS file summary page. Clicking the revision,will take the user to the page that shows the contents of the file as it was at that revision. Clickingthe "diff" summary will show the ViewCVS "diff" page between the shown revision of the fileand its previous revision.

Please note:

• Currently, JIRA is able to retrieve CVS module's log data via local access, pserver protocolor ssh (ext method). If your CVS module is not reachable by these methods you can disableautomatic log retrieval.

• If you would like JIRA to automatically keep synchronized with your CVS repository thecommunication between JIRA and the CVS server might be fairly bandwidth intensive asJIRA will periodically retrieve the CVS module's log data from the CVS repository. If this iscausing problems consider disabling CVS log retrieval.

• JIRA loads and parses the output of the "cvs log" command for each CVS module and keeps"relevant" commits in memory. Therefore JIRA's memory requirements depend on thenumber of relevant commits found in the CVS module. Relevant commits are CVS commitswhich have at least one potential JIRA key in their commit messages.

• Only commit messages which contain the JIRA issue key are linked to the issue.

4.15.1.2. Configure CVS Modules

Each project in JIRA can be associated with a CVS module. In JIRA Standard a project can beassociated with only one module. In JIRA Professional and Enterprise editions a project can havemultiple modules. To set up CVS integration please follow the steps outlined below:

1. Create or decide which existing directory will be used to store CVS module's log data (Thefile with the output of the "cvs log" command). JIRA must have read and write access to thedirectory. The write access is required even if you choose to update the CVS log manually asJIRA needs to use this directory to create a lock file in order to synchronize access to theCVS module's log.

2. Login as a user with global administrator access.3. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

JIRA Documentation

Page 204Copyright © 2002-2005 Atlassian All rights reserved.

Page 205: Jira Manual

Link to Administration section

Link to Administration section

4. On the panel on the left, expand the sub-menu titled "Global Settings" if it is not open already.Click on the link labelled "CVS Modules". This should bring up the "CVS Modules" page.

5. Click on the "Add" new CVS module link on this page.6. This will bring up the "Add CVS Module" page.

JIRA Documentation

Page 205Copyright © 2002-2005 Atlassian All rights reserved.

Page 206: Jira Manual

Adding a CVS module

Fill in as follows:

1. For Name put a short descriptive name, possibly just the name of the CVS module as itappears in your CVS repository.

2. (Optional) For Description put a short phrase that describes this CVS module.3. For Log File Path specify the full path to the file that will contain the CVS log data. This

file should be located in a directory mentioned in step 1. If you would like JIRA toperiodically update the contents of the log this file does not need to exist at the moment,as JIRA will automatically create it. If you choose to manually update the file pleaseensure that the log file already exists at the specified path and is readable by JIRA.

4. Specify CVS Root that will be used to retrieve the CVS module's log or was used to

JIRA Documentation

Page 206Copyright © 2002-2005 Atlassian All rights reserved.

Page 207: Jira Manual

retrieve the log. The CVS Root is needed while parsing the log data so it is required even ifyou choose to retrieve CVS log manually. Please provide "full" CVS Root details. Forexample:• /some/local/path (for local repository access)• :pserver:username@hostname:port/some/path (for pserver access)• :ext:username@hostname:/some/path (for ssh access)If JIRA finds trouble understanding your local CVS Root (e.g. on Windows systems) pleaseprefix the path with :local:. For example, :local:d:\some\path.

5. For Module Name specify the name of the module as it is called in the CVS repository. Thisinformation is required to retrieve the CVS log as well as to parse it, so you will need toprovide the module's CVS name even if you choose to retrieve the CVS log manually.

6. Choose whether you would like JIRA to automatically synchonize with the CVS repository.If you choose "Automatically retrieve the CVS log", JIRA will periodically retrieve theCVS log for the module automatically and then parse it for commit information. If youchoose "I would like to update the log myself", JIRA will not retrieve the log, but willperiodically just parse it. If you choose this option you will need to update the CVS log byother means (e.g. manually or using a scheduled script) to keep the CVS information in JIRAcurrent.

7. The Password needs to be provided only if you let JIRA automatically retrieve the module'sCVS log. Please specify the password that is needed to retrieve the log using the methodspecified in the CVS Root. If no password is required, leave the field empty.

8. (Optional) For Base URL in the "ViewCVS Details" section of the page, enter the fullyqualified URL (i.e. include "http://" or "https://" at the beginning) to the ViewCVS site of theCVS module. The URL needs to point to the root of the module on the ViewCVS site.

9. (Optional) For Root Parameter in the "ViewCVS Details" section of the page, enter thename of the Project Root that is used in ViewCVS to navigate the CVS module. Thisparameter is required only if ViewCVS has been set up to work with multiple CVS modules,and this module is not the default module on the ViewCVS server. The value that should beplaced in this field is the same as the value of the 'root' URL parameter that appears on everyViewCVS URL (e.g. when viewing a file). If the URL that appears in your browser whenviewing a file from this CVS module on ViewCVS does not have the 'root' parameter, leavethis field blank.

7. Click the "Add" button.8. This should bring you back to the "CVS Modules", where you should see the new CVS module

listed. You can edit and delete this module here.

Note:If JIRA finds trouble understanding your local CVS Root (e.g. on Windows systems) please prefix the path with :local:. For example,:local:d:\some\path

4.15.1.3. Associate Project(s) with CVS Modules

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 207Copyright © 2002-2005 Atlassian All rights reserved.

Page 208: Jira Manual

Link to Administration section

3. This will bring up the "Projects" page. It lists all the existing projects. Select a project thatyou would like to associate with the CVS module.

4. In the project's summary section of the page, click on the "select module" link. This willbring up a page, where you can associate the project with one CVS module if you are usingthe Professional version of JIRA, or multiple modules if you are using the Enterprise versionof JIRA.

5. Select the appropriate module(s), and click "Select" button.

4.15.1.4. Configuring Permissions

Now, the "View Version Control" permission needs to be given to users/groups that should beallowed to see CVS commit information. Note, by default this permission is given to the'jira-developers' group. Please read the Permissions section, and follow the instructions giventhere to assign the "View Version Control" permission.

4.15.1.5. How it Works

JIRA retrieves the CVS commit information for an issue by parsing the output of the "cvs rlog"(or cvs log) command of each associated CVS module and scanning it for the issue's key. If anissue key is found in the commit message, the commit message is displayed on the VersionControl tab for the issue.

If you have allowed JIRA to automatically synchronize with the CVS repository JIRA willperiodically run the "cvs rlog" command for the module and store the results in a file which pathis specified by the module's Log File Path attribute. The file is then parsed for commitinformation.

Note:Even if you are using local repository access JIRA will obtain the CVS log for the module and then parse it. JIRA does not accessthe CVS repository directly.

If you have chosen to update the log manually JIRA will only periodically parse the CVS logspecified by the module's Log File Path attribute.

As JIRA parses the module's CVS log and keeps relevant commits in memory, the requiredmemory for JIRA is relative to the size of the CVS module.

4.15.1.6. Disabling Automatic CVS Log Retrieval

To disable automatic CVS log retrieval for a CVS module please choose "I would like to updatethe log myself" option for the module's Log Retrieval attribute.

If you have disabled automatic CVS log retrieval for the CVS module JIRA will only parse theCVS log periodically. Therefore for the new commit information to appear in JIRA the log needsto be updated by other means. This can be done manually or a scheduled script can be used.

Note:Before updating the module's CVS log please check for the existence of a lock file with name cvslog.write.lock in the same directoryas the CVS log file. If the lock file exists please wait until it is removed before updating the log.

JIRA Documentation

Page 208Copyright © 2002-2005 Atlassian All rights reserved.

Page 209: Jira Manual

When updating the CVS log for a module please create a lock file with name cvslog.write.lock in the same directory as the CVS log file toensure that JIRA does not start parsing the log while it is still being updated. Please do not forget to remove the lock file after the updatehas finished.

4.15.1.7. Frequency of Module Updates

To minimise the network traffic between JIRA and the CVS server, JIRA updates and re-parses thecommit information of the associated CVS modules only once during the specified period of time.By default, this period of time is 1 hour, but it can be adjusted if required.

When the first CVS module is created in JIRA, a background service is automatically started. Theservice is called "VCS Update Service". To change the frequency of the module updates follow thefollowing steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Open the "System" tab of the left-hand menu, if it is not already open.4. Select "Services" from the "System" tab of the left-hand menu. The page showing all the

configured services should appear. If at least one CVS module has been configured the "VCSUpdate Service" should be present in the list.

5. Click the "Edit" link in the right-most column of the "VCS Update Service". This should bringup a page where you can set the delay for the service.

6. Change the value as required. Remember, the delay is specified in minutes.7. Click the "Update" button to make the changes take effect.

Please keep in mind:

• The CVS modules are updated one after another every specified period of time. That is, it is notpossible to specify a different update delay for each configured CVS module.

• If you are using automatic log retrieval for your CVS modules and you set the delay to a verylow value, the bandwidth consumption between JIRA and the CVS server might be very high.

• If the delay is set to a very large value the "new" cvs commit messages will not appear in JIRAfor some time.

4.15.1.8. CVS Aliases

JIRA does not currently support CVS aliases. If you have a CVS aliases that references more thanone module please create each CVS module in JIRA and then associate each module with therelevant JIRA Projects. The feature request for adding CVS module support to JIRA is JRA-4586.Please vote for the issue to increase its popularity. Please refer to this document which described theway Atlassian implements new features and improvements.

JIRA Documentation

Page 209Copyright © 2002-2005 Atlassian All rights reserved.

Page 210: Jira Manual

4.15.2. Subversion integration

JIRA's Subversion integration lets one see Subversion commit information relevant to each issue.Subversion integration is implemented as a plugin (drop-in extension) to JIRA.

Subversion tab screenshotCommits will appear in this tab if the commit log mentions the issue key ('TEST-3' above).

For more information, see the Subversion plugin page online.

4.15.3. Perforce integration

JIRA's Perforce integration lets one see Perforce commit information relevant to each issue:

JIRA Documentation

Page 210Copyright © 2002-2005 Atlassian All rights reserved.

Page 211: Jira Manual

Viewing an issue with its associated Perforce job and linked changelists.This includes two-way integration with Perforce Jobs, for example creating a job when an issue iscreated:

Issue create screen showing optional creation of P4 joband searching for JIRA issues with associated perforce jobs:

JIRA Documentation

Page 211Copyright © 2002-2005 Atlassian All rights reserved.

Page 212: Jira Manual

Issue navigator interface to query by perforce job.Perforce integration is implemented as a plugin (drop-in extension) to JIRA, which is licensedseparately to JIRA. For more information, see the Perforce plugin page online.

4.16. LDAP Integration

Many organizations have an LDAP directory acting as a centralized database of system users.JIRA is able to authenticate users against their LDAP password. This guide describes how to setthis up.

In JIRA, user management is handled by OSUser, a pluggable user management framework.OSUser is configured through the WEB-INF/classes/osuser.xml file.

In the standalone distribution, this file can be edited directly inatlassian-jira/WEB-INF/classes/osuser.xml. In the webapp distribution, it should be copiedfrom webapp/WEB-INF/classes/osuser.xml to edit-webapp/WEB-INF/classes/, edited there,and then rebuilt into an updated .war file with the 'ant war' command.

JIRA Enterprise contains a configuration utility which lets you auto-generate a valid osuser.xmlfile. This can be accessed from Admin -> System -> LDAP:

JIRA Documentation

Page 212Copyright © 2002-2005 Atlassian All rights reserved.

Page 213: Jira Manual

LDAP Configurer in JIRA EnterpriseIn JIRA Professional and Standard, the same configuration can be done by hand.

The default osuser.xml contains:

<opensymphony-user><authenticator

class="com.opensymphony.user.authenticator.SmartAuthenticator" />

<providerclass="com.atlassian.core.ofbiz.osuser.CoreOFBizCredentialsProvider"><property name="exclusive-access">true</property>

</provider>

<providerclass="com.opensymphony.user.provider.ofbiz.OFBizProfileProvider">

<property name="exclusive-access">true</property></provider>

<providerclass="com.opensymphony.user.provider.ofbiz.OFBizAccessProvider">

<property name="exclusive-access">true</property></provider>

</opensymphony-user>

CredentialsProviders are responsible for checking usernames and passwords, which is what we areinterested in here. The default CoreOFBizCredentialsProvider looks in the JIRA database. We aregoing to add a LDAPCredentialsProvider, so that LDAP users can also be authenticated:

<opensymphony-user><authenticator class="com.opensymphony.user.authenticator.SmartAuthenticator" />

<providerclass="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">

JIRA Documentation

Page 213Copyright © 2002-2005 Atlassian All rights reserved.

Page 214: Jira Manual

<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property><property name="java.naming.provider.url">ldap://localhost:389</property><property name="searchBase">dc=atlassian,dc=com</property><property name="uidSearchName">uid</property><!--<property name="java.naming.security.principal">cn=Manager,dc=atlassian,dc=com</property><property name="java.naming.security.credentials">secret</property><property name="exclusive-access">true</property>--></provider>

<provider class="com.atlassian.core.ofbiz.osuser.CoreOFBizCredentialsProvider"><property name="exclusive-access">true</property>

</provider>

<provider class="com.opensymphony.user.provider.ofbiz.OFBizProfileProvider"><property name="exclusive-access">true</property>

</provider>

<provider class="com.opensymphony.user.provider.ofbiz.OFBizAccessProvider"><property name="exclusive-access">true</property>

</provider>

</opensymphony-user>

It is necessary to use both the LDAP and OFBiz providers, and the order must be as shown(LDAP first).

Some LDAP properties that are commonly set here are:

Property Required Description Example

java.naming.factory.initialYes Specifies that JNDI(the directory API)should use the LDAPimplementation

Should always becom.sun.jndi.ldap.LdapCtxFactory

java.naming.provider.url Yes LDAP URL of yourserver

ldap://localhost:389

searchBase Yes The node in the LDAPtree to search belowfor usernames.

The root LDAP node istypically called'dc=companyname,dc=com',and user accountnodes are usuallystored in a subtree, like'cn=Users,dc=companyname,dc=com'.

uidSearchName Yes Attribute expected tocontain username

Typically uid, orsAMAccountName forMS ActiveDirectory.

java.naming.security.principalNo Username to initiallylog in to LDAP as. Notrequired if anonymoususer lookups areallowed.

Eg.'cn=Administrator,cn=Users,dc=companyname,dc=com'

java.naming.security.credentialsNo Password for initiallogin. Not required ifanonymous lookupsare allowed.

providerName No (in JIRA 3.2-beta andabove) unique namefor this LDAP provider.Useful when youspecify multiple LDAP

JIRA Documentation

Page 214Copyright © 2002-2005 Atlassian All rights reserved.

Page 215: Jira Manual

providers (allowingfallback), and need todistinguish them in thedebug logs.

cacheTimeout No The value inmilliseconds forduration of passwordcaching. Passwordcaching reduces theload JIRA will put onthe LDAP server. Onlysuccessfulauthentication attemptsare cached. Thedefault value is 30minutes (1,800,000ms).

0 (to disable caching)

The full list of properties is specified in the JNDI documentation.

Once you have made this modification and restarted JIRA, JIRA users whose username also existsin LDAP will be authenticated against their LDAP password.

4.16.1. LDAP over SSL

With plain LDAP, passwords may be passing over the network unencrypted, which (depending onyour network security) may be a security problem. If you wish to connect to LDAP over SSL, seethe Connecting to SSL services guide for details on how to import the SSL server's public key. Inosuser.xml, you would need to use ldaps:// in the URL if you have port 636 dedicated to LDAPover SSL.

4.16.2. How it works

It is useful to have a general idea of how this setup works. This section outlines some consequencesof the current implementation, and provides some help for people experiencing LDAP connectionproblems.

4.16.2.1. Only password-checking for LDAP users done in JIRA

The main point to realise is that user profiles are still managed in JIRA (the OFBizProfileProvider inosuser.xml). Only the password lookup is done against LDAP, and only if the JIRA usernamecoincides with a LDAP username.

Technically, this behaviour is due to Credentials (password) checking being a separate operation touser-profile lookups. The profile can be loaded from the JIRA database, but the password looked upfrom LDAP. Furthermore, multiple credentials providers can be specified (here, LDAP andOSUser), and if one fails, the other will be used. This allows non-LDAP users to log in with theirJIRA password.

4.16.2.2. Not all LDAP users have JIRA access

Another effect of this implementation is that LDAP users do not automatically have access to JIRA.A JIRA account must be created for each user wishing to use JIRA. You can bulk-create users fromLDAP with this LDAP user importer.

This is because each JIRA user has a set of groups (for example, 'jira-users') stored in their profile.Without an associated group, that user can do nothing; not even browse JIRA (they lack the 'use'

JIRA Documentation

Page 215Copyright © 2002-2005 Atlassian All rights reserved.

Page 216: Jira Manual

permission).

Thus, for an LDAP user to be able to use JIRA, a JIRA admin must create an account for them,and assign them to a group (typically 'jira-user'). The password in this JIRA account will beignored, as the LDAP password will override it.

4.16.2.3. Debugging

If JIRA does not authenticate against the LDAP password, then something is probably wrongwith your setup. First, ensure that the user you are trying to connect as has a JIRA account (seeabove). Make sure you have the LDAP connection details correct (basename, uid,username/password). These details are best discovered with the help of an LDAP browser.

To see exactly why LDAP authentication is failing, follow these steps:

1. Edit log4j.properties (instructions), locate the lines:log4j.category.com.opensymphony = WARN, consolelog4j.additivity.com.opensymphony = false

Duplicate these, and change the first copy to:log4j.category.com.opensymphony.user.provider.ldap = DEBUG, consolelog4j.additivity.com.opensymphony.user.provider.ldap = false

This turns up logging for the LDAP authentication module.

When next trying to log in, you should see extra logs on stdout. A successful authentication lookslike this:DEBUG [user.provider.ldap.LDAPCredentialsProvider] LDAPCredentialsProvider $Revision: 1.2 $ initializingDEBUG [user.provider.ldap.LDAPCredentialsProvider] 'jturner' will be handled by LDAPDEBUG [user.provider.ldap.LDAPCredentialsProvider] 'jturner' will be handled by LDAPDEBUG [user.provider.ldap.LDAPCredentialsProvider] 'jturner' will be handled by LDAPDEBUG [user.provider.ldap.LDAPCredentialsProvider] Doing initial search:

username='cn=admin,dc=atlassian,dc=com', password='secret', base='ou=People,dc=atlassian,dc=com', filter='uid=jturner'DEBUG [user.provider.ldap.LDAPCredentialsProvider] Found usersDEBUG [user.provider.ldap.LDAPCredentialsProvider] Searching below 'uid=jturner,ou=People,dc=atlassian,dc=com' for 'uid=jturner'DEBUG [user.provider.ldap.LDAPCredentialsProvider] User 'jturner' successfully authenticated; caching for 1800000 ms

This log was generated with the following to osuser.xml:<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider"><property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property><property name="java.naming.provider.url">ldap://localhost:389</property><property name="searchBase">ou=People,dc=atlassian,dc=com</property><property name="uidSearchName">uid</property><property name="java.naming.security.principal">cn=admin,dc=atlassian,dc=com</property><property name="java.naming.security.credentials">secret</property><property name="exclusive-access">true</property>

</provider>

If you have problems, try emulating the operations performed by the LDAP authenticationprovider. The LDAP authentication provider works by first doing an search for the specifiedusername, searching from base searchBase, using query uidSearchName=username,authenticating using the principal and credentials properties if present, or doing an anonymoussearch otherwise. If an entry is found, it then tries to log in to LDAP using the specified matchingusername and specified password.

Note:If you get an error message javax.naming.PartialResultException: Unprocessed Continuation Reference(s), try adding<property name="java.naming.referral">follow</property> to the LDAPCredentialsProvider section.

4.16.3. Improvements

Currently, only passwords can be stored in LDAP. For a information on to disabling password

JIRA Documentation

Page 216Copyright © 2002-2005 Atlassian All rights reserved.

Page 217: Jira Manual

management within JIRA when using LDAP intergration consult the Configuring JIRAdocumentation. In future, we plan to more tightly integrate LDAP into JIRA, so that LDAP groupscan be mapped to JIRA groups, and user management can be fully externalized. We'd like feedbackas we go further with this; please see this issue report for current status, and add your use-case as acomment. Thanks!

Note:See these notes on how to set up a LDAP directory on a Linux server.

4.17. Operational Tasks

4.17.1. Search Indexing

In order to provide fast searching, JIRA creates an index of the text entered into issue fields. Thisindex is stored on the filesystem, and updated whenever issue text is added or modified. It issometimes necessary to regenerate this index manually; for instance if issues have been manuallyentered into the database, or the index has been lost or corrupted.

4.17.1.1. Indexing Administration

To get to the indexing page first go to the Administration section and then on the left panel, underthe title System, click on the Indexing link.

This page allows you to reindex your data, or move your index to another directory.

Note:Whenever you reindex data, JIRA will clear any existing indexes and re-index all the current data from scratch. This may take a fewminutes, depending on how many issues you have, and users will be unable to access JIRA during this time.

4.17.2. Backing up data

This page describes how to back up JIRA data, and establish processes for maintaining continualbackups. Backing up JIRA's data is the first step in upgrading your server to a new JIRA revision, orsplitting your JIRA instance across multiple servers. See also the Restoring JIRA data page.

Creating a complete backup of JIRA consists of two stages:

1. Backing up the data in the database2. If attachments are enabled, backing up the attachments directory

4.17.2.1. Backing up database contents

There are two possibilities - JIRA's built-in XML backup capabilities, or native database-specifictools. Here we consider them both:

Using JIRA's XML backup service

Undoubtedly the easiest backup option is to rely on JIRA's ability to generate backups of databasecontent in XML (text) format. The first step in the setup wizard prompts you for a backup path, andif entered, JIRA will automatically generate XML backups every 12 hours. If you did not specifythis path, see the Automating JIRA Backups page for how to enable this.

Once-off XML backups

JIRA Documentation

Page 217Copyright © 2002-2005 Atlassian All rights reserved.

Page 218: Jira Manual

Besides the automated backup service, once-off backups (eg. before an upgrade) can be made asfollows:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Import & Export", click "Backup Data to XML".This will bring up the "Backup JIRA data" page.

Backup data from XML4. In the form, fill in the File path data entry box with a full path, including filename, that JIRA

can write to.5. Select the "Backup as Zip" checkbox.6. Click the Backup button, and be patient.7. JIRA will return, confirming that it has written out the content to the file specified above.

Using native database tools

All serious databases come with tools to back up and restore databases (the 'MS' in RDBMS). Werecommend these tools in preference to the XML backup option described above, as they:

• are much faster and less resource-intensive than JIRA's XML backup.• integrate with existing backup strategies (eg. allowing one backup run for all database-using

apps).• allow the database and attachments to be backed up at the same time.• may allow for incremental (as opposed to 'full') backups, saving disk space.• avoid character encoding and format issues relating to JIRA's use of XML as a backup

format.

See the documentation for your database on how to set up periodic backups. This typicallyinvolves a cron job or Windows scheduled task invoking a command-line tool like mysqldump orpg_dump,

JIRA Documentation

Page 218Copyright © 2002-2005 Atlassian All rights reserved.

Page 219: Jira Manual

4.17.2.2. Backup attachments

If you have attachments enabled you also need to create a backup of the attachments directory, as theattachments do not get stored in the database.

To back up attachments, a snapshot of the attachment directory (all files and subdirectories) needs tobe created. Note, the directory structure under the attachments directory must be preserved in thecreated snapshot during the backup.

Creating this snapshot is a fairly operating system-specific task.

On MS Windows, a batch script copying the directory can be written and scheduled periodically(Programs > Accessories > System Tools > Scheduled Tasks). There are also various utilitiesavailable to simplify this (eg. http://www.picozip.com).

On Linux/Solaris, it is best to write a small shell script, placed in /etc/cron.daily, backing upfiles to a directory like /var/backup/jira. It is best to copy an existing script in/etc/cron.daily to ensure local conventions (file locations, lockfiles, permissions) are adheredto.

4.17.3. Restoring data

This page describes how to restore JIRA data from a backup. This is the second step in eitherupgrading your server to a new JIRA revision, or splitting your JIRA instance across multipleservers.

Note:When restoring data, all data in the existing JIRA database is deleted, including all user accounts. Make sure you have the password toa login in the backup file that has global administration level access before importing.

Restoring JIRA from backup is a three stage process:

1. Optionally, disable email sending/receiving2. Restore data from XML to the database3. Optionally, if attachments were backed up, restore the attachments to the attachments directory

4.17.3.1. Disabling email sending/receiving

If you are restoring production data into a test JIRA instance to play around with, you probably wantto disable JIRA's email interaction features before you begin:

• Disable email notifications - if JIRA is configured to send emails of any changes, and you wantto make test modifications to the copy, you should start JIRA with the-Datlassian.mail.senddisabled=true flag.

• Disable POP email polling - if JIRA is configured to poll a POP mailbox, to create issues frommails, you will likely want to disable this polling on your test installation. This is done by settingthe -Datlassian.mail.popdisabled=true flag.

Exactly how to set these flags is dependent on your app server, but for Tomcat (JIRA Standalone), itis done by setting the JAVA_OPTS environment variable before starting JIRA:set JAVA_OPTS="-Datlassian.mail.senddisabled=true -Datlassian.mail.popdisabled=truecd binstartup.bat

4.17.3.2. Restoring XML data

Here we assume you are restoring an XML backup. Alternatively if you use native database tools to

JIRA Documentation

Page 219Copyright © 2002-2005 Atlassian All rights reserved.

Page 220: Jira Manual

create backups, the restore process will also be tool-specific.

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. On the panel on the left, under the title "Import & Export", click on the link labelled "RestoreData from XML". This will bring up the "Restore JIRA data from Backup" page.

Restore data from XML4. In the form, fill in the path to the zip or XML backup file generated by JIRA.5. Check or (if in the setup wizard) fill in the Index Location path. Ensure this directory

contains only the indexes, as its contents may be deleted in subsequent operations.

6. Click the Restore button, and be patient.7. JIRA will come back, informing you that you have been logged out. This is done because all

the users from the previous JIRA instance have been deleted and replaced with users from theJIRA export file.

8. Log in, and if necessary, correct the search index path.

4.17.3.3. Restoring Attachments

If you have created a backup of the attachments directory, you will need to restore the backupinto a directory where JIRA can access it. The process of restoring the attachments backupdepends on the way it was created. Usually you can use the same tool to restore the backup as theone that was used to create it. Ensure the attachment file permissions are correct.

If you have restored the attachments to a different location (directory path) that the path that wasspecified in JIRA when the backup was created (e.g. when moving servers), please follow theinstructions given here to change the location of the attachments directory so JIRA can find therestored attachments.

4.17.4. Upgrading JIRA safely

JIRA Documentation

Page 220Copyright © 2002-2005 Atlassian All rights reserved.

Page 221: Jira Manual

This page describes the recommended process for upgrading an existing JIRA installation. Beforeyou start, you should review the release and upgrade notes for the version you are upgrading to.

The upgrade process is essentially:

• create an XML backup• create a new database• ensure the new JIRA is using the new database• restore the XML backup into the new JIRA

These steps are elaborated below for various scenarios.

Note:You can simply point the new JIRA at your old database, and JIRA will automatically upgrade the database schema. We recommend thefull new database/restore XML process as this allows column type changes to take effect (you will see warnings on startup otherwise) andlets newly defined indexes to be created,

Note:When performing a backup of Jira the properties files you have configured for any plugins (such as the subversion plugin) are notincluded in the backup process and should be manually copied across if you are configuring a new Jira installation.

4.17.4.1. Back up and Test with JIRA Standalone

It is always a good idea to test the new JIRA version running with your data, before deploying it inproduction. This allows you to check for problems, and ensures you have a working backup ifsomething goes wrong later.

Testing is most easily done as follows:

1. Generate a backup (Admin -> Import & Export -> Backup) of your data from your existingJIRA.

2. Download the Standalone distribution of JIRA.3. Copy the values of the modified properties from the old

WEB-INF/classes/jira-application.properties file to the new one. Do not justcopy the file across, as the new version of JIRA could have new properties that are missing in theold file.

4. If necessary, disable email access in this JIRA Standalone instance to prevent inadvertentSMTP/POP/IMAP access while testing (see the Restore a backup page for details).

5. Restore this backup (Admin -> Import & Export -> Restore) into the standalone instance.6. If running on the same server as the live JIRA, make sure you change the index directory (Admin

-> System -> Indexing) to avoid conflicting with the live one.7. Test the standalone JIRA installation, checking that there are no errors in the log file.

4.17.4.2. Upgrade JIRA

Having deployed your data in JIRA Standalone, you now have a known-working backup, and canproceed to upgrade your live JIRA. Choose the section below which applies to you:

JIRA Standalone

If you are happy running JIRA Standalone, and have been through the steps above, you're done - justcopy the newly configured JIRA Standalone to its permanent home, and enable email if you disabledit during testing.

JIRA Standalone + external database

JIRA Documentation

Page 221Copyright © 2002-2005 Atlassian All rights reserved.

Page 222: Jira Manual

If you are currently running JIRA Standalone configured to use an external database, you should:

• Create an XML backup (or use the one from the previous section).• Create a new database. For instance, if you previously used database jiradb, create database

jiradb_34 (for JIRA 3.4) with identical access permissions.• Reapply the modifications you made to Standalone to get the new Standalone instance to

using your database, but substituting the new database name (jiradb_34 in the aboveexample) in the JDBC URL.

• Copy the values of the modified properties from the oldWEB-INF/classes/jira-application.properties file to the new one. Do notjust copy the file across, as the new version of JIRA could have new properties that aremissing in the old file.

• Start the new JIRA Standalone (now with a blank database), and import the XML backup.

Example: JIRA Standalone with Oracle

Say you currently use Oracle with JIRA 3.1.1 Standalone. In your old JIRA directory, you wouldhave modified edit-webapp/WEB-INF/classes/entityengine.xml to:

• set field-type-name="oracle"• to set driverClassName to oracle.jdbc.driver.OracleDriver• JDBC URL to something like jdbc:oracle:thin:@localhost:1521:jiradb• Set the SetBigStringTryClob=true property to allow fields over 4000 characters

These changes should be hand-ported to the same file in the new JIRA Standalone distribution,following the Oracle notes. The JDBC URL would bejdbc:oracle:thin:@localhost:1521:jiradb_323, and the field-type-name would befield-type-name="oracle10g" (new in 3.2 and above - see the upgrade guide).

After creating a new jiradb_323 database in Oracle, JIRA should then start correctly with theblank database, in which you can restore the old data.

External app server

If you have JIRA deployed as a webapp in your own app server, the upgrade process is similar tothat of making an initial clean install:

1. download and unpackage the JIRA WAR/Webapp distribution2. Customize edit-webapp/WEB-INF/classes/entityengine.xml (see the configuration

overview), referring to the modified entityengine.xml file from your previous JIRA webapp.The entityengine.xml format could have changed, so it is best to hand-edit the new one, ratherthan just copy over the old one.

3. Similarly to entityengine.xml, check other files you have customized in edit-webapp/ ofyour old JIRA. For instance, the osuser.xml file (if you use it) needs porting (it changedformats between 2.5.3 and 2.6, so again a hand-comparison is recommended).

4. Run build.bat or build.sh to build the new webapp5. Tomcat, Jetty and Resin users: these app servers need extra libraries to run JIRA, and the

extra libraries currently in your app server may be outdated. Download the extra jars packagefrom the relevant app server configuration guide and check.

6. Create a new database (eg. jira_323) with same access permissions as the old one, and editthe JDBC URL in your app server to use the new database.

7. Copy the values of the modified properties from the oldWEB-INF/classes/jira-application.properties file to the new one. Do notjust copy the file across, as the new version of JIRA could have new properties that aremissing in the old file.

8. Now stop the app server, remove the old JIRA webapp from your app server, and copy in the

JIRA Documentation

Page 222Copyright © 2002-2005 Atlassian All rights reserved.

Page 223: Jira Manual

new one.

Note:If using Tomcat, delete the Tomcat work/ directory before restarting to avoid odd JSP problems.

9. Start the app server. You should see the JIRA Setup wizard, as JIRA is using the new database.Now restore the backup XML.

4.17.4.3. After an upgrade

• Immediately after an upgrade, it is advisable to check your server logs for error messages, even ifJIRA appears to be working correctly.

• If you changed servers when upgrading, make sure to change the path to the indexes,attachments and backup directories. This is done once JIRA is running, in the Administrationsection.

4.17.4.4. Problems?

If you have problems and need to revert back to your previous version, you can restore your datafrom the backup file you made in step 1. As mentioned, the XML cleaner utility is useful if you haveXML-related problems. If you need help, please raise a support request.

4.17.5. Splitting a JIRA instance

Warning:Before carrying out any of the following, always backup your database using your database backup procedures, and test that the backupsare good.

Splitting a JIRA instance is easy. Firstly, create a backup file from you current production server, asdescribed in How to backup your data. Import this backup file into your second production machine,as described in How to restore your data. At this point you have two JIRA instances with identicalstate - projects, users, issues, et al. At this point delete the non-required projects from each server.

Note:This requires two separate server licenses.

4.17.6. Database Integrity Checker

4.17.6.1. Overview

Searching for common data inconsistencies, the Database Integrity Checker attempts to ensure thatall JIRA data is in a consistent state.

This is useful in a number of situations - for example:

• Before migrating a project to a new workflow• An external program is modifying JIRA's database• The server suddenly crashed

If an error is encountered, most integrity checks provide a 'repair' option which attempts to reset thedata to a stable state.

4.17.6.2. Using the Integrity Checker

1. Login as a user with global administrator access.2.

JIRA Documentation

Page 223Copyright © 2002-2005 Atlassian All rights reserved.

Page 224: Jira Manual

Bring up the administration page by clicking either on the "Administration" link on the topbar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. If the "System" sub-menu is not already open, choose "System" from the left-hand menu toopen it.

4. Click on the "Integrity Checker" link to navigate to the screen shown below.

JIRA Documentation

Page 224Copyright © 2002-2005 Atlassian All rights reserved.

Page 225: Jira Manual

IntegrityChecker Screenshot5. The integrity checker has a number of "integrity checks" that look for common inconsistencies in

the data. You can select one or more checks you would like to run and then press "Preview".6. After the selected checks run, the preview screen will be shown.

The screen provides details about the existing data inconsistencies. If any inconsistencies werefound, the "Correct" button will also appear on the page. The messages in red describeinconsistencies that the check will correct if it is chosen and the "correct" button is clicked.Messages that appear in yellow are warnings that the check will not correct. JIRA willauto-recover from these inconsistencies when an action is taken on an issue, for example. Youcan select which inconsistencies you would like to correct and click the "Correct" button.

7. If any inconsistencies were found and you choose to correct them, you will be presented with asummary screen describing all the corrective actions that have taken place after theinconsistencies are fixed.

Note:

JIRA Documentation

Page 225Copyright © 2002-2005 Atlassian All rights reserved.

Page 226: Jira Manual

We strongly recommend taking a backup of your data before correcting any data inconsistencies.

4.18. Importing from Other Systems

4.18.1. Importing Data from Bugzilla

JIRA can import your bugs from Bugzilla. Currently, the import has been successfully test onBugzilla versions 2.16, 2.17 and 2.18. The data from the Bugzilla database is appended to theexisting data in JIRA. The tool imports the following data from the Bugzilla database:

In Bugzilla In JIRA Special Notes

Bugs Issues • Attachments are extractedfrom the Bugzilla databaseand saved to disk

• Statuses, Bug Severity, IssueTypes, and Resolutions inBugzilla are mapped to thedefaults in JIRA

• Statuses in Bugzilla aremapped to JIRA. Bugs inBugzilla in the 'NEW','UNCONFIRMED', or'ASSIGNED' status with noassignees are 'Open' in JIRA.

• Issue Types of bugs fromBugzilla are all 'Bugs' or'Improvements'

• Bug_Severity in Bugzilla ismapped to Priorities in JIRA.Bugs with'ENHANCEMENT' severityin Bugzilla are treated as'Improvement' issues with'MINOR' Priority in JIRA.Note: if you have customizedthe Bugzilla list of priorities,you will need to edit theImporter source and define thenew mappings.

• The first description for a bugin Bugzilla is stored as JIRA'sDescription. All otherdescriptions are stored ascomments logged to thatissue.

• If a user has voted one ormore times for a Bugzillaissue, a JIRA vote is storedfor that user

Product Project • The project key and projectlead can be set by the user.

Version Version • Versions for imported projectsare imported from Bugzilla,and set to Un-Released andUn-Archived state.

• The JIRA "Fix For" Version isset to the Bugzilla bug'milestone', if it exists. Note:this code is not well tested -

JIRA Documentation

Page 226Copyright © 2002-2005 Atlassian All rights reserved.

Page 227: Jira Manual

please let us know if you haveproblems.

Component Component

User User • Users are imported 'ondemand', so users who havenot interacted with the systemin any way are not imported.

• Passwords from Bugzilla arenot imported for v2.16+ ofBugzilla (as they areencrypted in the database).Users from Bugzilla will needto get their passwords emailedto them the first time they loginto JIRA.

• Users with no real namestored in Bugzilla will get theportion of their email address(login name) before the "@"character as their Full Namein JIRA.

4.18.1.1. How to import from Bugzilla

1. In JIRA's Default permission scheme (associated with newly imported projects), ensure that theBrowse, Create and Comment permissions are granted to group 'jira-users' (or a group with theglobal "JIRA Users" permission). This is the default.

2. Make sure that the Bugzilla database you wish to import from is running on MySQL.3. Download and install the MySQL JDBC driver into JIRA. To do this, download the MySQL

Connector/J driver. The package contains a file "mysql-connector-java-xxx.jar". Copy this to thecommon/lib/ directory in JIRA Standalone, or equivalent "lib" directory in your app server.Restart JIRA so the driver is loaded.

4. Login as a user with global administrator access.5. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

6. On the panel on the left, under the title "Import & Export", click "External System Import"

JIRA Documentation

Page 227Copyright © 2002-2005 Atlassian All rights reserved.

Page 228: Jira Manual

Link in Admin section

Then select 'Bugzilla' on the subsequent page.

7. You will now be prompted for connection details to Bugzilla's MySQL database:

Bugzilla Importer Connection screen

Set the JDBC URL, database username and password for your system. The JDBC URL is ofthe format:jdbc:mysql:host[:port]/databasename?parameters

host is the server hosting JIRA, whose MySQL allows incoming TCP connections on portport (defaults to 3306). databasename is the MySQL database name (usually 'bugs').

The database name, username and user password can usually be found in the 'localconfig' filein Bugzilla's root directory, or in /etc/bugzilla/.

8. Click 'Next >>' to advance to the project selection page. If you have got the connectiondetails wrong, you may have to wait about 30s for the connection attempt to time out.

9. You will now be presented with a list of projects in Bugzilla:

JIRA Documentation

Page 228Copyright © 2002-2005 Atlassian All rights reserved.

Page 229: Jira Manual

Choosing Bugzilla projects to import

Select the projects you wish to import (even if there is only one — select it!), and set importoptions via the checkboxes (the default checkbox settings is correct for most users). Click 'Next>>' to proceed.

10.You will now be prompted to choose a project key (the per-project prefix to attach to bug keys),and a project lead for each project to be imported. Important: do not use dashes or numbers inthe project key!

JIRA Documentation

Page 229Copyright © 2002-2005 Atlassian All rights reserved.

Page 230: Jira Manual

Choosing JIRA project keys and leads for projects

Click 'Import' when you are done to start the import. As imports frequently take a long time,you can watch the logs as they are generated by clicking the 'watch logs in separate window'link. Logs are also sent to stdout, and will appear in your app server's log:

Importing project(s) 'Xerces-P', 'Xindice', 'XmlCommons'2004-02-27 15:34:10,031 INFO [atlassian.jira.util.BugzillaImportBean] Importing Project: Xerces-P2004-02-27 15:34:10,052 INFO [atlassian.jira.util.BugzillaImportBean] Importing Project: XmlCommons2004-02-27 15:34:10,061 INFO [atlassian.jira.util.BugzillaImportBean] Importing Project: Xindice2004-02-27 15:34:10,069 INFO [atlassian.jira.util.BugzillaImportBean] 3 projects imported from Bugzilla.2004-02-27 15:34:10,069 INFO [atlassian.jira.util.BugzillaImportBean]

Importing Versions from project 'Xerces-P', 'Xindice', 'XmlCommons'

2004-02-27 15:34:10,071 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: 1.5.62004-02-27 15:34:10,080 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: unspecified2004-02-27 15:34:10,087 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: SWIG-1.32004-02-27 15:34:10,093 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: 1.32004-02-27 15:34:10,098 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: 1.4...2004-02-27 15:34:10,228 INFO [atlassian.jira.util.BugzillaImportBean] Importing Component: SWIG2004-02-27 15:34:10,292 INFO [atlassian.jira.util.BugzillaImportBean] Importing Component: Test Scripts2004-02-27 15:34:10,346 INFO [atlassian.jira.util.BugzillaImportBean] Importing Component: Documentation...Importing Issues from project(s) 'Xerces-P', 'Xindice', 'XmlCommons'2004-02-27 15:34:11,341 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "All filesneed Apache license"2004-02-27 15:34:11,343 INFO [atlassian.jira.util.BugzillaImportBean] Importing User:[email protected] 15:34:16,430 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "SEGV on:getAttributes() in list context"2004-02-27 15:34:16,545 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "Sample codemust be updated"2004-02-27 15:34:16,680 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "SWIG 1.3rohibits sub-classing of wrapped classes"2004-02-27 15:34:16,878 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "AttributeList inPerl is broken (can't get attributes)"2004-02-27 15:34:16,909 INFO [atlassian.jira.util.BugzillaImportBean] Importing User: [email protected]....

JIRA Documentation

Page 230Copyright © 2002-2005 Atlassian All rights reserved.

Page 231: Jira Manual

2004-02-27 15:35:09,364 INFO [atlassian.jira.util.BugzillaImportBean] Importing User: [email protected] 15:35:09,580 INFO [atlassian.jira.util.BugzillaImportBean] 144 issues imported from Bugzilla.2004-02-27 15:35:09,581 INFO [atlassian.jira.util.BugzillaImportBean]

Importing Votes2004-02-27 15:35:09,747 INFO [atlassian.jira.util.BugzillaImportBean] 0 votes imported from Bugzilla.2004-02-27 15:35:09,748 INFO [atlassian.jira.util.BugzillaImportBean] Reindexing (this may take a while)...2004-02-27 15:35:11,282 WARN [jira.issue.index.AbstractDocument] Unable to index field 'created' from ANT-4with value: 0002-11-30 00:00:00.02004-02-27 15:35:29,170 INFO [atlassian.jira.util.BugzillaImportBean]Import SUCCESS and took: 79142 ms.

It does not matter if your browser window times out — the import will continue regardless.

11.Once completed, you will see the 'Import SUCCESS' message, either in the logs (as above) or onthe subsequent page:

Final Bugzilla importer screen

Congratulations, you have successfully imported your Bugzilla projects into JIRA!

If you have any questions or encounter any problems, please contact Atlassian.

4.18.1.2. Importing only new bugs (repeated imports)

It is possible to re-import a Bugzilla project, and have JIRA import only 'new' bugs not previouslyimported. This allows for a transition period in which the imported JIRA project can be trialled, butbugs still logged in Bugzilla need not be lost.

To import only new bugs, click the 'Import only new issues' checkbox in the importer.

4.18.1.3. Searching by Bugzilla ID

The Bugzilla importer creates a 'Bugzilla ID' custom field for imported issues, linking back to theoriginal Bugzilla bug URL.

JIRA Documentation

Page 231Copyright © 2002-2005 Atlassian All rights reserved.

Page 232: Jira Manual

Bugzilla ID custom fieldIf you intend to use this, you will need to configure the URL to Bugzilla injira-application.properties. The custom field can also be made to display just the ID (unlinked) injira-application.properties. If you don't need this custom field, delete it or hide it.

The custom field is searchable, so you can search for JIRA issues by their old Bugzilla ID. Thereis also a portlet which lets you search by Bugzilla ID:

Bugzilla ID Search Portlet on Dashboard

4.18.1.4. Importer Source code

The Bugzilla importer source code is available here (BugzillaImportBean.java) — fixes andimprovements welcome.

4.18.2. Importing Data From Mantis

JIRA is able to import data from Mantis, an open-source PHP-based bug tracker. The Mantisimport is almost identical to the Bugzilla importer (just expecting a different database format), soplease refer to the Bugzilla documentation for a walkthrough.

In addition to the Bugzilla importer's features, the Mantis importer also:

1. Creates a custom field, "Mantis Link", containing a link to the old Mantis bug URL. Thisfield can be hidden when no longer useful.

2. Creates a custom field, "Mantis ID", containing the mantis bug ID (useful for searching)3. Creates and uses a custom "Not a bug" resolution type.4. Converts Mantis links (#1234) to JIRA links (TST-123) in text.

4.18.2.1. Importer Source code

The Mantis importer source code is available here (see also here) — fixes and improvementswelcome.

JIRA Documentation

Page 232Copyright © 2002-2005 Atlassian All rights reserved.

Page 233: Jira Manual

4.18.3. Importing Data From FogBugz

4.18.3.1. Overview

The FogBugz importer allows you to import your bugs from an existing FogBugz installation.Importing from a FogBugz file is a two step process. First, you will need to create a mapping file byrunning the FogBugz import wizard. As with the CSV importer, the mapping file is a plain textproperties file that you can also manually edit. To perform the import, enter the connection detailsand the location of your configuration file, and import away!

1. Running the FogBugz Import Wizard1. Configure Project2. Assign field mappings3. Map field values4. Issue Links5. Saving the file

2. Importing your FogBugz file

4.18.3.2. Import Configuration Wizard

The wizard allows you to choose projects, custom fields and issue links to import. Once this iscompleted, you can save the file on the server and use it in the import process. The FogBugzimporter is available from Administration -> Import & Export -> External System Import.

Import Configuration Wizard

4.18.3.3. Project Configuration

First step is to choose projects to be imported. Choose a valid project key for each project you wantto import and leave blank if you do not wish to import the project. In JIRA Enterprise Edition, youcan also choose a project category that the project should be created in. This will only apply if theproject key does not exist and a new project is created.

JIRA Documentation

Page 233Copyright © 2002-2005 Atlassian All rights reserved.

Page 234: Jira Manual

Project Configuration

4.18.3.4. Issue Field Mappings

The second step is to figure out which optional FogBugz fields you wish to import. Most of thefields in FogBugz are automatically mapped to appropriate JIRA fields. You can choose to mapthe fields ixBug (internal FogBugz issue id), sCustomerEmail (e-mail address of the issue ifcreated by e-mail) and sComputer (custom field) to any existing global JIRA custom field.

Issue Field mappings

Value Mappings

Value mappings are how values from your FogBugz importer can be "transformed" duringimport. The fields sPriority, sFullName, sComputer and sCategory can have their values mapped.The first screen allows you to choose which fields you would like to map values.

JIRA Documentation

Page 234Copyright © 2002-2005 Atlassian All rights reserved.

Page 235: Jira Manual

Choose field for Value mapppingOn the next screen, all unique values for each field you selected to be mapped have been displayed.You can now map any of these values to a new value. Leave the field blank if you wish to import thevalue as-is. If you want to clear a field, enter the keyword <<blank>>.

For sPriority and sCategory you will get a select list with the available values in JIRA. sFullNamerefers to the usernames that will be created in JIRA. If you don't specify any particular mappings, theuser name will be created from the first letter of the first name and the last name, lowercased.

JIRA Documentation

Page 235Copyright © 2002-2005 Atlassian All rights reserved.

Page 236: Jira Manual

Value mappping

Issue Links

FogBugz has two types of links, Duplicates and BugRelations. On this screen, you can map thelinks to existing JIRA link types. Leave as none to not import the links

Issue Links

Saving the configuration file

JIRA Documentation

Page 236Copyright © 2002-2005 Atlassian All rights reserved.

Page 237: Jira Manual

The final step of the Wizard is to save the file on your server. Please ensure you enter a valid path.You can also choose to continue on with the import without saving the file.

You can also see a preview of the mapping file that will be saved.

4.18.3.5. Importing the FogBugz

Once you have your configuration file, you can now import the FogBugz file into JIRA. The settingspage allows you fine control to what will be imported on each import run.

Once the import has begun you'll be able to follow live progress of the import, with the screenrefreshing at around every 10 seconds. You can change this value by updating the field at the bottomof the page. The importer also give you stats about what objects have been imported and timeelapsed so you can have an idea as approximately how long the import will take. You can alsochoose to Abort the import, which will cease importing after the current issue is done.

4.18.3.6. Import Notes

Below are some notes about how FogBugz importer work.

1. Attachments: JIRA will import all attachments stored in the FogBugz dB. Any e-mail issueswill be parsed for attachments and the e-mail text saved as a comment. The dates and userattaching the attachments will be retained.

2. Link rewriting: FogBugz allows for links to other issues to be automatically generated by usingthe format "bug issueId" or "case issue id". After import, any string matching this pattern will berewritten to their new JIRA key. For example, a comment "Please see case 100" may berewritten to "Please see IMP-100".

4.18.4. Importing Data From CSV

4.18.4.1. Overview

The CSV importer provides a powerful and flexible way to import data from an comma separatedfile, which is a format supported by most applications such as Microsoft Excel. Importing from aCSV file is a two step process. First, you will need to create a mapping file by running the CSVimport wizard. The mapping file is a plain text properties file that you can also manually edit thatwill map your CSV fields to fields in JIRA. To perform the import, simply enter the location of yourimport file and your configuration file, and you're on your way!

1. Preparing your CSV file2. Running the CSV Import Wizard

1. Configure Project2. Assign field mappings3. Map field values4. Miscellaneous information5. Saving the file

3. Importing your CSV file

4.18.4.2. Preparing your CSV file

The first thing you need to do is to ensure that your CSV is a valid CSV format. A good way tocheck is to import your file into a spreadsheet (e.g. Microsoft Excel, Open Office) and see if the datais as expected. Here is a good opportunity to do any massaging of data you may wish to do.

If you wish to import data from one column into multiple JIRA fields, you should duplicate thecolumn and rename it as something different.

JIRA Documentation

Page 237Copyright © 2002-2005 Atlassian All rights reserved.

Page 238: Jira Manual

If you have values that signify a blank value (e.g. <blank> or None), it's best if you simplyremove them in this step.

Valid file format

The CSV importer assumes a Microsoft Excel styled CSV file. Fields are separated by commas,and enclosed in quotes if they contain commas or quotes. Embedded quotes are doubled.

There are two requirements of the CSV beyond general well-formed'ness:

• The CSV file must contain a heading row. The CSV configuration wizard uses the CSVheader row extensively. The header values should not have any punctuation (beyond thecommas separating records) such as apostrophes or the importer may not work correctly.

• As a minimum, the CSV file must contain a column for Summary data.

You can also have multi-lined CSV. So this below is a valid file with a single record:

Summary,Description,StatusLogin fails,"This is ona new line",Open

Importing Comments from CSV

If a row contains more columns than there are header columns, then the excess columns will beadded as comments (though see JRA-7672.

4.18.4.3. Import Configuration Wizard

The next step of the import process is to run the import configuration wizard to determine howthe CSV data can be mapped to JIRA fields. The CSV importer is available fromAdministration -> Import & Export -> External System Import.

You can also specify the delimiter your CSV file used. Leave the field blank if you wish to usethe (default) comma delimiter. Please note that the delimiter is only one character long.

Import Configuration Wizard

Project Configuration

The first step is to choose which project the issues will be imported into. You can import into anew project or an existing project. Note that if you are creating a new project, no validations areperformed at this time - it can only fail at import time. Further, if certain project details match anexisting project (like name and key), then the issues will be imported into an existing project.

If you want to import into multiple projects, you must map project information from the CSV fileitself. That means that all rows must have the project information in them.

JIRA Documentation

Page 238Copyright © 2002-2005 Atlassian All rights reserved.

Page 239: Jira Manual

The recommended import method is a single project per CSV file imported into an existing project.

Project Configuration

Issue Field Mappings

The second step is to figure out which CSV fields you want to import. The screen shows all thecolumns that are found in your CSV file and a sample data row. On this screen you can map eachcolumn of your CSV file to system fields in JIRA or leave as None to not import. You can optionallycreate new custom fields on the fly or import into an existing custom field.

Issue Field mappings

Note:As no validations are performed on field mappings until data import occurs, please try to ensure that your data is correct and valid.

JIRA Documentation

Page 239Copyright © 2002-2005 Atlassian All rights reserved.

Page 240: Jira Manual

System Fields

You can select multiple fields to be combined into version and component fields. For example,you can import from "Raised Version" and "Found in Version" into "Affects Versions" field. ForVersions and Components, the importer will detect if the version exists in JIRA for the project .If it doesn't then it will automatically created.

User fields (assignee & reporter) are assumed to be in a "FirstName LastName" format. Newusers will be created with the username as "FirstNameLastName"; spaces apostrophes andbrackets are stripped out. If the name only the has one word, that one word will be used as theusername.

In most cases when importing system fields values like priority, issue type, status and resolutionyou will need to map the field values. The mapping needs to be done even if the imported CSVfile has the values set to "valid" names, e.g. issue type set to "Bug" or "New Feature". The onlyway to get around having to map the values is to change the CSV file such that it contains theexact ids of JIRA's priorities, issue types, statuses and resolutions instead of their names. As thisis rather annoying, due to the fact that one needs to determine the correct ids and then update thewhole CSV file, it is easier to map the values during the import.

Custom Fields and the importer

You can also map a column to an existing custom field or create a new custom field on the fly.Currently you can only create certain custom fields on the fly. All custom fields created this waywill be globally scoped. Moreover, if the name matches an existing custom field, that existingcustom field will be used instead. If you are worried about how this works exactly, werecommend that you create your custom fields first before importing them.

Creating custom fields on the flyIf you map to a select list custom field, all unique values will be created as options at importtime. If you map to a multiple select field, it's values should be separated by a comma. If the fieldvalues have commas in them, the commas should be escaped with a backslash. Thus the field:

"Wally\, I,Wally\, II"

would be translated into one field with multiple values:

• Wally I• Wally II

Once again, no data validations are done at configuration time, so you should ensure that the datayou are trying to import is of a compatible type.

Map Field Value

You may wish to map certain values in your CSV file to a different value. For example, you've

JIRA Documentation

Page 240Copyright © 2002-2005 Atlassian All rights reserved.

Page 241: Jira Manual

mapped field "Severity" to JIRA's "Priority" field. JIRA expects the ID of priorities that exist inJIRA. Thus for this field, you'll need to check the Map field value check box. This will affect thenext screen that you'll come to.

Value Mappings

Value mappings are how values from your CSV importer can be "translated" to match that valuesexpected by JIRA. This is usually required for fields like issue type, resolutions, priorities andstatuses, but can equally be applicable for other fields. On this screen, all unique values for eachfield you selected to be mapped have been displayed. You can now map any of these values to theirvalues in JIRA. Leave the field blank if you wish to import the value as-is. If you want to clear afield, enter the keyword <<blank>>.

On the Field Mappings screen you will notice that each field has a checkbox under the heading Mapvalues. If you check these boxes you will be able to map the values of these fields when youprogress to the next page.

Value mapppingFor fields mapping to resolution, priority and issue type, you will get a select list with the availablevalues in JIRA. In addition you can quickly create values that do not exist in JIRA by clicking thegreen plus symbols. These will become issue constants that you can change at a later time.

For fields mapping to status, you will get the select list with JIRA's available values, but no plussymbol for creating new status values.

For these fields, there are two special options in the select list in addition to JIRA's available values,Import as blank and No mapping. Import as blank causes the JIRA value to be blank for that field.No mapping attempts to import the value in the CSV file as-is.

Note:Using No mapping for a field value will result in a failed import if the value is not valid for that JIRA field.

For fields mapping to status and issue type, default values are used when the blank option isselected.

Miscellaneous Information

You will be asked to enter some extra information on this screen such as:

JIRA Documentation

Page 241Copyright © 2002-2005 Atlassian All rights reserved.

Page 242: Jira Manual

1. The domain name of the Users that will be created in the system2. If you are importing date fields, you will also be asked to define the date format that is used

in your CSV file. Don't confuse this with the date format in JIRA. All date fields will beinterpreted using the format you supply.

Miscellaneous information

Saving the Configuration File

So you can import more CSV files later without going through the Configuration Wizard again,in the final step of the Wizard you can save the file on your server. Please ensure you enter avalid path. You can also choose to continue on with the import without saving the configurationin a file.

You can also see a preview of the mapping file that will be saved.

Saving the file

4.18.4.4. Importing the CSV

Once you have your configuration file, you can then import the CSV file into JIRA. The settingspage allows you fine control over what will be imported on each import run.

Once the import has begun you'll be able to follow the progress of the import, with the screenrefreshing around every 10 seconds. You can change this rate by updating the field at the bottomof the page. The importer also give you stats about what objects have been imported and timeelapsed so you can have an idea as approximately how long the import will take. You can alsochoose to Abort the import, which will cease importing after the current issue is done.

JIRA Documentation

Page 242Copyright © 2002-2005 Atlassian All rights reserved.

Page 243: Jira Manual

Import completed

4.18.4.5. CSV Limitations

The CSV Importer doesn't import all the objects available in JIRA at present. You can find theselimitations at issue JRA-5774.

5. Usage Guides

5.1. Configuring the Dashboard

The Dashboard is the first page you see when you sign into JIRA. It can be configured to displaymany different types of information, depending on your areas of interest. JIRA comespre-configured with a set of standard dashboard portlets. Portlets are the information boxes on theDashboard. Please note that it is possible to develop custom portlets and plug them into JIRA usingits flexible plugin system.

JIRA Documentation

Page 243Copyright © 2002-2005 Atlassian All rights reserved.

Page 244: Jira Manual

The portlets on a dashboard page can be re-ordered, switched between the left and right columns,additional portlets can be added, and some portlets can be configured.

Since JIRA 3.0, the Professional and Enterprise editions support multi-page dashboards. Eachdashboard page is composed of several portlets. This powerful feature allows users to neatlyorganise related information by context. Please note that the default dashboard is limited to onlyone page.

Note:You can return to the dashboard from any page in JIRA by clicking the "Home" link which appears on JIRA's navigation bar.

5.1.1. Steps to configure the dashboard

If you have not previously configured your dashboard, you are using the default dashboard whichis configured by JIRA administrators. Every user in JIRA can have a personal dashboard whichthey can configure as they like.

In JIRA 3 there are two ways to configure your dashboard:

1. Using the configuration interface. The interface only shows the name of the portlets and theirposition on a dashboard page. You can use the configuration interface to quickly moveportlets around, add and remove portlets or reconfigure them.

2. Directly from the dashboard. This way you can see exactly how the dashboard page lookslike in the current configuration, as the dashboard is completely redrawn with every change.The down side of configuring the dashboard this way, is that if you have configured portletswhich take time to load, waiting for the dashboard to render with every change can get a littleannoying.

Note:This method is only available after the dashboard has been setup for the first time. Please use the first method of configuring thedashboard if your dashboard has not been previously configured.

5.1.1.1. Using configuration interface

1. Login as a user. The dashboard configuration is user specific.2. On the top right of the Dashboard, click on the link labelled "Manage Portal".3. If you don't currently have a customised dashboard, you will be shown a confirmation page.

Click on "Configure Dashboard".4. If you are using the Standard edition of JIRA you will be brought to the "Configure

Dashboard" page.

JIRA Documentation

Page 244Copyright © 2002-2005 Atlassian All rights reserved.

Page 245: Jira Manual

Dashboard configuration pageIf you are using the Professional or the Enterprise edition of JIRA you will be brought to the"Manage Portal" page.

Portal configuration pageWe will discuss this page in a later section, please click the "Full Configure" link next to the"Dashboard" page in the presented list to proceed to the "Configure Dashboard" page.

5. The "Configure Dashboard" page consists of two selectable areas listing the portlets. The portletscan be configured as follows:Move a portlet up Select the portlet, and click the "^" closest to

select area that contains the portlet.

Move a portlet down Select the portlet, and click the "v" closest toselect area that contains the portlet.

Move a portlet left Select the portlet in the right hand column,and click the "<" button.

Move a portlet right Select the portlet in the left hand column,and click the ">" button.

Configure a portlet Select the portlet, and press the "Edit"button.

JIRA Documentation

Page 245Copyright © 2002-2005 Atlassian All rights reserved.

Page 246: Jira Manual

Delete a portlet Select the portlet and press the "Delete"button.

5.1.1.2. In-line Editing

If you have setup a personal dashboard (i.e. are not using the default dashboard) you canconfigure it without leaving the dashboard page. Simply click the "ON" link next to the"Configure" title in the top-right corner of your dashboard. Each portlet on the dashboard will behighlighted and given a "control" bar with icons that can be used to reorganise the portlets.

In-line Edit screenshotPlease use the left or right icons on a portlet's control bar to move the portlet between columns orthe up and down icons to move the portlet up or down within the same column. The curly up anddown arrow icons move the portlet to the first or last position in its column. The trash iconremoved the portlet from the dashboard page. The wrench icon brings up the "Edit Portlet" pagethat can be used to edit portlet's parameters. The wrench icon is only available for portlets thathave one more customisable parameters.

The "Add new portlet" link in the top-right corner of the dashboard can be used to add a portletto the dashboard page.

5.1.2. How to add a portlet

1. If you are using the dashboard configuration interface to configure a dashboard page press the"Add" button on the "Configure Dashboard" screen. If you are editing a dashboard pageinline, press the "Add new portlet" link in the top-right corner of the dashboard. This pageshows you a preview of the available portlets and how much of each already exist on thecurrent dashboard page.

JIRA Documentation

Page 246Copyright © 2002-2005 Atlassian All rights reserved.

Page 247: Jira Manual

Add Portlet page2. Select the radio button of the one you want, and press the "Add" button.3. If the portlet you have selected requires configuration, you will be presented with the portlet's

configuration page. Configure appropriately and press "Save".4. You will be brought back to the page you have started from: either the "Configure Dashboard"

page or the dashboard itself.

5.1.3. Statistic Portlets

There are several portlets in JIRA which show useful statistical information. These portlets include:

1. Project statistics - shows statistics about all issues within a chosen project grouped by a certain

JIRA Documentation

Page 247Copyright © 2002-2005 Atlassian All rights reserved.

Page 248: Jira Manual

issue field (e.g. assignee, reporter, priority).

Statistic Portlet displaying issues by priority2. Filter statistics - very similar to the portlet described above, but uses a saved filter as a

source of issues rather than all issue's from a chosen project.3. Two Dimensional Filter Statistics - uses a filter as a source of issues and groups the results

by two issue fields presenting a matrix with one issue field on the X-axis and another on theY-axis.

Statistic Portlet displaying issues by priority and project

5.1.4. Multiple Dashboard Pages

The Professional and Enterprise editions of JIRA allow users to configure more than onedashboard page. Each dashboard page can be configured independently, allowing users twoorganise information by context.

Each dashboard page appears as a separate "tab" on the dashboard. You can view a dashboardpage by simply clicking its name in the tab list.

JIRA Documentation

Page 248Copyright © 2002-2005 Atlassian All rights reserved.

Page 249: Jira Manual

Dashboard Tabs screenshotTo add a new dashboard page to the dashboard please follow these steps:

1. Login as a user. The dashboard configuration is user specific.2. On the top right of the Dashboard, click on the link labelled "Manage Portal".3. If you don't currently have a customised dashboard, you will be shown a confirmation page.

Click on "Configure Dashboard".4. If you are using the Professional or the Enterprise edition of JIRA you will be brought to the

"Manage Portal" page, which lists all currently configured dashboard pages. The "ManagePortal" page also has a "Add New Portal Page" form at the bottom of the screen.

Portal configuration page5. Provide a name for the new dashboard page and optionally enter a short description. You can

also choose an existing page as a starting point for the new page. This means that theconfiguration of the existing page will be duplicated for the newly created page. Alternatively, ifyou would like to create a portal page with no portlets, leave the "Blank portal page" optionselected.

6. Click the "Add" button and the new portal page should appear at the bottom of the existing portalpages list.

The "Manage Portal" page also allows to reorder the dashboard pages and delete them. You can alsoclick the "Full configure" link next to each dashboard page in the list to proceed to the dashboardconfiguration interface to organise the portlets on that page.

JIRA Documentation

Page 249Copyright © 2002-2005 Atlassian All rights reserved.

Page 250: Jira Manual

5.1.5. Configure the default dashboard

The default dashboard is the one that all JIRA users see the first time they log on. The users whohave not configured a personal dashboard also see the default.

JIRA allows Administrators to configure the default dashboard (this is different to configuringyour own personal dashboard). To edit the default, go to the Administration section and click onthe "Default Dashboard" link under "Global Settings" on the left pane. Configure the dashboardas per the instructions above.

Note:All changes made to the default dashboard will also change the dashboards of all users currently using the default. However, portletsthat users do not have permissions to see will remain hidden to them. For example, the admin portlet, although it may exist in thedefault dashboard configuration, will not be visible to non-admin users.

Note:JIRA's default dashboard is limited to only one dashboard page.

5.2. Keyboard Shortcuts

Keyboard shortcuts provide an quick and easy way of navigating though the JIRA interfacewithout having to take you fingers off the keyboard.

5.2.1. Activating Shortcuts

Shortcuts are activated by simultaneously pressing the modifier key and the specific access key.For example, pressing 'Alt + A' on Firefox will open the 'Administration' page.

The access key is an identifying key for a particular page element. The access key is commonlyidentified by the underlined character on the element label. From the diagram below you can seethe link 'Create New Issue'. So in this example it is possible to identify that 'C' is the appropriateaccess key for selecting that link.

5.2.2. Available Shortcuts

The shortcuts that are currently available to use and their default access keys are:

Operation Default Access Key Description

Home H Redirects you to yourDashboard.

Find Issues F Redirects you to the IssueNavigator.

Create New Issue C Redirects you to Create IssuePage.

Administration A Redirects you to theAdministration Page

Quick Search Q Directs your cursor to the QuickSearch Text Field in the topright hand corner.

Submit S Submits any form.

Cancel `(backquote) Cancels any form.

JIRA Documentation

Page 250Copyright © 2002-2005 Atlassian All rights reserved.

Page 251: Jira Manual

Remember Me R Automatically checks the"Remember me" check box onthe Login page.

Comment M On the View Issue screen,opens and focuses on thecomment box.

Edit E On the View Issue screen,Edits the issue (if you haveappropriate permissions).

5.2.3. Modifier Keys

The modifier key will differ with each operating system and browser. For example, when runningFirefox on Mac OSX you will need to type 'Ctrl+S' to submit a form, while on Windows you willneed to type 'Alt+S'. The following table identifies the modifier keys for the various configurations

Operation System Modifier Key

Mac OSX Ctrl

Other Alt

Table 1: Firefox/MozillaOperation System Modifier Key

Mac OSX Ctrl

Other Alt

Table 2: Internet Explorer

Note:On Internet Explorer links will only be highlighted by shortcut keys, you will need to press enter to proceed. Buttons however are selectedthrough the shortcut.

Operation System Modifier Key

All Ctrl

Table 3: SafariOperation System Modifier Key

All Shift + Esc

Table 4: Opera

Note:On Opera buttons will only be highlighted by shortcut keys, you will need to press enter to proceed.

5.3. Screenshot Applet

The screenshot applet provides a quick and easy way to attach screenshots to Jira issues.

Note:The screenshot applet is only available under windows and mac clients at the moment. Because of some pre jdk 1.5 issues we do not yetsupport using the screenshot applet under linux.

5.3.1. Activating the Screenshot Applet

JIRA Documentation

Page 251Copyright © 2002-2005 Atlassian All rights reserved.

Page 252: Jira Manual

In order to use the screenshot applet your instance of Jira must be configured to allowattachments. This setting can be checked in the Administrator section under the Global Settingsmenu on the Attachments link. On this page the 'Allow Attachments' option should state that it ison. Only a Jira administrator can configure this option, please see the docs for more information.

A user must have the 'Create Attachments' permission before they will see the option to launchthe screenshot applet. Only a Jira administrator can manipulate this permission, please see thedocs for more information.

5.3.2. Using the Screenshot Applet

When viewing an issue if the above requirements have all been met the user will be presentedwith an option on the left hand side of the screen to 'Attach screenshot to this issue'.

Screen shot of JIRA screenshot applet launch linkClicking this link will launch the screenshot applet in a new browser window. If this is the firsttime the applet has been launched you will be presented with a dialog box asking you whetheryou want to load the applet or not, choose the 'yes' option to use the applet.

JIRA Documentation

Page 252Copyright © 2002-2005 Atlassian All rights reserved.

Page 253: Jira Manual

Screen shot of JIRA screenshot applet dialog boxThe applet has three operations that you can perform; 'Paste', 'Attach', and 'Cancel'. The way that itworks is that when you click on the 'Paste' button the applet will place any image that currentlyresides on your operating systems clipboard (see section below on simple windows and mac OSXexamples) into the top area above the 'Paste' button. Once you have placed an image into the appletyou will have the option to 'Attach' the image to the Jira issue. Pressing the 'Attach' button before animage has been entered into the applet will have no effect. At any time you may click the 'Cancel'button to close the applet without performing any operations.

Screen shot of JIRA screenshot appletWhen attaching a screenshot using the applet you have three options that you can specify:

• The filename for the screenshot you are attaching. By default this is set to screenshot-1, but this

JIRA Documentation

Page 253Copyright © 2002-2005 Atlassian All rights reserved.

Page 254: Jira Manual

can be set to any valid filename. A valid filename will not contain any of these characters: '\','/','\"', '%', ':', '$', '?', '*'. If a filename is entered with an invalid character, the applet willdisplay an error message when the 'Attach' button is clicked and will not allow the operationto proceed until the filename specified is valid.

• An optional comment can be specified in the applet. If specified then as well as adding thescreenshot as an attachment the provided comment will be added to the Jira issue.

• If providing a comment then you can also specify the security level for the comment. Thecomment can be visible by all or it can be constrained so that it is only visible by a specifiedgroup.

Once the applet has performed a successful 'Attach' operation the applet window will be closedand you will be returned to the original window which is displaying the Jira issue you originallylaunched the applet from. To attach another screenshot you just follow the same procedure overagain starting with clicking the 'Attach screenshot to this issue' link.

5.3.3. Capturing Screenshots

The method for capturing screenshots will differ on each operating system. This doc will give asimple example on windows and on mac OSX.

5.3.3.1. Capturing a screenshot on windows

To place a screenshot into the system clipboard on windows you can simply press theALT-PRINTSCREEN (to capture your currently selected window) orCTRL-ALT-PRINTSCREEN (to capture the whole desktop) keyboard combination. You canalso go into you favorite imaging application, open an image, and select the copy option from themenu.

5.3.3.2. Capturing a screenshot on mac OSX

To place a screenshot into the system clipboard on mac OSX you can simply press theCTRL-APPLE-SHIFT-4 (to capture your currently selected window) or CTRL-APPLE-SHIFT-3(to capture the whole desktop) keyboard combination. You can also go into you favorite imagingapplication, open an image, and select the copy option from the menu.

5.4. User Management

5.4.1. Automatic Group Membership

In order to automatically add a new user to a group, grant the group the global permission 'JIRAUsers'.

This can be achieved by navigating to the administration section and selecting the 'GlobalPermissions' section. The required group can then be granted the permission.

JIRA Documentation

Page 254Copyright © 2002-2005 Atlassian All rights reserved.

Page 255: Jira Manual

Global permissions screen

5.5. Time Tracking

Once time tracking is turned on it allows you to enter an estimate for how long you think the issue isgoing to take to resolve.In each issue three times are stored:

• Original Estimate• Remaining Estimate• Time spent

These times are created and updated at three different times.

5.5.1. Issue creation

When creating a new issue you will be asked to specify an original time estimate. Once work hasstarted on the issue (ie. a work log entry has been made) you will not be able to modify this value.

Setting time tracking when creating an issue

5.5.2. Issue edit

The time tracking section of the edit issue page changes if work has started on the issue.If work has not begun on the issue you will see the original time estimate.

Setting time tracking on an existing issueYou may edit this value up until work is logged against the issue.When work has started on the issue, the following screen will be displayed.

Setting time tracking on an existing issueAs shown above, you cannot modify the original time estimate.

JIRA Documentation

Page 255Copyright © 2002-2005 Atlassian All rights reserved.

Page 256: Jira Manual

There is an additional time field that is an estimate of how much time remains until this issue willbe resolved.

5.5.3. Log Work

You may not be able to log work if you do not have the correct permissions. If this is the case amessage stating this fact will be displayed on the view issue page. Contact your JIRAadministrator to be given the relevant permission.

No permissions to log workIf you have permission you can log work by clicking on the link at the bottom left of the viewissue page.

Navigating to the log work pageThis then displays a screen which allows you to specify the amount of time you have spent on theissue.

Logging workThe page allows you to log time and make a comment on the work you have done (You canrestrict who sees the comment by selecting a user group). It also allows you to specify how muchtime you think is remaining on this task or let the system automatically calculate it.

Once time tracking information is being recorded, various reports (measuring progress, developerworkload and version workload) based on this information become available.

5.6. JIRA Workflow

JIRA Documentation

Page 256Copyright © 2002-2005 Atlassian All rights reserved.

Page 257: Jira Manual

A "workflow" is the set of stages and stage transitions that an issue goes through in its lifecycle.Issue workflows typically represent business processes and development cycles. This section willtake you through the process of creating or customizing a workflow, explaining the concepts alongthe way. Once you have a workflow defined, see the Activating Workflow section for how to use it.

All editions of JIRA are shipped with one default workflow. JIRA Enterprise and Professionaleditions allow the workflow to be customised using JIRA's workflow editor. In JIRA Enterprise, onecan have multiple workflows in the system, associated with a particular project or project-issue typecombination. JIRA Professional supports only one active workflow. That is, in JIRA Professionalany number of workflows can be defined, but all issues in the system must use only one of thedefined workflows at any point in time.

5.6.1. Steps and Transitions

Workflows are composed of steps and transitions.

A workflow step represents a stage in a workflow for an issue. An issue can exist in only one step atany point in time. Each workflow must have at least one step. This step is called the "initial step"and an issue is placed into this step when it is created. Each workflow step has a "linked" status.When an issue is moved into a certain step, its "status" field is updated to the value of the step's"linked" status.

Each workflow step can have transitions which allow an issue to move from the step to anotherstep. For an issue to be able to progress from one step to another, a transition must exist that linksthese two steps. A transition is a unidirectional link between two workflow steps. This means that ifan issue needs to move back and forth between two steps, two transitions need to be created.

The available workflow transitions for an issue are listed on the issue's View Issue page:

Available Workflow Transitions screenA user is able to execute a workflow transition (progress the issue through workflow) by clickingone of the available links.

5.6.2. Creating workflow

To create a new workflow, navigate to the View Workflows page by following these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

JIRA Documentation

Page 257Copyright © 2002-2005 Atlassian All rights reserved.

Page 258: Jira Manual

Link to Administration section

Link to Administration section

3. Click the Global Settings sub-menu on the left hand side if it is not open already, and chooseWorkflows from the list.

The View Workflows page lists all the currently defined workflows in the system, and allows theadministrator to manage these workflows.

View Workflows page

Note:This screenshot shows how the page would appear in the Enterprise edition of JIRA. JIRA Professional does not support WorkflowSchemes and would therefore have the "Schemes" column missing from the workflows list.

There are several ways of creating a new workflow in JIRA:

1. Creating a "blank" workflow by using the Add New Workflow form on the View Workflowspage.

2. Copying an existing workflow by clicking the "Copy" link next to an existing workflow.3. Manually creating a workflow definition in XML and importing it into JIRA.

Once you have created a new workflow you might want to edit it (especially if you have createda blank workflow) or activate it.

JIRA Documentation

Page 258Copyright © 2002-2005 Atlassian All rights reserved.

Page 259: Jira Manual

5.6.3. Editing workflows

To edit a workflow, go to the View Workflows page, and click the "Steps" link next to the workflowyou wish to edit. You will be taken to the Workflow Steps page:

Workflows Steps pageThe Workflow Steps page allows one to create, edit and delete workflow steps and add and deleteworkflow transitions.

Note:Only inactive workflows can be edited. If an active workflow needs to be modified, copy an active workflow, modify the copy and thenactivate it.

5.6.3.1. Workflow steps

To add a new workflow step, enter a name for the step into the Add New Step form on the bottom ofthe Workflow Steps page, select a linked status and click the "Add" button. If all existing statuses arebeing used in the workflow which is being edited a new status will need to be created.

Note:A workflow step cannot be deleted if it is the destination of a transition.

It is possible to get an overview of the step by navigating to the View Workflow Step page, byclicking the step's name on the Workflow Steps page:

JIRA Documentation

Page 259Copyright © 2002-2005 Atlassian All rights reserved.

Page 260: Jira Manual

Viewing a workflow stepThe View Workflow Step page lists all the operations that can be taken on the step, and shows allthe incoming and outgoing transitions. Each of the transition names can be clicked to view thedetails of the transition.

5.6.3.2. Workflow transitions

To allow an issue to progress from one step to another, a workflow transition must be created. Tocreate a new workflow transition click the "Add Transition" link next to originating step of thenew transition. This action should bring up the Add Workflow Transition page:

Add Transition pageHere you can specify:

• Transition Name - the name of the transition which will appear on the View Issue page as anoperation that can be taken on the issue.

• Description - a short text describing the purpose of the transition.• Destination Step - the step that the issue will be moved into when this transition is executed.• Transition View - the screen of fields that will be shown to the user to ask for input before the

transition is executed. The options for this value:1. No view for transition - no page will be shown to the user and the transition will occur

instantly.2. Select an existing screen - choose a screen that will be shown before the transition is

executed. It is possible to select an existing screen. Please see this document for moreinformation on screens.

5.6.3.3. Customising a workflow transition

In the workflow, it is possible to:

JIRA Documentation

Page 260Copyright © 2002-2005 Atlassian All rights reserved.

Page 261: Jira Manual

• Carry out arbitrary processing when an issue progresses from one step to another. For example,update some fields on an issue and save it to the database. This is done with Post functions.

• Limit who can perform a transition (who sees the transition link). This is done with Conditions.• Assuming the user can perform a transition (the Condition passes), check that all supplied input

parameters are valid, before they are passed to the Post functions. For example, check that thevalue for a certain field was entered. This is achieved with Validators.

Post functions, Conditions and Validators can be configured in the View Workflow Transition page,shown below.

View Workflow Transition screen

Conditions

Conditions restrict the execution of a workflow transition until certain criteria is met. If the conditionfails, the user won't see the transition link on the View Issue page.

JIRA ships with a few commonly used conditions:

Permission Condition Condition to allow only users with a certainpermission to execute a transition.

Only Assignee Condition Condition to allow only the assignee to executea transition.

User Is In Group Condition to allow only users in a given group toexecute a transition.

Sub-Task Blocking Condition Condition to block parent issue transitiondepending on sub-task status.

It is possible to create your own and use them in JIRA's workflow editor via the plugin system. Seethe Workflow guide for details on how to implement your own conditions.

To add Conditions to a transition:

1. Go to the View Workflow Transition page2. Select the Conditions tab3. Click the "Add" link. A list with all the current conditions that JIRA knows about will be

presented.

JIRA Documentation

Page 261Copyright © 2002-2005 Atlassian All rights reserved.

Page 262: Jira Manual

4. Select a condition from the list and click the "Add" button. If a condition requires one ormore configuration parameters a Condition Configuration page will be presented, otherwisethe condition will be added to the transition.

Once a condition has been added to the transition it can be removed by clicking the "Delete" linknext to its description. If the transition has one or more configuration parameters, these can beedited by clicking the "Edit" link.

Validators

Validators ensure that the run-time parameters passed to the transition's Post functions forprocessing are valid. For example, a validator can be used to ensure that that the commententered by a user on the transition's view meets a certain criteria. If a validator "fails" the PostFunctions of the transition will not be executed and the issue will not progress to the destinationstep of the transition.

There is often confusion about the role of Conditions and Validators. Conditions are used todetermine whether a transition is "allowed" to be executed and hence cannot use input parametersthat are provided by the user on the transition's View, as if the condition "fails" the user will notbe allowed to start executing the transition and hence will never be presented the transition'sView.

Validators on the other hand have access to the input that has been gathered from the user on thetransition's View and thus can validate that input.

Similarly to Conditions, JIRA ships with a few sample Validators, but it is possible to developcustom validators and "plug" them into JIRA's workflow editor using JIRA's plugin system.

Adding a Validator to a workflow transition is very similar to adding a Condition

1. Go to the View Workflow Transition page2. Select the "Validators" tab3. Click the "Add" link. A list of available validators will be presented.4. Select a validator from the list and click the "Add" button.

Once a validator has been added to a transition it can be deleted by clicking the "Delete" link or,if it has any input parameters, edited by clicking the "Edit" link.

Post Functions

Post Functions carry out some processing immediately after a transition is executed (hence thename post-function), such as updating issue's fields, generating change history for an issue,adding a comment to an issue, generating an event that signals that an issue has been progressedthrough workflow.

There are certain post functions that cannot be edited, deleted or ordered, as they must beexecuted during every transition. These post functions are essential for JIRA's issue life cycle,and would compromise other functionality if not executed.

As with conditions and validators, JIRA ships with some post functions, but custom ones can beimplemented and plugged into the workflow editor via JIRA's plugin-in system. See theWorkflow guide for details on how to implement your own post functions.

Post functions can be added to a transition as follows:

1. Go to the View Workflow Transition page2. Select the "Post Functions" tab3. Click the "Add" link. A list of post-functions will be presented.4. Select a post-function from the list and click the "Add" button.

JIRA Documentation

Page 262Copyright © 2002-2005 Atlassian All rights reserved.

Page 263: Jira Manual

Once a post function has been added to a transition it can be deleted by clicking the "Delete" link or,if it has any configuration parameters, edited by clicking the "Edit" link.

Post Functions can also be reordered by clicking up or down arrows next to each post function in thelist. Please note, that the essential post functions cannot be reordered relative to each other, howeverit is possible to "insert" a post function between them.

5.6.3.4. Initial transitions

An initial transition is a transition that is executed when an issue is created. This transition "puts" anissue into the "initial" workflow step.

Each workflow must have one, and only one initial transition. The transition is created automaticallywhenever a new workflow is created (unless the workflow is imported from XML).

Sometimes it is useful to execute a piece of logic whenever an issue is created in a given workflow.This can easily be achieved by adding a post function to the workflow's initial transition. To edit theinitial transition, navigate to the workflow's "initial" step and click the workflow transition thatappears in green in the Workflow Browser.

5.6.3.5. Common Transitions

Those that are familiar with OSWorkflow, the workflow system that JIRA uses, are likely familiarwith Common Actions. Common Actions (or Common Transitions) are transitions that are definedonly once in the workflow, and then referenced from more than one workflow step. This means thatthe common transition can have more than one originating step. The advantage of commontransitions is that if a transition needs to be updated, this can be done in only one place and theupdate affects all originating steps of the transition.

JIRA's default workflow uses Common Transitions. JIRA's workflow editor, however, does notprovide the capability to create Common Transitions, but does provide support for editing them.Therefore it is still possible to edit a copy of JIRA's default workflow, if one is created.

5.6.4. Copying workflows between systems

Sometimes it is useful to create a workflow in a test system and then copy it into a productionsystem. The best way to achieve this is to export the workflow to XML from the test system byclicking the "XML" link next to the workflow in the list presented on the View Workflows page andsave the output into a file.

Then, import the file by clicking the "import workflow from XML" link and paste the contents of theworkflow file into the text area on the presented page.

Alternatively, you can copy the file to the machine running JIRA and then provide the full path tothe file rather than pasting its contents into the text area.

5.6.5. Active and Inactive workflows

Workflows in JIRA can be in one of the two states: Active and Inactive.

Inactive workflows are workflows that exist in the system but are not associated with any project or(in Enterprise) workflow scheme.

In the Professional edition of JIRA there is only one active workflow - the one that is used by allprojects.

In the Enterprise edition of JIRA, inactive workflows are those that have not been associated with

JIRA Documentation

Page 263Copyright © 2002-2005 Atlassian All rights reserved.

Page 264: Jira Manual

any Workflow Schemes, or have been associated with Workflow Schemes that are not being usedby any projects.

Active workflows are those that are being currently used.

Please note that only inactive workflows can be modified. If an active workflow needs to bemodified, please copy the workflow, modify the copy and then activate it.

5.6.6. Restricting Issue Updates

It is possible to restrict issues from being edited in particular workflow steps. For example, in thedefault JIRA workflow issues in the Closed status cannot be edited, even by users who have theEdit Issue permission. Note that issues that cannot be edited cannot be updated using Bulk Editeither.

To stop issues from being editable in a particular step, set the jira.issue.editableproperty of the step to false. To set the property click the View step's properties link on theView Workflow Step page of the Workflow Editor and add the property using the form on thebottom of the screen. Please note that the Workflow you are editing must be inactive, asotherwise it cannot be updated.

As the default JIRA workflow cannot be edited, if you would like to allow issues in the Closedstatus to be editable, you will need to copy the default workflow and remove thejira.issue.editable property. Then activate the workflow.

5.6.7. Workflow Resolution

JIRA models the issue life cycle by progressing an issue through a specified number of statuses.Each status represents a stage in the life cycle - usually denoted by a meaningful name such as:

• OPEN - issue open, work has yet to commence• IN PROGRESS - issue open, work has commenced• CLOSED - issue closed, work has been completed

However, in terms of actual open and closed issues, JIRA does not differentiate between thesestatuses. JIRA does not determine an issue to be open if it is associated with a status namedOPEN, equally so, an issue associated with a status named CLOSED is not determined to beclosed.

Within JIRA, the actual determination of whether an issue is open or closed is achieved throughthe use of the Resolution field. An issue is determined to be open if the associated Resolutionfield is not set. An issue is determined to be closed if the associated Resolution field is set.

Most of the portlet filters available in JIRA - e.g. All Open issues - work on the resolution settingto determine if an issue is opened or closed.

The workflow designer can enforce when a resolution should be set/unset through the workfloweditor. There are two methods available that allow this to be achieved:

• Workflow Transition Post Function• Workflow Transition View Screen

5.6.7.1. Workflow Transition Post Function

1. For a particular step in a workflow, create a transition that will move the issue to a closedstatus (e.g. Closed, Resolved, etc.).

2. Select the Add Comment And Assign or No View For Transition for the transition view.3. Editing the newly created transition, add a new post function Update Issue Field. Select

Resolution from the drop-down and specify the value 1.

JIRA Documentation

Page 264Copyright © 2002-2005 Atlassian All rights reserved.

Page 265: Jira Manual

4. Once completed, the post function list appears as follows:

Resolution Post FunctionIn order to create a transition that unsets the resolution - follow the same steps, but do not enter avalue for the resolution in the Update Issue Field screen. The post function list should now includethe statement:

The Resolution of the issue will be cleared.

Each time the workflow transition operation is selected - the resolution of the issue is automaticallyset or unset.

5.6.7.2. Workflow Transition View Screen

A transition view screen is the screen that will appear when the transition is executed. The screensare made available by creating a field screen. So for this example you can create a Resolution FieldScreen with the fields you want displayed added to the screen.

JIRA Documentation

Page 265Copyright © 2002-2005 Atlassian All rights reserved.

Page 266: Jira Manual

Resolution Transition

5.6.8. Workflow and Notifications

Each workflow transition has a Fire Issue Event post function that is responsible for firing aselected event every time the transition is performed. The event is used to send notifications andinvoke listeners.

When the transition is performed, JIRA will use the fired event to lookup the NotificationScheme associated with the issue's project, and send an e-mail notification to each nominatedparty for the event in the scheme. As noted above, the fired event is also propagated to allregistered listeners.

It is possible to select which event is fired by a Workflow Transition by editing the Fire IssueEvent post function and selecting one of the JIRA events. In your custom workflow you can usethe Generic Event which is not used in JIRA by default.

5.6.9. Technical Information

JIRA uses OSWorkflow, a flexible and customisable workflow engine. JIRA's workflow editorgenerates OSWorkflow XML definition files that are stored in JIRA's database. If you need totake advantage of some OSWorkflow feature that is not available in JIRA's workflow editor youcan define the workflow in XML and then import it into JIRA.

Note:JIRA's workflow editor should be able to display most of OSWorkflow definitions even if it does not support creating or editingthem. For example, conditional results of workflow transitions are displayed in the "Other" tab on the View Workflow Transitionpage. The "Other" tab is only visible if a transition has elements that the editor does not directly support.

Warning:JIRA's XML workflow definitions contain references to JIRA meta attributes. For example, the id of the linked JIRA status of eachworkflow step is stored as a "jira.status.id" meta attribute in the step's definition. Therefore, when manually creating workflows inXML please ensure that all referenced external entities exist before import the workflow into JIRA.

5.7. Activating Workflow

Assuming you have created or modified a workflow, describes how to 'activate' it by associatingit with a project and/or issue type.

The method of activating workflows depends on the edition of JIRA. The Standard edition onlysupports the default workflow which is always active. The Professional edition can only have oneactive workflow in the system. In the Enterprise edition workflows are organised into schemeswhich are then associated with projects.

5.7.1. Activating workflow in Professional Edition

To activate a workflow in JIRA Professional please follow the following steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

JIRA Documentation

Page 266Copyright © 2002-2005 Atlassian All rights reserved.

Page 267: Jira Manual

Link to Administration section

Link to Administration section

3. Open the Global Settings sub-menu on the left hand side if it is not open already, and chooseWorkflows from the list.

4. Click the "Activate" link next to the workflow that needs to be activated and go through theactivation wizard that will guide you through migrating all the existing issues to this workflow.

Activate Workflow in JIRA Professional screen

5.7.2. Activating workflows in Enterprise Edition

JIRA Enterprise supports multiple active workflows through Workflow Schemes.

5.7.2.1. Workflow Schemes

Workflow Schemes organise workflows on per issue type basis. The schemes are associated withprojects. Therefore, it is possible to use a different workflow for every project/issue typecombination.

Creating Workflow Scheme

To create a workflow scheme please follow the following steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 267Copyright © 2002-2005 Atlassian All rights reserved.

Page 268: Jira Manual

Link to Administration section

3. Open the "Schemes" sub-menu on the left hand side if it is not open already and select the"Workflow Schemes" link. This should bring up the Workflow Schemes page.

4. On the Workflow Schemes page click the "Add" link.5. Provide a name for the new workflow scheme and optionally a short description. Then click

the "Add" button. This will create the scheme and bring up the Edit Workflows page for thenewly created scheme. The Edit Workflows page allows one to associate existing workflowswith issue types.

6. To assign a workflow to an issue type with the new scheme click the "Assign" link. This willbring up the Add Workflow To Scheme page.

7. On the Add Workflow To Scheme page select an issue type that you would like to associatewith the workflow or select "All Unassigned Issue Types". The "All Unassigned Issue Types"is used to indicate which workflow will be used by issue types that do not have a specificassociation in this scheme.

8. Select the workflow to associate with the selected issue type and press the "add" button. Thiswill show the Edit Workflows page for the screen. If another association has to be madeplease go through the last 2 steps again.

9. Once a Workflow Scheme is fully defined it needs to be associated with one or more projectsso that the scheme's workflows are actually used by the system.

Associating a Workflow Scheme

To associate Workflow Scheme with a project please follow the following steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Open the "Projects" sub-menu on the left-hand side if it is not open already, and select the"Projects" link.

4. Select the project from the presented list by clicking on its name. This will bring up theAdminister Project page.

5. Click the "select scheme" link next to the "Workflow Scheme" property of the project.

JIRA Documentation

Page 268Copyright © 2002-2005 Atlassian All rights reserved.

Page 269: Jira Manual

Select Workflow Scheme6. Select a workflow scheme from the presented list and click the "Associate" button.7. Follow the wizard that will guide you through migrating all the project's issues to the scheme's

workflows.

Note:It is possible to associate a workflow scheme with more than one project.

Note:All projects that do not have an associated workflow scheme use JIRA's default workflow.

Editing Scheme's workflows

To edit a workflow scheme please follow these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Open the "Schemes" sub-menu on the left hand side if it is not open already and select the"Workflow Schemes" link. This should bring up the Workflow Schemes page.

4. Click the "Workflows" link next to the workflow scheme in the presented list. This will open theEdit Workflow page for the workflow scheme.

5. Click the "Assign" link to add a new entry to the scheme, or use the "Delete" link next to eachentry to remove it.

Note:It is not possible to edit workflow schemes that are associated with one or more projects. The best way to edit an active workflow schemeis to copy it, edit the copy and then associate all the required projects with it.

Disassociating a workflow scheme

JIRA Documentation

Page 269Copyright © 2002-2005 Atlassian All rights reserved.

Page 270: Jira Manual

All projects that do not have an associated workflow scheme use JIRA's default workflow. Todisassociate a workflow scheme from a project please follow these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

3. Open the "Projects" sub-menu on the left-hand side if it is not open already, and select the"Projects" link.

4. Select the project from the presented list by clicking on its name. This will bring up theAdminister Project page.

5. Click the "select scheme" link next to the "Workflow Scheme" property of the project.6. Select "None" from the presented list and click the "Associate" button.7. Follow the wizard that will guide you through migrating all of the project's issues to the

default workflow.

5.8. Clone Issue

Clone Issue allows a user to create a duplicate of an issue within the same project. The cloneissue is a replica of the original issue - containing the same information stored in the originalissue - e.g. summary, affects versions, components, etc. The clone issue summary can be prefixedwith a property file specified prefix. The clone issue can also be linked to the original issue usinga 'clone' link.

A clone issue is a separate entity from the original issue. Operations on the original issue have noaffect on the clone issue and vice versa. The only connection takes the form of the link (ifcreated) between the original and the clone issue.

A clone issue retains the following information:

• Summary - with optional prefix• Description• Assignee• Environment• Priority• Issue Type• Security• Reporter• Components• Affects Versions• Fix For Versions

JIRA Documentation

Page 270Copyright © 2002-2005 Atlassian All rights reserved.

Page 271: Jira Manual

Details such as time tracking and comments are not cloned.

5.8.1. Creating a Clone Issue

A clone issue can be created by selecting the 'Clone' link available in the issue operations menu. It ispossible to edit the clone issue summary before creating the clone issue.

5.8.2. Clone Issue Linking

The clone issue can be linked to the original issue when creating the clone issue using a pre-existinglink type.

JIRA queries the property file for the jira.clone.linktype.name setting.

• If this property is unset, JIRA will not create a link between the original and clone issues.• If this property is set, JIRA will use the pre-existing link type with the specified name as the link

type. If a link type with this name does not exist, a link is not created between the original andclone issues.

The link type with the name specified in the properties file should be created before creating cloneissues if linking is required.

5.8.3. Clone Issue Summary Prefix

The clone issue summary can be prefixed with a string - e.g. "Clone Issue - ". This string is specifiedin the properties file in the setting jira.clone.prefix and is prepended to the issue summary.

5.8.4. Cloning and Sub-Tasks

Sub-Tasks can be cloned in the same manner as other issue types.

If the original issue has associated sub-tasks, clone sub-tasks will also be created for the clone issue.However, the clone sub-task summaries will not include the property file specified prefix.

Note:It is not possible to clone an issue between projects - i.e. create a clone of an issue from one project and place it in a different project. Thisenhancement will be addressed in a future release.

Note:If the current user user does not have the 'Modify Reporter' permission, the clone issue will be created with the current user as thereporter.

5.9. Bulk Operations

Bulk Operations enables multiple operations to be performed on multiple issues at once. The bulkoperations are performed on the result set of a search. The following list details the available bulkoperations:

• Workflow TransitionThis operation allows multiple issues to be transitioned through workflow at once.

• DeleteThis operation allows multiple issues to be deleted at once.

• MoveThis operation allows multiple issues to be moved at once.

• EditThis operation allows multiple edit operations to be performed. The operations available are:

JIRA Documentation

Page 271Copyright © 2002-2005 Atlassian All rights reserved.

Page 272: Jira Manual

• Change Fix For Version• Change Affects Version• Change Component• Change Assignee• Change Priority• Change Custom Fields

Note:The bulk Edit operations available depend on the issues selected. If the issues selected are of a project without the specific elements,the respective operations are unavailable. If the issues are selected from multiple projects, the following operations are unavailable:- Change Fix For Version- Change Affects Version- Change Component- Change AssigneeThe 'Change Custom Fields' operation is available only if:- a global custom field exists- an issue type custom field exists and the issues are all of this specific issue type- a project custom field exists and the issues are all of the same project

Note:The bulk steps available in the Move operation will depend on the issues selected. More information on the Move operation isavailable here.

5.9.1. Steps to Perform Bulk Operations

1. From the Issue Navigator, perform a search with the required filters to produce an issue resultset.

2. The Bulk Change option in the Issue Navigator menu provides access to the bulk operations.If the result set spans a number of pages, it is possible to select all issues within the result setto be considered for the bulk operation. Alternatively, all issues on the current page can beselected for the bulk operation.

3. The next screen allows the selection of the issues that the bulk operation is to be performedon.

4. The next screen allows the bulk operation to be selected - Delete, Move or Edit.5. If the Delete operation is selected, the final step is confirmation of the delete operation on the

issues selected.6. If the Edit operation is selected, the next screen provides a list of the available edit operations

that can be performed on the issues selected. Some operations may be unavailable as notedabove.

7. After selecting the required Edit operation(s), the final step is confirmation of the editoperation(s) on the selected issues.

8. If the Move operation is selected, the next screens allow a target project (and issue type ifEnterprise edition) to be selected, with the ability to migrate workflow statuses and updaterequired fields as necessary. Further details on this operation can be found here.

5.9.2. Bulk Move

The Bulk Move operation allows multiple issues to be moved at once. It is possible to move aselection of issues to a new project with the ability to select a new issue type in certain cases. Theissues are selected through the Issue Navigator as discussed above.

The operation is completed as follows:

1. Select Projects and/or Issue Types2. Select Projects and/or Issue Types for Sub-Tasks3. Select status migration mappings for invalid statuses4. Select values for required fields and fields with invalid values

JIRA Documentation

Page 272Copyright © 2002-2005 Atlassian All rights reserved.

Page 273: Jira Manual

5. Confirm changes to be made and complete the operation

Note that steps 3 and 4 will occur once for each different target project and issue type combination.

5.9.2.1. Issue Selection

The bulk move operation can be performed on both standard issues and sub-task issues. Standardissues can be moved to another project and issue type, whereas a sub-task can only have its issuetype changed.

It is not possible to select both a sub-task and its parent to bulk move. This is so to adhere to theparent/sub-task relationship (i.e. the sub-task is always located in the same project as the parentissue). Any sub-tasks of selected parent issues which were also selected will be automaticallydiscarded from the move.

For example, you have issue B being a sub-task of issue A and you try to bulk move both A and Bsimultaneously. You will see a warning message (see below) and will be prompted to select a targetproject and issue type for issue A. If you select a new project for A, you will be prompted to movethe sub-task to a new issue type based on issue A's new project. If you don't change the project forissue A, the sub-task will not be required to be moved.

Bulk Move - Sub-tasks discarded

5.9.2.2. Select Projects and Issue Types

The first step of the bulk move wizard is to choose what projects and issue types you'll move yourissues to. The target project and issue type will determine whether extra steps will be required tomigrate statuses and fields.

This screen shows all selected issues grouped by their current project and issue type. You can eitherselect a new project and issue type for each one or choose to move all standard issues to a singleproject and issue type. To do this, select the check box with the label Use the above project andissue type pair for all other combinations and the selected project / issue type will apply. Note thatthis will not apply to sub-tasks since they cannot be moved to a standard issue type.

JIRA Documentation

Page 273Copyright © 2002-2005 Atlassian All rights reserved.

Page 274: Jira Manual

Bulk Move - Project/Issue Type Selection

5.9.2.3. Select Projects and Issue Types for Sub-Tasks

If you are moving issues with sub-tasks to another project, you'll also need to move the sub-tasksto the new project. On this screen you can elect to change the issue types of the sub-tasks beingmoved if you need to.

JIRA Documentation

Page 274Copyright © 2002-2005 Atlassian All rights reserved.

Page 275: Jira Manual

Bulk Move - Project/Issue Type Selection for Sub-Tasks

5.9.2.4. Workflow Status Mapping

As multiple workflows can be active simultaneously within Enterprise Edition, some statusesassociated with the collection of selected issues may not be valid in the target workflow. In this case,JIRA allows the user to specify a mapping from invalid statuses to those available in the the targetworkflow.

JIRA Documentation

Page 275Copyright © 2002-2005 Atlassian All rights reserved.

Page 276: Jira Manual

Bulk Move - Status MappingThis step of the wizard will only appear if you have invalid statuses. If you are moving issues todifferent projects and issue types at the same time, you will complete this step as well as the nextfor each of the different target project and issue type pairs. To help you easily keep track of yourprogress, the current context, that is the target project and issue type, is highlighted in theleft-hand, "progress" pane.

Bulk Move - Target list

5.9.2.5. Field Updates

In order to adhere to the field layout scheme associated with the target project and issue type, itmay be necessary to update/populate required fields. For example, if one of the selected issuesdoes not have a value for a required component and version fields, JIRA prompts the user toenter a suitable value.

JIRA Documentation

Page 276Copyright © 2002-2005 Atlassian All rights reserved.

Page 277: Jira Manual

Bulk Move - Field Update

5.9.2.6. Retain Original Values

It is possible to retain original field values that are valid in the target destination by checking theRetain checkbox associated with the field. For example, some issues may already include a validcustom field value - these values can be retained, while issues that require an update will adopt thevalue specified on the field update screen.

• Checked: the original value is retained where possible. The field will not be updated with thespecified new value.

• UnChecked: all fields will be updated with the specified new value.

5.9.2.7. Bulk Move Confirmation

When all move parameters - e.g. target project, status mappings and field updates - have beenspecified for all issues, the user is presented with a confirmation screen displaying all changes thatwill be made to the issues being moved. The following details are displayed:

• Issue Targets: the target project and issue type• Workflow: the target workflow and invalid status mappings• Updated Fields: new values for fields that require updating• Removed Fields: values to be removed in fields that are not valid in the target

The issues will only be moved once the Confirm button is clicked from the confirmation page. If theoperation is exited anytime before this step, no changes will be made to the issues.

Bulk Move - Confirmation

5.10. Project Release Notes

JIRA provides the functionality to create release notes for a specific version of a project. The releasenotes contain all issues within the specified project that are marked with a specific "Fix For" version.The release notes can also be generated in a number of formats (e.g. HTML, plain text, etc.) so as

JIRA Documentation

Page 277Copyright © 2002-2005 Atlassian All rights reserved.

Page 278: Jira Manual

they can be included in various documents.

At present, two example format templates are provided - HTML and Text - using Velocitytemplates. Further format templates can be created and added to the system.

5.10.1. Generating Release Notes

1. Select the Browse Projects option from the main menu2. Select the project from which you wish to create release notes.3. Select Release Notes.4. Select the required format of the release notes - HTML and plain text format templates are

provided.5. Select the required project version for which the release notes will be generated.6. Selecting the Create button will generate the release notes using the specified template in the

specified format. The release notes are displayed as HTML and also within a text area in theactual format selected - allowing the contents to be copied for inclusion in another document.

Note:It is also possible to create a default set of release notes using the HTML format template. By selecting the Roadmap option fromthe Reports menu, it is possible to create the HTML release notes for each un-released version by selecting the Release Notes linkafter each version title.

5.10.2. Adding New Format Templates

1. Create a Velocity template similar in content to that of the examples provided -releasenotes-text.vm and releasenotes-html.vm.

2. The title within the template should be modified along with the code within the text area. Theother sections of the template do not need to be modified.

3. Add the new format template to the list within the jira-application.propertiesfile. A corresponding entry must be made in both thejira.releasenotes.templatenames and thejira.releasenotes.templates lists. It is also necessary that the entries in both listsare in the same order.

4. The new format template is now available for selection as a release note format template.

5.11. Image Attachment Thumbnails

JIRA provides the functionality to create thumbnail images of image attachments within thesystem. This functionality allows an image to be previewed without having to download theoriginal image. When enabled, the thumbnail images are visible when viewing an issue. It is alsopossible to configure the issue navigator column layout to include a thumbnail images column.

5.11.1. Administration

The Administration -> Global Settings -> Attachments page allows the thumbnailfunctionality to be enabled/disabled. Attachment functionality must be enabled in order toenable thumbnails. The thumbnails are stored in the attachments directory with the originalattachments. The thumbnail images are denoted by "_thumb_" in the filename.

In order to re-configure the dimensions of the thumbnail images - please follow these steps:

1. Stop JIRA.2. Edit the following values found in the file jira-application.properties:

• jira.thumbnail.maxwidth• jira.thumbnail.maxheight

3. Delete all existing thumbnail images within the system - denoted by *_thumb_* in the

JIRA Documentation

Page 278Copyright © 2002-2005 Atlassian All rights reserved.

Page 279: Jira Manual

filename.4. Restart JIRA. All thumbnails are generated using the new dimensions.

Note:Thumbnails are enabled by default and set to a default width of 200 and default height of 200.

5.11.2. Supported Image Formats

At present, thumbnail images can be created from the following image formats:

• GIF• JPEG• PNG

All thumbnail images are stored in JPEG format in the attachments directory.

5.11.3. Viewing Thumbnails

Once thumbnail functionality is enabled, the thumbnails are immediately visible in the ImageAttachments section when viewing an issue with image attachments of the supported formats. Allother file attachments are displayed in the File Attachments section. It is also possible to configurethe issue navigator column layout to display the Images column.

Note:It is necessary to set the java system property -Djava.awt.headless=true to enable the thumbnail functionality.

Note:Thumbnail image generation requires the system to have X11 support. This web page details the minimum set of libraries needed to useJDK 1.4.2 under RedHat Linux 9.0.

5.12. Linking Issues

Issue Linking allows you to create an association between issues. For example:

• An issue may duplicate another• An issue may incorporate another (be a superset)• An issue's resolution may depend on another's

Within an issue, links to other issues look like this:

JIRA Documentation

Page 279Copyright © 2002-2005 Atlassian All rights reserved.

Page 280: Jira Manual

A real example of issue linking

5.12.1. Creating a link

Follow these steps to create a link between issues:

1. View the issue that you want to link.2. If Issue Linking is enabled - the 'Link' action is available under the Operations menu on the

left.

Selecting the 'Link' action, you can then select the type of link to be created and the issue(s)to be linked to.

Screen for linking an issue with another3. It is possible to link to single or multiple issues. Specify the full issue key (e.g. ABC-123) -

JIRA Documentation

Page 280Copyright © 2002-2005 Atlassian All rights reserved.

Page 281: Jira Manual

or a comma separated list of issue keys if linking multiple issues.

It is also possible to specify the link issues through the issue selector popup by clicking on the'select issue' link.

Note:If you have previously browsed an issue, you can find the issue number by clicking on the History link, at the top right of the page.

History link, for discovering previously visited issue IDs

5.12.2. Deleting a link

To delete a link:

1. Inside a linked issue, click on the 'Manage Links' link.2. In the following screen, click on the small icon in the bottom-right corner.

Deleting a link

5.12.3. Issue Selector

The issue selector popup allows you to select issues recently viewed or issues returned from a savedsearch filter.

• It is possible to select a single issue - or by clicking on the 'Select multiple issues' link,checkboxes appear enabling multiple issues to be selected.

• Once the multiple issues have been selected, click the 'Select issues' link to close the popup andadd the selected issues to the link issue list.

• By selecting a saved search filter in the select list available at the top right of the screen, thepopup will display the issues returned from the specified filter. It is possible to return to therecently viewed issues by clicking the 'Recent Issues' link.

JIRA Documentation

Page 281Copyright © 2002-2005 Atlassian All rights reserved.

Page 282: Jira Manual

Multiple Issue Selector

More detail on JIRA issue linking can be found in the Configuring Issue Linking section.

5.13. Voter and Watcher Lists

JIRA allows a user to cast a vote for a particular issue - "voicing" their preference for that issueto be resolved or completed. JIRA also allows a user to watch a particular issue, signing up fornotifications of any updates relating to that issue.

Building on these two features, JIRA provides the ability to view the voter and watcher lists foran issue. Further, a user with the correct permission can manage the watcher list.

The voter and watcher lists can be accessed by clicking the relevant link (beside thevoter/watcher total) in the issue summary when viewing an issue.

Mange Watcher List

5.13.1. Permissions

JIRA Documentation

Page 282Copyright © 2002-2005 Atlassian All rights reserved.

Page 283: Jira Manual

JIRA incorporates two permissions to govern who may view/edit the voter and watcher data:

• View Voters and Watchers - permits a user to view both the voter and watcher lists• Manage Watcher List - permits a user to view/edit the watcher list

These permissions can be granted through a Permission Scheme.

Note:It is possible to add multiple users to the watcher list through the multi-user picker.

Note:It is not possible to edit the voter list.

5.14. Issue Navigator Columns

The Issue Navigator is used within JIRA to find and filter issues. It is possible to select which issuefields will be displayed in issue navigator (for browser and printable views).

JIRA administrators can configure which columns appear in the issue navigator by default, for allusers that do not have their personal navigator columns configured. Each authenticated JIRA usercan override these defaults by configuring navigator columns to fit their needs.

5.14.1. Locating Navigator Column Configuration Screen

JIRA administrators can configure the default navigator columns by navigating to the"Administration section" and then choosing "Navigator Columns" from the "Issue Settings" menu onthe left.

JIRA users can configure their personal navigator columns by navigating to the "Profile" section andchoosing "Navigator Columns" from the menu on the left. Or simply choosing "Configure IssueNavigator" from the Issue Navigator itself (after doing a search). A JIRA administrator canconfigure their personal settings to override the defaults, as after all, they are a JIRA user too.

In Enterprise version it is possible to configure filter specific column order for saved filters.Navigate to the "Manage" tab of the Issue Navigator, and select "Add Column Order" link to add acolumn order to a saved filter, or the "Edit Column Order" link if the filter already has a savedcolumn order.

5.14.2. Configuring Navigator Columns

Only users that can see at least one issue in the JIRA installation are able to configure issuenavigator columns. To move a column left or right click on the left arrow or right arrow icon thatappear under the column's heading. To remove the column from the list click the bin icon whichappears under the column's heading. To add a column to the list select the issue field name from thedrop-down box titled "Add New Column" and click the "Add" button. The column should appear asthe right-most column in the list. It is then possible to position the column where desired using thearrow icons.

JIRA Documentation

Page 283Copyright © 2002-2005 Atlassian All rights reserved.

Page 284: Jira Manual

Configure Navigator ColumnsIf the columns order has been modified from the defaults it is possible to restore the defaults byselecting "Restore Defaults". The link should appear only if the defaults are not used. Whenconfiguring the installation defaults (only available to administrators), the link is called "RestoreSystem Defaults", and when clicked restores the configuration JIRA ships with by default.

When configuring navigator columns a user can only see columns for issue fields that have notbeen hidden. It is possible to add any of the existing custom fields to the navigator column list.When configuring the navigator columns a user can choose any custom field that they havepermissions to see. That is, any custom field except those that are project specific and apply onlyto a project that the user does not have permissions to browse. Some custom fields, even ifselected to be part of the navigator columns, will not appear in the issue navigator for all issues.For example, project specific custom fields will be shown only of the filter has bee restricted tothat project only. Issue type custom fields will only appear if the filter has been restricted to thatissue type.

Please note, that when administrators are configuring default navigator columns (used for allusers with no personal configurations), their permissions are ignored, so that they can add aproject specific custom field from a project that they do not have permissions to browse. Thefield would never be actually shown to users that do not have permissions to see it.

5.14.3. Ordering Issues by Navigator Columns

When viewing issues in the navigator, it is possible to re-order the issues displayed by themajority of columns available (the images column is non-orderable). For example, by selectingthe 'Components' column header, the navigator re-orders the issues displayed based on earliestcomponent found. It is possible to further sort the issue order by selecting other column headers.

5.15. Issue Navigator Views

The Issue Navigator is used within JIRA to find and filter issues. Once you have created a filter,you can save it or view it using a number of different pre-built 'views'. Each Issue Navigator

JIRA Documentation

Page 284Copyright © 2002-2005 Atlassian All rights reserved.

Page 285: Jira Manual

view presents the currently selected filter in a different way (for example as an Excel spreadsheet, orin XML).

To change views, simply select one of the links under Current View: (shown in the screen shotbelow)

JIRA view selectorThe different views are:

Browser This is the default view. It uses HTML to show asingle table row per issue with brief issueinformation. If you have the filter pane hidden, a fewextra columns are displayed. The issues are displayeda page at a time.

This view is most useful to creating and previewingfilters.

Printable The same as the Browser view, but it shows allissues in a printable format.

XML The XML view returns an extended RSSrepresentation of the current filter. For moredetails see the RSS API section.

Full Content This view shows each issue matching the filterwith full content, including all comments andfields. This is useful for printing.

Excel (All fields) The Excel view presents all the issues in thecurrent filter as an Excel spreadsheet. Thespreadsheet can then be saved (for example toemail to a colleague), or edited to producegraphs and charts. It is also useful for basicreporting and statistical tasks. The All fields viewwill include all currently unhidden fields that Jirais configured for and their values in thegenerated excel spreadsheet. NB - SP1a isrequired for office 2000. Some users reportproblems using Excel over SSL.

Excel (Current fields) The Excel view presents all the issues in thecurrent filter as an Excel spreadsheet. Thespreadsheet can then be saved (for example toemail to a colleague), or edited to producegraphs and charts. It is also useful for basicreporting and statistical tasks. The Current fieldsview will include only the fields that are currentlydisplaying in your issue navigator and theirvalues in the generated excel spreadsheet. NB -SP1a is required for office 2000. Some usersreport problems using Excel over SSL.

5.15.1. RSS API

The XML is also a full RSS API for JIRA. The XML view presents an RSS 0.9.2 feed of the currentfilter and also includes a few additional fields for other JIRA information. With this XML, you can

JIRA Documentation

Page 285Copyright © 2002-2005 Atlassian All rights reserved.

Page 286: Jira Manual

easily extract JIRA issue data for use in other applications using a simple HTTP GET.

You can view a sample RSS feed of the latest 15 issues reported on jira.atlassian.com.

The URL created by the XML link in the Issue Navigator contains all the parameters needed todo an HTTP GET request from outside JIRA (for example from an RSS aggregator likeAmphetaDesk).

Using different URL parameters you can control the set of issues returned in the RSS. For detailson these parameters, see the HTML Issue Navigator Edit Filters form. Additionally, thetempMax parameter can be used to control how many issues are returned in your RSS feed.

5.15.1.1. RSS Authentication parameters

When accessing RSS generated from JIRA you may find that access to some resources requireuser authentication. There are three options for providing user authorization:

1. To retrieve XML data without logging in, you may have a Browse permission turned on forAnyone

2. You may provide the parameters os_username and os_password in the request (ex.http://jira.atlassian.com/browse/TST-1?os_username=tester&os_password=tstpassword). Theproblem with this method is that it transmits your username and password across the wire inclear text, this may not be an option for some users.

3. This last option is available since JIRA 3.4. You can provide the request parameteros_authType=basic (ex. http://mycompany.com/anypage?os_authType=basic). This willforce the server to issue a challenge for user credentials via the basic http authenticationprotocol.

5.16. Using JIRA's Quick Search

Sometimes you just want to be able to get to the particular issue that you are interested in. Othertimes you can't remember what the issue was, but you remember that it was an open issue,assigned to you. Quick search can help you.

5.16.1. Jump to an Issue

If you type in the key of an issue, you will jump straight to that issue. For example, if you type in'ABC-107' (or 'abc-107'), you will get redirected to the JIRA issue 'ABC-107'.

In many cases, you do not even need to type in the full key, but just the numerical part. If you arecurrently working on the 'ABC' project, and you type in '123', then you will be redirected to'ABC-123'.

5.16.2. Smart Querying

Quick search also enables you to perform a very quick search for an issue. Say that you werelooking for all the open bugs in the test project, you could type in 'test open bugs', and it wouldperform a search for you.

The search terms that JIRA recognises are:

Free text searchYou can add normal search words, which will work the same way as if you typedthem into the query box in the issue navigator.Issues assigned to meYou can use the keyword 'my', as in 'my open bugs'.Overdue issues

JIRA Documentation

Page 286Copyright © 2002-2005 Atlassian All rights reserved.

Page 287: Jira Manual

You can use the keyword 'overdue' to search for issues that were due before today.Issues in a particular projectYou can use the project name, 'test', or by key, 'TST' or 'tst'.Issues in a particular statusYou can use the name of any status in your search. Examples are open, closed.Issues with a particular resolutionYou can use a resolution name to search for issues with a particular resolution. If yousearch for "duplicate" to search for all issues that have a resolution of "Duplicate". Youcan also used 'unresolved' as a keyword query.Issues with a particular priorityYou can use a priority name to search for issues with a particular pririty. If you searchfor "blocker" to search for all issues that have a priority of "blocker".Issues with a particular fix for versionYou can use the prefix "ff:" to search for issues with a particular fix for version(s). Thisallows you to search across multiple versions. "ff:enterprise" will search for all issueswith a fix for version that contains the word enterprise. Note that there can be no spacesbetween "ff:" and the version name.Issues with a particular versionYou can use the prefix "v:" to search for issues with a particular version(s). This allowsyou to search across multiple versions. "v:3.0" will search for all issues with a versionthat contains the word "3.0".Issues of a particular issue typeYou can use the type of an issue in the search. Examples include bug, task. Note thatyou can also include plurals, such as bugs.Issues with a particular created, updated, or due dateYou can find issues with certain dates. You can use the prefix created:, updated:, or due:. Forthe date range, you can use today, tomorrow, yesterday, a single date range (eg "-1w"), or twodate ranges (eg. "-1w,1w"). Note that date ranges cannot spaces in them.

Some examples:

• "created:today", "created:yesterday"• "updated:-1w" - issues updated in the last week• "due:1w" - issues due in the next week.• "due:-1d,1w" - all issues due from yesterday to next week.• "updated:-1y,-1m" - all issues created from one year ago, to one month ago.• "created:-1m updated:-1w" - all issues created in the last month, updated in the last week.

Note that you can combine terms together. 'my closed tst tasks', 'open test bugs pear', 'closed testbugs ' are all valid search queries.

Note:In Mozilla-based browsers, try creating a bookmark with URLhttp://jira.atlassian.com/secure/QuickSearch.jspa?searchString=%s (substituting in your JIRA URL) andkeyword 'j'. Now typing 'j my open bugs' in the browser URL bar will search JIRA for your open bugs.

5.17. Logout Confirmation

Administrators can now configure JIRA to prompt users with a confirmation before logging themout. You can adjust this setting by going to the Administration page and then clicking "GeneralConfiguration" link found under "Options and Settings" on the left pane.

JIRA Documentation

Page 287Copyright © 2002-2005 Atlassian All rights reserved.

Page 288: Jira Manual

Logout Confirmation Setting is switched off by defaultAs shown above, JIRA will never prompt users for logout confirmation by default. To changethis, click on "Edit Configuration".

Logout Confirmation SettingThe "Never" and "Always" settings are self-explanatory. When set to "Cookie", users will onlybe prompted if they have logged in using a cookie (ie. checked the box reading "Remember mylogin on this computer" before they logged on).

5.18. Portlets

5.18.1. JIRA Portlets

JIRA provides the ability to display summary information on project/issue data through the useof portlets. Each portlet can be configured to display project and issue details relevant toparticular users. The portlets can be added to the dashboard - providing a central location forquick access to this information.

5.18.1.1. Standard Portlets

JIRA provides a set of standard portlets out of the box:

• Bugzilla ID Search Portlet• Projects Portlet• Project Statistics Portlet• Assigned To Me Portlet• Project Portlet• Introduction Portlet• Two Dimensional Filter Statistics Portlet• Saved Filter Portlet• Project Table

JIRA Documentation

Page 288Copyright © 2002-2005 Atlassian All rights reserved.

Page 289: Jira Manual

• Filter Statistics Portlet• In Progress Portlet• List All Filters Portlet• Administration Portlet• Quick Links Portlet

5.18.1.2. Creating New Portlets

New portlets can be created by writing a Java class, a template and an XML descriptor file,packaged as JIRA plugin. See How To Create a JIRA Portlet for more information.

5.18.2. Bugzilla ID Search Portlet

5.18.2.1. Overview

The Bugzilla ID Search portlet allows the user to search all JIRA issues for references to BugzillaIDs. If the specified ID is not found within JIRA, the portlet redirects to the Bugzilla issue if aBugzilla server URL has been specified. This allows JIRA to become the one interface for all JIRAand Bugzilla data.

5.18.2.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Bugzilla ID Search' portlet.3. Click Add.4. Optionally specify a URL for the Bugzilla server.

Bugzilla ID Search Portlet Form5. Click Save.6. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.2.3. Dashboard Display

The Bugzilla ID Search portlet should appear as follows on the dashboard:

Bugzilla ID Search Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.3. Projects Portlet

JIRA Documentation

Page 289Copyright © 2002-2005 Atlassian All rights reserved.

Page 290: Jira Manual

5.18.3.1. Overview

The Projects portlet provides information and various filters related to all projects within JIRA.If available, the portlet displays links to:

• Open Issues• Road Map• Change Log• Popular Issues

for each project within JIRA.

5.18.3.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Projects' portlet.3. Click Add.4. Select 'Full' or 'Brief' to specify the amount of information to be displayed.

Projects Portlet Form5. Click Save.6. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.3.3. Dashboard Display

The Projects portlet should appear as follows on the dashboard:

Projects Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.4. Project Statistics Portlet

5.18.4.1. Overview

The Project Statistics portlet allows various per-project statistical data to be displayed on thedashboard. The portlet can be configured to display per-project statistical data based on variousfields within JIRA (e.g. all open issues broken down by Assignee).

JIRA Documentation

Page 290Copyright © 2002-2005 Atlassian All rights reserved.

Page 291: Jira Manual

5.18.4.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Project Statistics' portlet.3. Click Add.4. Select the project on which the portlet will focus.5. Select the field on which the statistics will focus.

Project Statistics Portlet Form6. Click Save.7. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.4.3. Dashboard Display

The Project Statistics portlet should appear as follows on the dashboard:

Project Statistics Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.5. Assigned To Me Portlet

5.18.5.1. Overview

The Assigned To Me portlet displays all open issues in all projects assigned to the current userviewing the dashboard.

5.18.5.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Assigned To Me' portlet.3. Click Add.4. Select the maximum number of issues to display in the portlet.

JIRA Documentation

Page 291Copyright © 2002-2005 Atlassian All rights reserved.

Page 292: Jira Manual

Assigned to Me Portlet Form5. Click Save.6. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.5.3. Dashboard Display

The Assigned to Me portlet should appear as follows on the dashboard:

Assigned to Me Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.6. Project Portlet

5.18.6.1. Overview

The Project portlet provides information and various filters related to a specified project on thedashboard.

5.18.6.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Project' portlet.3. Click Add.4. Select the project on which the portlet will focus.5. Select 'Full' or 'Brief' to specify the amount of information to be displayed.

JIRA Documentation

Page 292Copyright © 2002-2005 Atlassian All rights reserved.

Page 293: Jira Manual

Project Portlet Form6. Click Save.7. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.6.3. Dashboard Display

The Project portlet should appear as follows on the dashboard:

Project Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.7. Introduction Portlet

5.18.7.1. Overview

The Introduction portlet displays a configurable introduction message on the dashboard.

5.18.7.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Introduction' portlet.3. Click Add.4. The portlet can be positioned on the dashboard through the dashboard configuration page.

Note:The text/html displayed in the Introduction portlet is configured through the JIRA configuration page.

JIRA Documentation

Page 293Copyright © 2002-2005 Atlassian All rights reserved.

Page 294: Jira Manual

5.18.7.3. Dashboard Display

The Introduction portlet should appear as follows on the dashboard:

Introduction Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.8. Two Dimensional Filter Statistics Portlet

5.18.8.1. Overview

The Two Dimensional Filter Statistics portlet displays statistical data based on a specified filterin a configurable table format.

For example, a filter can be created to retrieve all open issues in all projects. The portlet can thenbe configured to display the statistical data on this collection of issues in a table withconfigurable axes - e.g. Assignee versus Status.

5.18.8.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Two Dimensional Filter Statistics' portlet.3. Click Add.4. Select the filter on which the portlet will focus.5. Configure the X-Axis of the table by selecting the required field.6. Configure the Y-Axis of the table by selecting the required field.7. Select if the 'Totals' column in the table is required.

Two Dimensional Filter Statistics Portlet Form8. Click Save.9. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.8.3. Dashboard Display

The Two Dimensional Filter Statistics portlet should appear as follows on the dashboard:

JIRA Documentation

Page 294Copyright © 2002-2005 Atlassian All rights reserved.

Page 295: Jira Manual

Two Dimensional Filter Statistics Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.9. Saved Filter Portlet

5.18.9.1. Overview

The Saved Filter portlet displays the results of a specified filter on the dashboard. It can beconfigured to display a maximum number of issues from the collection returned from the specifiedfilter.

5.18.9.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Saved Filter' portlet.3. Click Add.4. Select the filter on which the portlet will focus.5. Select the maximum number of issues that the portlet will display.6. Select if the filter description (if any) should be displayed within the portlet.

Saved Filter Portlet Form7. Click Save.8. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.9.3. Dashboard Display

The Saved Filter portlet should appear as follows on the dashboard:

JIRA Documentation

Page 295Copyright © 2002-2005 Atlassian All rights reserved.

Page 296: Jira Manual

Saved Filter Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.10. Project Table Portlet

5.18.10.1. Overview

The Project Table portlet displays all the project names in a table in the dashboard.

5.18.10.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Project Table' portlet.3. Click Add.4. Select the maximum number of columns which will appear in the table.

Project Table Portlet Form5. Click Save.6. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.10.3. Dashboard Display

The Project Table portlet should appear as follows on the dashboard:

Saved Filter Portlet on Dashboard

JIRA Documentation

Page 296Copyright © 2002-2005 Atlassian All rights reserved.

Page 297: Jira Manual

Further information on all JIRA portlets is available here.

5.18.11. Filter Statistics Portlet

5.18.11.1. Overview

The Filter Statistics portlet displays the collection of issues returned from a specified filter brokendown by a specified field.

For instance, a filter can be created to return all open issues from all projects. The portlet can then beconfigured to display these issues broken down by a field such as Assignee.

5.18.11.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Filter Statistics' portlet.3. Click Add.4. Select the filter on which the portlet will focus.5. Select the field on which the statistics will focus.

Filter Statistics Portlet Form6. Click Save.7. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.11.3. Dashboard Display

The Filter Statistics portlet should appear as follows on the dashboard:

Filter Statistics Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.12. In Progress Portlet

JIRA Documentation

Page 297Copyright © 2002-2005 Atlassian All rights reserved.

Page 298: Jira Manual

5.18.12.1. Overview

The In Progress portlet displays all issues that are currently in progress and assigned to thecurrent user viewing the dashboard.

5.18.12.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'In Progress' portlet.3. Click Add.4. Select the maximum number of issues which the portlet will display.

In Progress Portlet Form5. Click Save.6. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.12.3. Dashboard Display

The In Progress portlet should appear as follows on the dashboard:

In Progress Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.13. List All Filters Portlet

5.18.13.1. Overview

The List All Filters portlet displays all saved filters for the current user on the dashboard.

5.18.13.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'List All Filters' portlet.3. Click Add.4. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.13.3. Dashboard Display

The List All Filters portlet should appear as follows on the dashboard:

JIRA Documentation

Page 298Copyright © 2002-2005 Atlassian All rights reserved.

Page 299: Jira Manual

List All Filters Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.14. Administration Portlet

5.18.14.1. Overview

The Administration portlet displays quick links to administrative functions for admin users on thedashboard.

5.18.14.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Administration' portlet.3. Click Add.4. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.14.3. Dashboard Display

The Administration portlet should appear as follows on the dashboard:

Administration Portlet on DashboardFurther information on all JIRA portlets is available here.

5.18.15. Quick Links Portlet

5.18.15.1. Overview

The Quick Links portlet displays a number of useful links to issues associated with the current user.Each link directs the user to the Issue Navigator, displaying the relevant issues. The portlet provides

JIRA Documentation

Page 299Copyright © 2002-2005 Atlassian All rights reserved.

Page 300: Jira Manual

links to:

• Reported Issues - all issues reported by the current user• Voted Issues - all issues voted for by the current user• Watched Issues - all issues watched by the current user

5.18.15.2. Adding Portlet to Dashboard

1. Navigate to the dashboard configuration page.2. Select the 'Quick Links' portlet.3. Click Add.4. The portlet can be positioned on the dashboard through the dashboard configuration page.

5.18.15.3. Dashboard Display

The Quick Links portlet should appear as follows on the dashboard:

Quick Links Portlet on DashboardFurther information on all JIRA portlets is available here.

5.19. Reports

5.19.1. JIRA Reports

JIRA provides functionality to generate various reports. These reports display statistics (someincluding time tracking details) for particular versions, developers or other fields within JIRA.

The following reports are included with JIRA:

• Road Map - Show unresolved issues for the next three versions.• Change Log - Show resolved issues for the previous three versions• Popular Issues - Show unresolved issues ordered by popularity (votes).• Release Notes - Generate a HTML or text list of issues resolved in a version.• Time Tracking Report - See progress towards completing a certain version, using work logs

and issue estimates• Developer Workload Report - See how much a developer has been allocated, and how long it

should take.• Version Workload Report - See how much outstanding work there is (per-user and per-issue)

towards completing a version.• Single Level Group By Report - List issues grouped by a field.

Note:Time tracking related reports are only available when time tracking is on. You can turn on time tracking in the administrationsection.

In addition to the built-in reports, there are some externally available reports (eg. Gantt ChartReport, Timesheet Report/Portlet) in the community and extensions sections of the JIRA Wiki.One can also create new reports with the plugin API.

5.19.2. Road Map report

JIRA provides a Road Map for each project, which shows issues scheduled for the next threeunreleased versions. The Road Map provide an overview of progress made towards releasing aversion.

JIRA Documentation

Page 300Copyright © 2002-2005 Atlassian All rights reserved.

Page 301: Jira Manual

To access a project's Road Map, click on Browse, and select the project if presented with a list. Thenclick the Road Map tab. You will see something like this:

Road Map from http://jira.atlassian.comA live version of this example can be seen online.

5.19.2.1. See also

• The Change Log - looking back at recent releases rather than forward• JIRA Reports Overview

5.19.3. Change Log report

JIRA's Change Log report shows resolved issues in the last three releases of a project. Whereas theRoad Map looks forward, the Change Log looks back, giving an overall view of issues resolved inrecent versions.

To access a project's Change Log, click on Browse, and select the project if presented with a list.Then click the Change Log tab. You will see something like this:

JIRA Documentation

Page 301Copyright © 2002-2005 Atlassian All rights reserved.

Page 302: Jira Manual

Change Log from http://jira.atlassian.comA live version of this example can be seen online.

5.19.3.1. See also

• The Road Map - looking forward to next releases• JIRA Reports Overview

5.19.4. Popular Issues report

JIRA's Popular Issues report shows unresolved issues in a project, sorted by votes. It isparticularly useful on public JIRA installations. This report is only visible if voting is enabled.

To access the Popular Issues report, click on Browse, and select the project if presented with alist. Then click the Popular Issues tab. You will see something like this:

JIRA Documentation

Page 302Copyright © 2002-2005 Atlassian All rights reserved.

Page 303: Jira Manual

Popular Issues from http://jira.atlassian.comA live version of this example can be seen online.

5.19.4.1. See also

• JIRA Reports Overview

5.19.5. Time Tracking Report

This report displays useful time-tracking information on issues for a particular version. It showsoriginal and current time estimations for particular issues, and whether they are ahead, or behind theoriginal schedule. Details on enabling time tracking can be found here.

5.19.5.1. Generating a Time Tracking Report

To generate a time tracking report - follow these steps:

1. Go to the Project Browser and select the project which you wish to generate the report on.2. Click on Time Tracking Report.

JIRA Documentation

Page 303Copyright © 2002-2005 Atlassian All rights reserved.

Page 304: Jira Manual

Time Tracking on Browser3. A Screen form will appear as follows:

Time Tracking Form Screen Shot4. Select the version which the Time Tracking Report is on.5. The report can be sorted either with the most completed, or least completed issues first.6. You can filter out issues which are not time-tracked, or are completed (i.e. 0 hours estimated

time remaining).

Note:Time tracking related reports are only available when time tracking is on. You can turn on time tracking in the administrationsection.

5.19.5.2. The Report

The report generated will look something like this:

JIRA Documentation

Page 304Copyright © 2002-2005 Atlassian All rights reserved.

Page 305: Jira Manual

Time Tracking Report Screen ShotThe table shows the issues within the version. The last line in the table is an aggregate total of thetime tracking information for this issue. There are four time tracking fields as follows:

Field Description

Original Time Estimate The amount of time which was originallyestimated it would take to complete this issue.

Estimated Time Remaining The current estimate of the the amount of time itwould take to complete this issue.

Time Spent The amount of time spent on the issue. This isthe aggregate amount of time which is loggedagainst this issue

Accuracy This displays the accuracy of your originalestimate compared to the current estimate forthe issue. It is the difference between the sum ofthe Time Spent and Time Remaining fields, andthe original Time Estimate field.

The report also includes two graphs which depict aggregate time tracking information for theversion.The first bar graph shows the percentage how completed (in green) issues are in this version.

Completion GraphThe second bar graph shows the accuracy of the original estimates. The length of this graphcompared to the completion graph gives an indication of whether the issues in the version are aheador behind schedule. There are three cases:

1. The issues are on schedule with the original estimation. The accuracy bar is completely grey andsame length as the completion bar above it.

On Schedule Graph

JIRA Documentation

Page 305Copyright © 2002-2005 Atlassian All rights reserved.

Page 306: Jira Manual

2. The issues are behind the original estimation. (i.e. It will take longer than originallyestimated.) The dark grey region reflects the original estimation time. The light grey region isthe amount of time which the issues are behind by.

Behind Graph3. The issues are ahead of the original estimation. (i.e. It will take shorter than original

estimated.) The accuracy graph is longer than the completion graph. The whole bar representsthe original estimated time, and the dark grey region depicts the amount of time which theoriginal estimate have over estimated by.

Ahead Graph

5.19.6. Developer Workload Report

This report displays useful time-tracking information on issues assigned to a particular user. Itshows the number of unresolved issues assigned to the specified user and the workload remainingon a per-project basis.

5.19.6.1. Generating a Developer Workload Report

To generate a developer workload report - follow these steps:

1. Go to the 'Project Browser' and select a project (report is based on a developer - the projectselection will not affect the report).

2. Click on 'Developer Workload Report'.

Developer Workload on Browser3. A screen form will appear as follows:

JIRA Documentation

Page 306Copyright © 2002-2005 Atlassian All rights reserved.

Page 307: Jira Manual

Developer Workload Form Screen Shot4. Select the user to focus the Developer Workload report on.

Note:Time tracking related reports are only available when time tracking is on. You can turn on time tracking in the administration section.

5.19.6.2. The Report

The report generated will look something like this:

Developer Workload Report Screen ShotThe table shows the number of unresolved issues assigned to the specified user and the workloadremaining on a per-project basis. The last line in the table is an aggregate total of the number ofissues and the workload remaining for this user.

5.19.7. Version Workload Report

This report displays useful time-tracking information on the current workload for a specific versionwithin a specific project. For the specified version, it shows the number of unresolved issuesassigned to each user and the workload remaining within the specified project.

5.19.7.1. Generating a Version Workload Report

To generate a version workload report - follow these steps:

1. Go to the 'Project Browser' and select the project that you wish to generate the report on.2. Click on 'Version Workload Report'.

JIRA Documentation

Page 307Copyright © 2002-2005 Atlassian All rights reserved.

Page 308: Jira Manual

Version Workload on Browser3. A screen form will appear as follows:

Version Workload Form Screen Shot4. Select the version to focus the Version Workload report on.

Note:Time tracking related reports are only available when time tracking is on. You can turn on time tracking in the administrationsection.

5.19.7.2. The Report

The report generated will look something like this:

JIRA Documentation

Page 308Copyright © 2002-2005 Atlassian All rights reserved.

Page 309: Jira Manual

Version Workload Report Screen ShotThe first table summarizes the workload for each user broken down by issue type for the specifiedproject.

Following the summary, the report is composed of individual sections for each user - with workloadbroken down by issue type. Each individual section begins with the workload total for the specificuser. Finally, all unassigned issues are displayed.

5.19.8. Single Level Group By Report

This report displays issues returned from a specified filter grouped by a specified field. For example,a filter can be created to retrieve all open issues for a particular version. The report can then beconfigured to display these issues grouped by a specified field - e.g. Assignee.

5.19.8.1. Generating a Single Level Group By Report

To generate a single level group by report - follow these steps:

1. Go to the 'Project Browser' and select a project (report is based on a filter - the project selectionwill not affect the report).

2. Click on 'Single Level Group By Report'.

JIRA Documentation

Page 309Copyright © 2002-2005 Atlassian All rights reserved.

Page 310: Jira Manual

Version Workload on Browser3. A screen form will appear as follows:

Version Workload Form Screen Shot4. Select the filter.5. Select the field by which the report will group the issues returned from the specified filter.

5.19.8.2. The Report

The report generated will look something like this:

Version Workload Report Screen Shot

JIRA Documentation

Page 310Copyright © 2002-2005 Atlassian All rights reserved.

Page 311: Jira Manual

The report displays the issues returned by the specified filter grouped by the specified field.

5.20. Searching & Filtering

5.20.1. Search and Issue Filters

JIRA provides a powerful issue search facility. The utility of this is further enhanced by the ability tosave a search. A saved search is called an issue filter.

Various operations can be performed with an issue filter.

• save the search for use at a later time• share a search with colleagues• have the results from a search mailed to you on a daily basis• subscribe to the search using RSS aggregators

While you are interacting with JIRA, your current search will be remembered, along with whetherthe search you are using is new, a saved search, or a modification of a saved search.

Note:The restriction on Issue Filters is that you can only have one search at any one time, even if you have multiple browser windows open. Toget around this restriction, do not be afraid to save filters that you build, see how to save a filter. You can then effortlessly flip betweendifferent saved filters.

5.20.1.1. Searching Issues

1. Start using JIRA as a user with permission to browse the projects you are interested in. This maybe the anonymous user, if the project is open to the world.

2. On the top navigation bar, click on the "Find Issues" tab. This will bring up the Issue Navigator.

JIRA Documentation

Page 311Copyright © 2002-2005 Atlassian All rights reserved.

Page 312: Jira Manual

Issue Query interface

The pane on the left is the search form. Several of the form items have contextual help available,denoted by the

Context helpicon. These form items allow you to narrow your search, be it to issues in a certain project, onlyissues that are marked as stoppers, only issues marked as enhancements, and so on.

5.20.1.2. Projects, issue types and searching

When searching in JIRA, selected projects and issue types determine what fields are shown andwhat options you can see for these fields. For example, version and component fields will only beavailable when searching for a single project and will have different options for each project.When you change the projects or issue types, you may need to refresh the search filter in order to

JIRA Documentation

Page 312Copyright © 2002-2005 Atlassian All rights reserved.

Page 313: Jira Manual

get most up to date versions, components and custom fields.

If you search on a single project, JIRA will remember that as your selected project and will defaultto that project on the "Browse Project" and "Create Issue" screens.

5.20.1.3. Searching for custom fields

Custom fields may also be searched, and will be available in the form on the left when appropriate.Thus project-specific custom fields can be searched when you select to only search that specificproject. Issue type scoped custom fields will be available to search by after a search on that issuetype.

5.20.1.4. Work Ratio Search Field

The search form contains a 'Work Ratio' section enabling users to search JIRA issues based ontime-tracking details.

The 'Work Ratio' search is based on the Actual work logged against an issue versus the originalEstimated work duration.

• Work Ratio Percentage = (Actual / Estimated Work) x 100

It is possible to enter a minimum, maximum or percentage range - the search respectively returningall issues above, below or within the specified percentage range.

Work Ratio

5.20.1.5. Navigating the Search Results

When an issue from a search result set is selected, an issue navigator becomes available in the issuetitle bar. This navigator displays the current issue position within the result set. It also provides a linkto the next and previous issue in the result set along with a link to return to the search results. It ispossible to navigate through the search results by using the shortcut keys [ALT]+P (Previous) and[ALT]+N (Next).

5.20.1.6. Saving a search to an Issue Filter

When you are happy that you have refined the search to something you will use again, you can saveyour search as a filter by clicking the "save" link.

JIRA Documentation

Page 313Copyright © 2002-2005 Atlassian All rights reserved.

Page 314: Jira Manual

Filter view

At this point, the four Filter tabs (previously unselected) become relevant.

View tabViews the current filter. A summary of what the filter does is shown on the left, withthe filter results on the right. Operations available for this filter are shown as links.These are discussed below.Edit tabLets you edit the current filter's search criteria.New tabAbandon the current filter and start a new oneAll tabManage your saved filters.

5.20.1.7. Filter Subscriptions

JIRA lets users or user groups subscribe to a filter. At a specified interval, JIRA will run thefilter's search and mail the subscribers with the results.

To set up a filter subscription:

1. First, ensure that you have a SMTP mail server configured.2. Locate the filter you are interested in (e.g. in the All filter tab)

JIRA Documentation

Page 314Copyright © 2002-2005 Atlassian All rights reserved.

Page 315: Jira Manual

Issue filters (from jira.atlassian.com)3. Click on the Subscribe link

Subscribing to an issue filter• Select the desired recipient. Only users with the "Manage Group Filter Subscriptions" global

permission are able to subscribe a group to a filter. By default, this means users in thejira-developer group, leaving regular jira-users only able to subscribe themselves.

• Specify a time interval using the described syntax.• Click "subscribe".

4. You will be taken to a subscription summary page, where your subscription can be tested.

5.20.1.8. Filter Sharing

Filters can be shared with other users as follows:

1. Ensure that the current user has the "Create Shared Filter" global permission. By default, this isassigned to people in the jira-developers group.

2. In the All filter tab (under the top-level "Find Issues" menu), locate the filter you wish to share,and click on the "Share" link at the far right.

JIRA Documentation

Page 315Copyright © 2002-2005 Atlassian All rights reserved.

Page 316: Jira Manual

Sharing a filter3. Select the group you wish to share the filter with, or share with all users.

5.20.1.9. Filter Specific Navigator Column Order

In Enterprise version it is possible to add an Issue Navigator Column Order to a saved filter. Theresults of a filter are displayed using the saved column order, if the filter has one. Otherwise theresults are shown using the user's personal column order or the system default.

Adding Column Order

To add a column layout to a saved filter, navigate to the "Manage" tab of the issue navigator, andclick the "Add Column Order" link.

Add Column Order ScreenshotThen configure the column order the same way you would configure your personal IssueNavigator column order.

Editing Column Order

If the filter already has a saved column order the "Add Column Link" will change to "EditColumn Order". To edit the column order, navigate to the "Edit Column Order" link and re-orderthe columns as needed.

Deleting Column Order

To delete filter's saved column order click the "Edit Column Order" link, and then choose the"Remove Filter''s Column Order" link from the presented page. Select the Issue Navigator's"Manage" tab to return to the "Manage Filters" screen.

Overriding Column Order

JIRA Documentation

Page 316Copyright © 2002-2005 Atlassian All rights reserved.

Page 317: Jira Manual

As mentioned earlier, if a filter has a saved column order, the results will be presented using thatcolumn order when the filter is run. The users, however, can choose to use their own column order(or the system default column order, if they do not have a personal one configured) to view theresults. To do this, click the "Use your Column Order" link on the Issue Navigator search resultsscreen.

Use Own Column Order ScreenshotTo go back to using filter's column order select the "Use filter's Column Order" link.

5.20.2. Search Query Syntax

JIRA uses Lucene for text indexing, which provides a rich query language that can makeconstructing full text queries daunting.

Most of the time however just entering a text string will suffice!

If you want to find out how to construct more advanced queries, read on. If you're looking forinformation on enabling and disabling indexing and searching within JIRA look here.

Note:Most of this information is derived from the Lucene document on Query Parser Syntax - thanks to Jakarta and the Lucene team for such agreat component

5.20.2.1. Query Terms

A query is broken up into terms and operators. There are two types of terms: Single Terms andPhrases.

A Single Term is a single word such as "test" or "hello".

A Phrase is a group of words surrounded by double quotes such as "hello dolly".

Multiple terms can be combined together with Boolean operators to form a more complex query (seebelow).

Note: All query terms in JIRA are case insensitive.

5.20.2.2. Term Modifiers

JIRA supports modifying query terms to provide a wide range of searching options.

Wildcard Searches

JIRA supports single and multiple character wildcard searches.

JIRA Documentation

Page 317Copyright © 2002-2005 Atlassian All rights reserved.

Page 318: Jira Manual

To perform a single character wildcard search use the "?" symbol.

To perform a multiple character wildcard search use the "*" symbol.

The single character wildcard search looks for terms that match that with the single characterreplaced. For example, to search for "text" or "test" you can use the search:te?t

Multiple character wildcard searches looks for 0 or more characters. For example, to search forWindows, Win95 or WindowsNT you can use the search:win*

You can also use the wildcard searches in the middle of a term. For example, to search forWin95 or Windows95 you can use the searchwi*95

Note:You cannot use a * or ? symbol as the first character of a search.

5.20.2.3. Fuzzy Searches

JIRA supports fuzzy searches. To do a fuzzy search use the tilde, "~", symbol at the end of aSingle word Term. For example to search for a term similar in spelling to "roam" use the fuzzysearch:roam~

This search will find terms like foam and roams

Note: Terms found by the fuzzy search will automatically get a boost factor of 0.2

5.20.2.4. Proximity Searches

JIRA supports finding words are a within a specific distance away. To do a proximity search usethe tilde, "~", symbol at the end of a Phrase. For example to search for a "atlassian" and"jira" within 10 words of each other in a document use the search:"atlassian jira"~10

5.20.2.5. Boosting a Term

JIRA provides the relevance level of matching documents based on the terms found. To boost aterm use the caret, "^", symbol with a boost factor (a number) at the end of the term you aresearching. The higher the boost factor, the more relevant the term will be.

Boosting allows you to control the relevance of a document by boosting its term. For example, ifyou are searching foratlassian jira

and you want the term "atlassian" to be more relevant boost it using the ^ symbol along withthe boost factor next to the term. You would type:atlassian^4 jira

This will make documents with the term atlassian appear more relevant. You can also boostPhrase Terms as in the example:"atlassian jira"^4 querying

By default, the boost factor is 1. Although, the boost factor must be positive, it can be less than 1(i.e. .2)

JIRA Documentation

Page 318Copyright © 2002-2005 Atlassian All rights reserved.

Page 319: Jira Manual

5.20.2.6. Boolean Operators

Boolean operators allow terms to be combined through logic operators. JIRA supports AND, "+",OR, NOT and "-" as Boolean operators .

Note:Boolean operators must be ALL CAPS.

OR

The OR operator is the default conjunction operator. This means that if there is no Boolean operatorbetween two terms, the OR operator is used. The OR operator links two terms and finds a matchingdocument if either of the terms exist in a document. This is equivalent to a union using sets. Thesymbol || can be used in place of the word OR.

To search for documents that contain either "atlassian jira" or just "jira" use the query:"atlassian jira" || jira

or"atlassian jira" OR jira

AND

The AND operator matches documents where both terms exist anywhere in the text of a singledocument. This is equivalent to an intersection using sets. The symbol && can be used in place of theword AND.

To search for documents that contain "atlassian jira" and "issue tracking" use thequery:"atlassian jira" AND "issue tracking"

Required term: +

The "+" or required operator requires that the term after the "+" symbol exist somewhere in a thefield of a single document.

To search for documents that must contain "jira" and may contain "atlassian" use the query:+jira atlassian

NOT

The NOT operator excludes documents that contain the term after NOT. This is equivalent to adifference using sets. The symbol ! can be used in place of the word NOT.

To search for documents that contain "atlassian jira" but not "japan" use the query:"atlassian jira" NOT "japan"

Note: The NOT operator cannot be used with just one term. For example, the following search willreturn no results:NOT "atlassian jira"

Excluded term: -

The "-" or prohibit operator excludes documents that contain the term after the "-" symbol.

To search for documents that contain "atlassian jira" but not "japan" use the query:"atlassian jira" -japan

JIRA Documentation

Page 319Copyright © 2002-2005 Atlassian All rights reserved.

Page 320: Jira Manual

5.20.2.7. Grouping

JIRA supports using parentheses to group clauses to form sub queries. This can be very useful ifyou want to control the boolean logic for a query.

To search for either "atlassian" or "jira" and "bugs" use the query:(atlassian OR jira) AND bugs

This eliminates any confusion and makes sure you that bugs must exist and either termatlassian or jira may exist.

5.20.2.8. Escaping Special Characters

JIRA supports escaping special characters that are part of the query syntax. The current listspecial characters are+ - && || ! ( ) { } [ ] ^ " ~ * ? : \

To escape these character use the \ before the character. For example to search for (1+1):2use the query:\(1\+1\)\:2

6. Admin Help

6.1. Performance

6.1.1. Profiling

To quantify performance problems, you can turn JIRA profiling on. You will then get a profilefor each URL requested in the logs:[Filter: profiling] Turning filter on [jira_profile=on][116ms] - /secure/Dashboard.jspa[5ms] - IssueManager.execute()[5ms] - IssueManager.execute()[5ms] - Searching Issues

[29ms] - IssueManager.execute()[29ms] - IssueManager.execute()[29ms] - Searching Issues[28ms] - Lucene Query[23ms] - Lucene Search

One performance problem with JIRA is can be the application server that you are running. Thedatabase connection pooling, JSP compilation times, resource allocation are different betweenapplication servers. Known slow servers include JBoss 3.x, Tomcat 4.0 and Tomcat 4.1.24. Thefastest servers for JIRA at the moment are Tomcat, Resin and Orion.

Databases can also have a large impact on performance, particularly if the database is accessedacross a network, or has not been indexed properly.

If you can't change your application server, there are performance improvements available, bothby tuning your server, database and through setting certain JIRA options.

6.1.2. Environment Options

6.1.2.1. Virus Checking

If you are experiencing slowness with JIRA, try running JIRA with virus checking disabled. AsJIRA creates many temporary files, virus checking software can slow JIRA dramatically.McAfee's NetShield 4.5 in particular claims to let one exclude folders from scanning, but doesn't

JIRA Documentation

Page 320Copyright © 2002-2005 Atlassian All rights reserved.

Page 321: Jira Manual

actually—upgrade to 7.0.0 to fix this.

6.1.2.2. Network shares

JIRA needs fast access to the local filesystem. If you are hosting JIRA, or its index directory on anetwork share (SMB, NFS etc), this can cause a large loss in performance. Run JIRA with fast localdisk access.

6.1.3. Database Options

6.1.3.1. JDBC drivers

Different JDBC drivers have different performance characteristics. Ensure that you are using thelatest patched version of the JDBC drivers for your database.

6.1.3.2. Databases

JIRA Standalone (and many app-servers) ship with an in-memory database like hsqldb. Usinganother database (eg MySQL, PostgreSQL or Oracle) will usually result in higher performance.

6.1.3.3. Network Latency

The latency between the database server and the server hosting JIRA can be a source of performanceproblems. If the database is hosted on a different machine to JIRA, please check the ping timesbetween the servers.

6.1.3.4. Index your database

JIRA 3.0+ automatically creates database indexes when the database is first created. However if youhave been doing in-place JIRA upgrades from earlier versions (not dropping/recreating the DBtables), your database will not be indexed. Doing a full XML backup and restoring into an emptydatabase will fix this. Additional indexes may be created by hand, but this is usually not necessary.

6.1.4. JDK Options

6.1.4.1. Choose the latest JDK Version

The latest JDKs contain performance optimisations that will improve the performance of JIRA. JIRAuses a lot of reflection, which was greatly improved in the 1.4 release.

6.1.4.2. Use the Server JVM

Sun ships two versions of the JDK, a client version and a server version. They have differentcharacteristics such as memory management and inline optimisations. You may need to explicitlystart your application server like "java -server -jar <app-server-jar>.jar". With JDK 1.5 it is best toleave this unset.

6.1.4.3. Allocate enough Memory

By default, many application servers are not started with enough memory for JIRA to run at anoptimum speed. A lack of memory increases garbage collection time, as it has to be run morefrequently. You may need to start your application server like "java -server -Xms100m -Xmx300m<app-server-jar>.jar". See Increasing JIRA Memory for more details.

JIRA Documentation

Page 321Copyright © 2002-2005 Atlassian All rights reserved.

Page 322: Jira Manual

6.1.5. JIRA Options

6.1.5.1. Enable GZip Compression

JIRA can compress page contents between the server and your browser, resulting in improvedperformance especially over slow connections. Check that GZip compression is enabled inAdministration -> Global Settings -> General Configuration.

6.1.5.2. Removing hsqldb params in JIRA Standalone

If you are using JIRA Standalone modified to use an external database, make sure you delete thehighlighted section in your conf/server.xml, which otherwise results in poor performance:

<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"username="jirauser"password="jirapassword"driverClassName="com.mysql.jdbc.Driver"url="jdbc:mysql://localhost/jiradb?autoReconnect=true"minEvictableIdleTimeMillis="4000"timeBetweenEvictionRunsMillis="5000"/>

6.1.5.3. External User Management

If External User Management is turned on (not the default), JIRA will not cache users & groups,potentially resulting in slow access.

6.1.6. Application Server Options

6.1.6.1. Database Connection pooling.

Obtaining a connection to a database is an expensive operation, and most application serversmaintain a pool of open connections to reduce this overhead. It is worth checking that you have asensible number of connections pooled, sensible expiry times etc. This is configured in your appserver.

Other application server tuning may be of benefit. Consult your application server documentationfor more information.

6.2. Database Indexing

JIRA 3.0 and later creates database indices automatically when the underlying table is created inthe database. This means that if you are doing a fresh install of JIRA 3.0 (or later) you do notneed to create indices manually. If you are upgrading JIRA from an earlier version (e.g. JIRA2.6) and do not wish to create the indices manually, please follow these instructions and recreate(drop and create) JIRA's database (or remove all tables in the database) AFTER successfullyexporting your data and before doing the import into the new version of JIRA. Removing thedatabase will force JIRA to recreate all tables in the database and hence create all requiredindices.

Warning:If upgrading from JIRA 2.6.1 or earlier to JIRA 3.0 (or above), JIRA will not create indices automatically, unless the database isremoved and recreated.

If you do not wish to drop and recreate JIRA's database, you can add the indices manually by

JIRA Documentation

Page 322Copyright © 2002-2005 Atlassian All rights reserved.

Page 323: Jira Manual

running the SQL statements shown below.

The syntax for creating indices differs between databases, so consult your documentation for theyour database. In addition, if you change the database tables or fields that you use inentitymodel.xml, you will need to change the shown SQL statements.

Below is the SQL for creating indices on PostgreSQL (you will probably need to alter this for yourdatabase):

CREATE INDEX action_issue ON jiraaction (issueid, actiontype);

CREATE INDEX chggroup_issue ON changegroup (issueid);

CREATE INDEX chgitem_chggrp ON changeitem (groupid);

CREATE INDEX cf_cfoption ON customfieldoption (CUSTOMFIELD);

CREATE INDEX cfvalue_issue ON customfieldvalue (ISSUE, CUSTOMFIELD);

CREATE INDEX attach_issue ON fileattachment (issueid);

CREATE INDEX subscrpt_user ON filtersubscription (FILTER_I_D, USERNAME);CREATE INDEX subscrptn_group ON filtersubscription (FILTER_I_D, groupname);

CREATE INDEX issue_key ON jiraissue (pkey);

CREATE INDEX issuelink_src ON issuelink (SOURCE);CREATE INDEX issuelink_dest ON issuelink (DESTINATION);CREATE INDEX issuelink_type ON issuelink (LINKTYPE);

CREATE INDEX linktypename ON issuelinktype (LINKNAME);CREATE INDEX linktypestyle ON issuelinktype (pstyle);

CREATE INDEX node_source ON nodeassociation (SOURCE_NODE_ID, SOURCE_NODE_ENTITY);CREATE INDEX node_sink ON nodeassociation (SINK_NODE_ID, SINK_NODE_ENTITY);

CREATE INDEX ntfctn_scheme ON notification (SCHEME);

CREATE INDEX osgroup_name ON groupbase (groupname);

CREATE INDEX mshipbase_user ON membershipbase (USER_NAME);CREATE INDEX mshipbase_group ON membershipbase (GROUP_NAME);

CREATE INDEX osproperty_all ON propertyentry (ENTITY_NAME, ENTITY_ID);

CREATE INDEX osuser_name ON userbase (username);

CREATE INDEX sec_scheme ON schemeissuesecurities (SCHEME);

CREATE INDEX sec_security ON schemeissuesecurities (SECURITY);

CREATE INDEX prmssn_scheme ON schemepermissions (SCHEME);

CREATE INDEX sr_author ON searchrequest (authorname);CREATE INDEX sr_group ON searchrequest (groupname);

CREATE INDEX user_source ON userassociation (SOURCE_NAME);CREATE INDEX user_sink ON userassociation (SINK_NODE_ID, SINK_NODE_ENTITY);

CREATE INDEX workflow_scheme ON workflowschemeentity (SCHEME);

Once you have created the index, you may need to tell your database to recompute its indices. ForPostgreSQL, the command is vacuumdb -U username -z -v database-name. Consultyour database documentation for your database specific command.

6.3. Precompiling JSP pages

JIRA Documentation

Page 323Copyright © 2002-2005 Atlassian All rights reserved.

Page 324: Jira Manual

If you decided to go the extra mile and extend JIRA's build process to precompile JSP pages,keep in mind that the "include" directory in the JIRA web application needs to be excluded fromprecompilation. The reason for this is that the JSP files in the "include" directory are not properJSP files, but are includes that are only meant to be compiled as part of larger JSP pages.

For example, to exclude the JSP pages in the "include" directory when using Maven use the<exclude> sub-element of the <ant:jspc> task, as shown:

<ant:path id="jspc.classpath"><ant:pathelement location="${tomcat.home}/common/lib/jasper-runtime.jar"/><ant:pathelement location="${tomcat.home}/common/lib/jasper-compiler.jar"/><ant:pathelement location="${tomcat.home}/common/lib/servlet.jar"/><ant:path refid="maven-classpath"/><ant:path refid="maven.dependency.classpath"/><ant:pathelement path="${maven.build.dest}"/><ant:pathelement path="${java.home}/lib/tools.jar"/>

</ant:path><ant:jspcpackage="${pom.package}.jsp"destDir="${jspOutDir}"srcdir="${warSource}"uriroot="${warSource}"uribase="/${pom.artifactId}"verbose="2"classpathref="jspc.classpath"><ant:include name="**/*.jsp"/><ant:exclude name="**/includes/**/*.jsp"/>

</ant:jspc>

6.4. Logging & Profiling

6.4.1. Logging

JIRA uses a powerful logging module called log4j. The logging module is configured via thelog4j.properties configuration file which is found in theWEB-INF/classes/log4j.properties under the JIRA web application directory. Thelog4j.properties file JIRA ships with has the default logging levels specified.

The default logging levels can be adjusted (often to get a more detailed error message or a stacktrace). Since JIRA 3.0 it is possible to adjust logging levels of logging categories already definedin the log4j.properties file from JIRA's administration interface. This can be achieved byfollowing these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 324Copyright © 2002-2005 Atlassian All rights reserved.

Page 325: Jira Manual

Link to Administration section

3. Open the "System" sub-menu on the left-hand side if it is not open already and click the"Logging & Profiling" link.

4. You should see a page that lists all the defined log4j categories and their current logging levels.To edit a logging level of a category click the "Edit" link next to the category in the list.

5. Choose the new logging level for the category and click "Update".

Warning:The changes that are made to the logging levels through JIRA's administration interface are NOT persisted and will be lost next time JIRAis restarted. To make persistent changes please edit the log4j.properties file and restart JIRA.

To get a better idea about log4j, for example about how to define new logging categories, and aboutthe format of the log4j.properties file please refer to the documentation on the log4j site.Please note that JIRA needs to be restarted to pick up changes made to the log4j.propertiesfile.

Note:If you application server itself configures logging (JBoss), you may need to remove the log4j.properties file. On some servers (JBoss 3.0),you may also need to remove the entire log4j.jar file to get logging to work.

6.4.2. Profiling

If you are experiencing performance issues with JIRA it is often helpful to see where the slow downsoccur. To do this you can enable profiling and analyse the performance traces that JIRA will producefor every request. An example of a profiling trace is shown below:[Filter: profiling] Turning filter on [jira_profile=on][116ms] - /secure/Dashboard.jspa[5ms] - IssueManager.execute()[5ms] - IssueManager.execute()[5ms] - Searching Issues

[29ms] - IssueManager.execute()[29ms] - IssueManager.execute()[29ms] - Searching Issues[28ms] - Lucene Query[23ms] - Lucene Search

To enable profiling please follow these steps:

1. Login as a user with global administrator access.2. Bring up the administration page by clicking either on the "Administration" link on the top bar or

the title of the Administration box on the dashboard:

Link to Administration section

JIRA Documentation

Page 325Copyright © 2002-2005 Atlassian All rights reserved.

Page 326: Jira Manual

Link to Administration section

3. Open the "System" sub-menu on the left-hand side if it is not open already and click the"Logging & Profiling" link.

4. The screen that appears should inform you whether profiling is turned ON or OFF at themoment. If it is turned off, please click the "Enable profiling" link.

5. JIRA should start generating profiling traces in its log.

To disable profiling simply click the "Disable profiling" link.

6.5. Debugging Errors

If you encounter any problems using or setting up JIRA, please let us know — we're here to help!The best way to get help is to mail the mailing list, where Atlassian staff and JIRA users cananswer your questions.

Alternatively you can raise a support request.

If you feel you have encountered a bug in JIRA, or wish to request a feature, please file an issue.It is a good idea to first scan JIRA's Popular Issues to prevent duplicates.

Whether a support request or a bug, we often need more information than just "this featuredoesn't work". Usually an error message is reported on the console or via log4j. If you couldinclude the error message in your email or bug report, it would be most appreciated! Please alsomention the version of JIRA involved.

Sometimes it is necessary to adjust JIRA's logging levels to get a more detailed error message ora stack trace. Please consult the logging section of the documentation for information on how toachieve this.

6.6. Thread Dump

Occassionally, JIRA may appear to 'freeze' during execution of an operation. During these times,it is helpful to retrieve a thread dump - a log containing information about currently runningthreads and processes within the Java Virtual Machine. This document describes the stepsnecessary to retrieve a thread dump.

The steps necessary to retrieve the thread dump are dependant on the operating system JIRA isrunning in - please follow the appropriate steps:

• Windows Environment• UNIX Environment

6.6.1. Windows Environment

1. In the Command Console window where JIRA is running, open the properties dialog box byright clicking on the title bar and selecting "Properties".

2. Select the Layout tab.3. Under Screen Buffer Size, set the Height to 3000.

JIRA Documentation

Page 326Copyright © 2002-2005 Atlassian All rights reserved.

Page 327: Jira Manual

Console Window Properties4. Click OK.5. With the same command console in focus, press CTRL-BREAK. This will output the thread

dump to the command console.6. Scroll back in the command console until you reach the line containing "Full thread dump". A

sample thread dump is available here.7. Right click the title bar and select Edit -> Mark. Highlight the entire text of the thread dump.8. Right click the title bar and select Edit -> Copy. The thread dump can then be pasted into a text

file.

JIRA Documentation

Page 327Copyright © 2002-2005 Atlassian All rights reserved.

Page 328: Jira Manual

Console Window Copy Paste

Note:It is not possible to retrieve a thread dump while running JIRA as a service. In order to retrieve a thread dump, we recommend notrunning JIRA as a service and starting JIRA from a console so as the thread dump can be retrieved.

6.6.2. UNIX Environment

1. Identify the java process that JIRA is running in. This can be achieved by running acommand similar to:ps -ef | grep javaThe process will appear similarly as follows:keithb 910 873 1 17:01 pts/3 00:00:18 /usr/java/jdk/bin/java -Xms128m -Xmx256m-Xms128m -Xmx256m -Djava.awt.headless=true -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager-Djava.awt.headless=true -Djava.endorsed.dirs=/tmp/atlassian-jira-enterprise-3.5.2-standalone/common/endorsed-classpath :

2. In order to retrieve the thread dump, execute the commandkill -3 <pid>where pid is the process id - in this case 910.

3. The thread dump is logged to the console in which JIRA was started. A sample thread dumpis available here.

6.7. Downgrading from JIRA Enterprise to JIRA Professional

6.7.1. Introduction

Occasionally people start out evaluating JIRA Enterprise, and then decide that they will not needthe extra features, and switch to JIRA Professional.

JIRA Documentation

Page 328Copyright © 2002-2005 Atlassian All rights reserved.

Page 329: Jira Manual

While JIRA can automatically upgrade data from Professional to Enterprise by adding the additionaltables, it cannot automatically do the opposite. Downgrading data from Enterprise to Professionalrequires some manual intervention, described in this document.

6.7.2. Step 1: Ensure no Enterprise features are used

Log into JIRA as a user with permission jira-administrator. In the administration section,check that:

• Issue Security Scheme is set to None.• Field Configuration Scheme is set to System Default Field Configuration• Issue Type Screen Scheme is set to Default Issue Type Screen Scheme.• Workflow Scheme is set to None• Project Category is set to NoneAlso ensure that in the permission schemes, only "groups" are assigned permissions (ie, no "CurrentReporter", "Single User", "Project Lead" and "Current Assignee"

6.7.3. Create an XML backup

In the administration section, click Backup Data to XML and create an uncompressed XMLbackup.

6.7.4. Delete license key

Open the saved XML dump, locate the section containing OSPropertyString tags, and specificallythe lines recording the license key, for example:

<OSPropertyString id="10012"value="QmSSppmNrnRemqoaaaXONrrNRMQONpqqqTsUwTXvuuSVoreeeemsqostsnmsunUUnmsqostsnmsqnUU9kabmbkaakq"/>

<OSPropertyString id="10013"value="NNORRIhehJHuopbJHahmlCIOpNUquvoaWtvMnSqAcaussss2KqaVqLs<18T3yRGL9AaQ12KlGXNCsNU9K7uYRPqKB<K"/>

Replace the values within the double quotes with:

<OSPropertyString id="10012"value="mNxwOOpqNMnqnNRonTWRpNqOoORQnNNPsSswxSTtStvTTMuXUWuxTQxtxXSswqtUUnmsurpmqmmmmmUUnmsurpmqmmmmmUUGiXZbeliaboWbumfobaWifZbkpb"/><OSPropertyString id="10013"value="OqPNWKIpAHlnPweAodiBiOpuPNPUBMMxPGwgcFPehrlPwOmi2K6aWBoeqgwqTRPQU3n23f2KYGb5TyaE8G9YQv1gBNKT"/>

(Make sure the original id attributes remain the same - "10012" and "10013" are just examples)

6.7.5. Import and reenter license key

Now shut down the JIRA Enterprise, and start up a JIRA Professional instance. Import the XMLsaved in the last step.

In the footer, JIRA will claim that has an expired license. Log in as an administrator and enter yourProfessional license key.

6.8. Downgrading from JIRA Professional to JIRA Standard

6.8.1. Introduction

Occasionally people start out evaluating JIRA Professional, and then decide that they will not needthe extra features, and switch to JIRA Standard.

While JIRA can automatically upgrade data from Standard to Professional by adding the additionaltables, it cannot automatically do the opposite. Downgrading data from Professional to Standard

JIRA Documentation

Page 329Copyright © 2002-2005 Atlassian All rights reserved.

Page 330: Jira Manual

requires some manual intervention, described in this document.

6.8.2. Step 1: Ensure no Professional features are used

Log into JIRA as a user with permission jira-administrator. In the administrationsection, check that no projects have more than one workflow, more than one CVS repository perproject, shared filters, or multiple dashboards.

6.8.3. Create an XML backup

In the administration section, click Backup Data to XML and create an uncompressed XMLbackup.

6.8.4. Delete license key

Open the saved XML dump, locate the section containing OSPropertyString tags, andspecifically the lines recording the license key, for example:

<OSPropertyString id="10012"value="QmSSppmNrnRemqoaaaXONrrNRMQONpqqqTsUwTXvuuSVoreeeemsqostsnmsunUUnmsqostsnmsqnUU9kabmbkaakq"/>

<OSPropertyString id="10013"value="NNORRIhehJHuopbJHahmlCIOpNUquvoaWtvMnSqAcaussss2KqaVqLs&lt;18T3yRGL9AaQ12KlGXNCsNU9K7uYRPqKB&lt;K"/>

Replace the values within the double quotes with:

<OSPropertyString id="10012"value="rRNSvoPoPNpoMqMoroWXQpnNnqOoqqOrnuUSwXWSXswvUXPvVSUVWuoSwTvUtxnmvUUnmsvoonsmmmmmUUnmsvoonsmmmmmUUGiXZbeliaboWbumfobaWifZbkpb"/><OSPropertyString id="10013"value="ROpOODCPufuglwtAFMICsMHhaoPumlNsONvGKBOMrvcOSEimj2L02TK9aBweqbvDsuPUemta2KlQPAax9Yk8&lt;zoI9PGrf6"/>

(Make sure the original id attributes remain the same - "10012" and "10013" are just examples)

6.8.5. Import and reenter license key

Now shut down the JIRA Professional, and start up a JIRA Standard instance. Import the XMLsaved in the last step.

In the footer, JIRA will claim that it has an expired license. Log in as an administrator and enteryour Standard license key.

7. Extending JIRA

7.1. Extending JIRA

JIRA is very flexible, and has a number of extension points where JIRA's data can be queried orits functionality extended. You can also download the JIRA Plugin Development Kit. Thiscontains full source code for seven working plugins (and growing), skeleton project templates forcreating your own plugins, full JIRA API documentation and all library dependencies.

Custom Field Types JIRA comes with various custom field typesdefined. New types can be written and pluggedinto JIRA. See the Writing Custom Field TypesTutorial for more information.

Portlets New portlets can be created by writing a Javaclass, a template and an XML descriptor file,packaged as a JIRA plugin. See How To Createa JIRA Portlet for more information.

JIRA Documentation

Page 330Copyright © 2002-2005 Atlassian All rights reserved.

Page 331: Jira Manual

Reports JIRA comes with various reports built-in. Usingthe plugin system, new reports can be written,providing new ways of viewing and summarisingJIRA's data.

Workflow functions and conditions JIRA's issue workflow (states and state transitions anissue can go through) can be customized through theweb interface (see the workflow documentation. Theworkflow engine (OSWorkflow) provides hookswhere you can plug in your own behaviour:

• Run arbitrary Java when a certain transitionoccurs, via post-functions

• Limit visibility of transitions to certain users, viaconditions

• Validate input on transition screens (eg. incomments), via validators

See the guide to creating custom workflow elementsfor how to write your own workflow post-functions,conditions and validators. Once written, these can bepackaged as plugins and reused.

Issue and Project Tabs When viewing an issue, some issue information(comments, change history) is displayed in tabs:

Issue tab panels

Likewise, the 'Browse Project' page contains tabpanels displaying project information:

Project tab panels

By writing a plugin, you can add new issue or projecttab panels to JIRA. For instance, you may wish todisplay project/issue data pulled in from an externalsource. This is how JIRA's Subversion and Perforceintegration works.

See the plugin guide for more information on writingthese plugin types.

Listeners JIRA has a complete event subsystem which firesevents whenever anything happens. For example anISSUE_CREATED event is fired whenever an issueis created.

A listener is just a class which implements aJiraListener interface and is called wheneverevents occur in JIRA. Using those events, you canthen perform any action you want. For example theemail sent by JIRA is driven by theMailListener.

This is useful when you want to drive or affectexternal systems from events which occur withinJIRA - usually used to push data into outside

JIRA Documentation

Page 331Copyright © 2002-2005 Atlassian All rights reserved.

Page 332: Jira Manual

systems.

For more information, read the listenersdocumentation.

Services Services are classes which implement theJiraService interface. When installed, youspecify an update period and JIRA will call therun() method of your service periodically.

A sample service is provided calledPOPCommentService. This service checks aparticular POP mailbox periodically and if it findsmessages, tries to extract an issue key from thesubject. If the subject contains a key, the body of themail is added as a comment to the message.

Services are useful when you want to periodicallypull data into JIRA from outside systems.

For more information, see the services guide.

SOAP and XML-RPC remote interfaces JIRA has a growing SOAP and XML-RPC interface.This enables you to drive JIRA automatically fromexternal systems. For example you can have a Javaprogram, Perl script or C# client add issues to JIRA.See the JIRA RPC overview for general information.For building RPC clients, check out the SOAP clienttutorial and XML-RPC client tutorial. New RPCendpoints can also be added to JIRA as plugins - seeRPC Endpoint Plugins.

Java JIRA has a full set of Java APIs that can be used toupdate information with in JIRA.You can view the API here. JIRA commercialcustomers get full access to the JIRA source (seebottom of the downloads page), so you can modifyJIRA itself if necessary. See the Building JIRA fromSource page for more information.

7.2. Listeners

Listeners are unique to JIRA, and a very powerful way to extend it.

JIRA has a complete event subsystem which fires events whenever anything happens inside theapplication. For example an ISSUE_CREATED event is fired whenever an issue is created.

A Listener is a class that implements one of the Listener interfaces. It is then called wheneverevents occur in JIRA. Using those events, you can then perform any action you want. Forexample the email sent by JIRA is driven by the MailListener.

Listeners are most useful when you want to drive or affect external systems from events whichoccur within JIRA.

7.2.1. Listener Interfaces

There are currently two different concrete Listeners within JIRA (both of which extend the baseJiraListener interface).

com.atlassian.jira.event.JiraListener The base interface which all other JIRA listener

JIRA Documentation

Page 332Copyright © 2002-2005 Atlassian All rights reserved.

Page 333: Jira Manual

interfaces extend. Covers core listener properties likeuniqueness, description, parameters etc.

API doc

com.atlassian.jira.event.issue.IssueEventListenerThe main listener interface in JIRA, used wheneveranything happens to an issue.

API doc

com.atlassian.jira.event.user.UserEventListener This listener is called whenever anything happens toa user within JIRA.

API doc

7.2.2. Example Listeners

The examples provided may be freely used and modified for use in your own environment. Thesource of all examples is available and should give you good overview of how simple it is to writeyour own listeners. Both example listeners are included with JIRA 2.1, and both implementUserEventListener and IssueEventListener.

DebugListener (source)This is a very simple listener that prints events and their content to System.out whenever they arereceived.

To test this listener, add a listener with the classcom.atlassian.jira.event.listeners.DebugListener.

MailListener (source)This listener is how mail notifications are currently sent from within JIRA, and a good exampleof a more complex listener. It basically listens for events, and turns them into email notificationsusing Velocity templates to generate the mail bodies.

This listener is usually always turned on in JIRA - see Email Notifications for more details. Ifyou want to write more complex or more specific notifications, you can disable the internalMailListener and add your own.

Other examples of useful tasks that can be accomplished with listeners are:

Send SMS or IM notificationsA listener could easily send notifications for various events via SMS or instantmessenger (eg ICQ or AIM) - or anywhere that you have a Java library to sendmessages.Group notifications:A listener could notify certain groups of issue changes, depending on the content of theissue. For example any issue containing "windows" in the environment could notify your"windows-developers" group.

7.2.3. Registering a Listener

You register a listener through the Listeners section of the Administration tab.

Registering your listener is a three step process:

1. Make sure your listener class is in the classpath where JIRA can see it - the best locations areusually the WEB-INF/classes or WEB-INF/lib (as a JAR) directories within the JIRAweb application.

JIRA Documentation

Page 333Copyright © 2002-2005 Atlassian All rights reserved.

Page 334: Jira Manual

2. Enter a Name (a nice name for this listener) and Class (the fully qualified class of yourlistener) for your listener and click Add.

3. The listener will now be added. Click Edit for your listener to edit its properties.

7.2.4. Editing Listener Properties

At any time you can edit a listeners properties by clicking Edit for that listener in the Listenerssection of the Administration tab.

7.2.5. Removing a Listener

To remove a listener, just click Del for that listener in the Listeners section of theAdministration tab.

7.3. Services

A service is a class that runs periodically within JIRA. Since a service runs inside JIRA, it has theability to use all of the JIRA API - and as it is written in Java it can use any Java libraries.

Services are useful because they enable you to integrate with external systems by pulling datainto JIRA periodically. JIRA comes with a number of pre-written services, and custom servicescan be written and plugged in at runtime.

7.3.1. Registering a Service

Services are set up as follows.

1. For custom-written services, make sure your service class is in the classpath where JIRA cansee it - the best locations are usually the WEB-INF/classes or WEB-INF/lib (as a JAR)directories within the JIRA web application.

2. Login as a user with global administrator access.3. Bring up the administration page by clicking either on the "Administration" link on the top

bar or the title of the Administration box on the dashboard:

Link to Administration section

Link to Administration section

4. Under the "System" sub-menu on the left, click the "Services" link.5. Fill out the Add Service form with the following parameters

Namea nice name for this serviceClassthe fully qualified class of your service. Will likely be of the formcom.atlassian.jira.service.services.type.TypeService. See Sample services for providedservice class names.

JIRA Documentation

Page 334Copyright © 2002-2005 Atlassian All rights reserved.

Page 335: Jira Manual

Delaythe delay (in minutes) between service runs

For example, adding a PopService:

Add service

Now click Add Service

6. This will bring up the "Edit Service" screen to configure the service. Depending on the service,you may now be required to specify a MessageHandler, a helper class that processes emailmessages. MessageHandlers are configured with a parameter string, a comma-separated list ofname=value pairs. Consult the tables below as to what parameters each MessageHandler accepts.Here we show a CreateIssueHandler being attached to a PopService

JIRA Documentation

Page 335Copyright © 2002-2005 Atlassian All rights reserved.

Page 336: Jira Manual

Editing a service

7.3.2. Editing Service Properties

At any time you can edit a service's properties by clicking Edit for that service in the Servicessection of the Administration tab.

7.3.3. Mail Service Properties

In addition to Message Handlers, the mail services POP Service and IMAP Service can be furtherconfigured with further properties on how the mail is found and handled.

Forward EmailsIf the mail service is unable to handle a message you can define an email address to forwardthese messages to. Just add the desired email address into the "ForwardEmail" textbox.

Note:You will need to configure a SMTP mail server before this functionality can be used.

SSLThe mail service can be configured to connect to the email server using an SSL connection.To do this select the appropriate SSL connection in the "Use SSL" select list. If you do notwant JIRA to use SSL select "No SSL"

If you are using SSL, you will need to preload the IMAPS/POPS server's public key in JIRA(actually, the Java virtual machine running JIRA). See Connecting to SSL Services forinformation on how to do this.

Folder (IMAP Only)For the IMAP Service it is possible to specify the folder you wish JIRA to read whenscanning for messages. To do this add the desired folder name to the "Folder" textfield.

Note:If a folder is not specified the mail service will default to "INBOX".

7.3.4. Removing a Service

JIRA Documentation

Page 336Copyright © 2002-2005 Atlassian All rights reserved.

Page 337: Jira Manual

To remove a service, click Del for that service in the Services section of the Administration tab.

7.3.5. Sample Services

The sample services provided may be freely used and modified for use in your own environment.The source of all sample services is available and should give you good overview of how simple it isto write your own services. All sample services are included with JIRA, and need only be configuredto be used.

Export Service (source)This sample service is a very simple service - useful for periodically backing up JIRA. TheExportService exports all data from JIRA every time it is run into a directory supplied as aparameter. The export files are timestamped, thus the service can act as a backup system.

To test this service, add a service with the classcom.atlassian.jira.service.services.export.ExportService.

POP Service (source)The POP service reads messages from a defined POP3 mail box, and then performs operationswithin JIRA based on the message contents. A MessageHandler (see below for moreinformation) is configured for each instance of the POP Service, which determines how themessage is handled.

To test this service, add a service with the classcom.atlassian.jira.service.services.pop.PopService and configure the POP details and messagehandler in the properties of the service.

To make the POP service even more useful, you can connect it with the email notifications sentby JIRA. Simply set the FROM address in the MailListener to be the same address as the POPmailbox being monitored. This allows you to do things like reply to email notifications and haveyour replies added as comments on the issue.

IMAP Service (source)Similar to POP service, except that it reads from an IMAP mailbox's "INBOX" instead. Like thePOP service, it removes emails after reading.

To test this service, add a service with the classcom.atlassian.jira.service.services.imap.ImapService and configure the IMAP details andmessage handler in the properties of the service.

File Service (source)The File service is very much like the POP service above, except that instead of reading emailsfrom a POP mailbox, they are read from a directory on disk. This is useful because you do notneed an anonymous POP mail box (which could be a potential security risk) to use it. Instead youcan simply get your mail server to dump incoming email messages into a particular directory,which the File service scans periodically.

The setup of this service is identical to the POP Service above, except that the service class iscom.atlassian.jira.service.services.file.FileService and the service is configured with thedirectory to watch instead of the POP mailbox details. Both File and POP services can use thesame MessageHandlers.

JIRA Service classes must all extend com.atlassian.jira.service.JiraService. Most do so by extendingcom.atlassian.jira.service.AbstractService or some more specialized subclass.

7.3.6. Message Handlers

JIRA Documentation

Page 337Copyright © 2002-2005 Atlassian All rights reserved.

Page 338: Jira Manual

POPService, IMAPService and FileService above use MessageHandlers (API doc) to performoperations within JIRA based on the format of incoming email messages.

You can design your own MessageHandlers to integrate JIRA with your own processes, and plugthem into either of these two services via the Administration interface.

MessageHandlers are configured with a comma-separated list of name-value pairs, known as thehandler parameters.

There are a number of default message handlers that ship with JIRA, described below:

7.3.6.1. CreateIssueHandler

com.atlassian.jira.service.util.handler.CreateIssueHandler | API doc | Source

This message handler creates a new issue for each incoming message.

Parameter Meaning Value

project Default project where newissues are created.

Project code, e.g. JRA

issuetype Default type for new issues. Integer representing issue type:

1. Bug2. New Feature3. Task4. Improvement

reporterusername Username of default reporter, ifsender not recognized.

JIRA username, e.g. admin

createusers If a message comes fromunrecognized address, create anew JIRA user with the username and email address set tothe 'From' address of themessage. The password for thenew user is randomlygenerated, and an email is sentto the new user informing themabout their new account inJIRA.Note: this parameter is notcompatible withreporterusername. Ifcreateusers is set to true,and the reporterusernameis also supplied, users will becreated if they cannot be foundusing the from addresses of thereceived messages. That is,the reporterusername willbe ignored.By default (if not supplied),createusers is set to false.

true or false

notifyusers This parameter is only used ifcreateusers is set to true. Ifnotifyusers is set to false theywill not receive a notificationthat their account has beencreated via email. The default

true or false

JIRA Documentation

Page 338Copyright © 2002-2005 Atlassian All rights reserved.

Page 339: Jira Manual

value is true to preserve thebehaviour before thisparameter was added.By default (if not supplied),notifyusers is set to true.

catchemail If set, only emails to thespecified recipient (To:, Cc:)are processed.

E.g. [email protected]

ccassignee If an email has a Cc addresslisting an assignable useralready present in JIRA, bydefault JIRA will assign theissue to that user. In JIRA 3.1and above, if you do not wantthis behaviour, set ccassigneeto false.By default (if not supplied),ccassignee is set to true.

true or false

Table 1: CreateIssueHandler parameters

7.3.6.2. CreateOrCommentHandler

com.atlassian.jira.service.util.handler.CreateOrCommentHandler | API doc | Source

This message handler creates a new issue, or adds a comment to an existing issue. If the subjectcontains an issue key, the message is added as a comment to that issue. If no issue key is found, anew issue is created in the default project.

Parameter Meaning Value

project Default project where newissues are created.

Project code, e.g. JRA

issuetype Default type for new issues. Integer representing issue type:

1. Bug2. New Feature3. Task4. Improvement

stripquotes If set (to anything), quoted textis removed from comments.

(anything)

reporterusername Username of default reporter, ifsender not recognized.

JIRA username, e.g. admin

createusers If a message comes fromunrecognized address, create anew JIRA user with the username and email address set tothe 'From' address of themessage. The password for thenew user is randomlygenerated, and an email is sentto the new user informing themabout their new account inJIRA.Note: this parameter is notcompatible withreporterusername. Ifcreateusers is set to true,

true or false

JIRA Documentation

Page 339Copyright © 2002-2005 Atlassian All rights reserved.

Page 340: Jira Manual

and the reporterusernameis also supplied, users will becreated if they cannot be foundusing the from addresses of thereceived messages. That is,the reporterusername willbe ignored.By default (if not supplied),createusers is set to false.

notifyusers This parameter is only used ifcreateusers is set to true. Ifnotifyusers is set to false theywill not receive a notificationthat their account has beencreated via email. The defaultvalue is true to preserve thebehaviour before thisparameter was added.By default (if not supplied),notifyusers is set to true.

true or false

catchemail If set, only emails to thespecified recipient (To:, Cc:,Bcc:) are processed.

E.g. [email protected]

ccassignee If an email has a Cc addresslisting an assignable useralready present in JIRA, bydefault JIRA will assign theissue to that user. In JIRA 3.1and above, if you do not wantthis behaviour, set ccassigneeto false.By default (if not supplied),ccassignee is set to true.

true or false

Table 1: CreateOrCommentHandler parameters

7.3.6.3. FullCommentHandler

com.atlassian.jira.service.util.handler.FullCommentHandler | API doc | Source

This message handler creates a comment based on the entire body of the email received.

The issue to use is chosen from the first issue key found in the email subject. The author of thecomment is taken from the from address of the email.

Parameter Meaning Value

reporterusername Username of default reporter, ifsender not recognized.

JIRA username, e.g. admin

createusers If a message comes fromunrecognized address, create anew JIRA user with the username and email address set tothe 'From' address of themessage. The password for thenew user is randomlygenerated, and an email is sentto the new user informing themabout their new account inJIRA.

true or false

JIRA Documentation

Page 340Copyright © 2002-2005 Atlassian All rights reserved.

Page 341: Jira Manual

Note: this parameter is notcompatible withreporterusername. Ifcreateusers is set to true,and the reporterusernameis also supplied, users will becreated if they cannot be foundusing the from addresses of thereceived messages. That is,the reporterusername willbe ignored.By default (if not supplied),createusers is set to false.

notifyusers This parameter is only used ifcreateusers is set to true. Ifnotifyusers is set to false theywill not receive a notificationthat their account has beencreated via email. The defaultvalue is true to preserve thebehaviour before thisparameter was added.By default (if not supplied),notifyusers is set to true.

true or false

catchemail If set, only emails to thespecified recipient (To:, Cc:,Bcc:) are processed.

E.g. [email protected]

Table 1: FullCommentHandler parameters

7.3.6.4. NonQuotedCommentHandler

com.atlassian.jira.service.util.handler.NonQuotedCommentHandler | API doc | Source

This message handler also creates a comment, but only uses the "non quoted" lines of the emailbody. A quoted line is any line that starts with">" or "|".

The issue to use is chosen from the first issue key found in the email subject. The author of thecomment is taken from the from address of the email.

Parameter Meaning Value

reporterusername Username of default reporter, ifsender not recognized.

JIRA username, e.g. admin

createusers If a message comes fromunrecognized address, create anew JIRA user with the username and email address set tothe 'From' address of themessage. The password for thenew user is randomlygenerated, and an email is sentto the new user informing themabout their new account inJIRA.Note: this parameter is notcompatible withreporterusername. Ifcreateusers is set to true,and the reporterusername

true or false

JIRA Documentation

Page 341Copyright © 2002-2005 Atlassian All rights reserved.

Page 342: Jira Manual

is also supplied, users will becreated if they cannot be foundusing the from addresses of thereceived messages. That is,the reporterusername willbe ignored.By default (if not supplied),createusers is set to false.

notifyusers This parameter is only used ifcreateusers is set to true. Ifnotifyusers is set to false theywill not receive a notificationthat their account has beencreated via email. The defaultvalue is true to preserve thebehaviour before thisparameter was added.By default (if not supplied),notifyusers is set to true.

true or false

catchemail If set, only emails to thespecified recipient (To:, Cc:,Bcc:) are processed.

E.g. [email protected]

Table 1: NonQuotedCommentHandler parameters

7.3.6.5. RegexCommentHandler

com.atlassian.jira.service.util.handler.RegexCommentHandler | API doc | Source

This message handler creates a comment from an email body - but ignores any part of the emailbody past a specified marker or separator. For mail systems like Lotus Notes and Outlook, emailsare separated from the quoted email by some predictable text like "---- Original Message ----" or"Extranet\n email.address/DOM/REG/CONT/CORP@CORPMAIL" TheRegexCommentHandler can take any valid regular expression - and in fact filter quoted mailsfrom various different mail systems simultaneously.

• If the pattern is found, it returns the text before the 1st match - and discards the rest of theemail body

• If the pattern is not found, it returns the email body unchanged• If the regex is not specified, it returns the email body unchanged• If there is any error (i.e. regex expression error), it returns the email body unchanged

Parameter Meaning Value

reporterusername Username of default reporter, ifsender not recognized.

JIRA username, e.g. admin

createusers If a message comes fromunrecognized address, create anew JIRA user with the username and email address set tothe 'From' address of themessage. The password for thenew user is randomlygenerated, and an email is sentto the new user informing themabout their new account inJIRA.Note: this parameter is notcompatible withreporterusername. If

true or false

JIRA Documentation

Page 342Copyright © 2002-2005 Atlassian All rights reserved.

Page 343: Jira Manual

createusers is set to true,and the reporterusernameis also supplied, users will becreated if they cannot be foundusing the from addresses of thereceived messages. That is,the reporterusername willbe ignored.By default (if not supplied),createusers is set to false.

notifyusers This parameter is only used ifcreateusers is set to true. Ifnotifyusers is set to false theywill not receive a notificationthat their account has beencreated via email. The defaultvalue is true to preserve thebehaviour before thisparameter was added.By default (if not supplied),notifyusers is set to true.

true or false

catchemail If set, only emails to thespecified recipient (To:, Cc:,Bcc:) are processed.

E.g. [email protected]

splitRegex Regular expression matchingthe text separating the mailfrom any previous mails

E.g. \\----\s*OriginalMessage\s*---- orExtranet[\n\r]*email.address/DOM/REG/CONT/CORP@CORPMAIL

Table 1: RegexCommentHandler parameters

7.3.6.6. CVSLogHandler

com.atlassian.jira.service.util.handler.CVSLogHandler | API doc | Source

This message handler parses CVS Log messages and adds the relevant sections as a comment.

The comment is added to any issue whose key is mentioned in the CVS commit message.

For instance if you commit to CVS with the message "This commit fixes JRA-57 and JRA-58.", acomment will be added to issues JRA-57 and JRA-58.

The body of the comment includes the commit message entered by the developer and the filesinvolved in the commit.

Warning:JIRA no longer uses CVSLogHandler for its CVS integration - this service is kept here purely as an example.

To use this message handler, setup your CVS server to email commit messages using something likeSyncMail.

Parameter Meaning Value

reporterusername Username of default reporter, ifsender not recognized.

JIRA username, e.g. admin

createusers If a message comes fromunrecognized address, create anew JIRA user with the username and email address set tothe 'From' address of the

true or false

JIRA Documentation

Page 343Copyright © 2002-2005 Atlassian All rights reserved.

Page 344: Jira Manual

message. The password for thenew user is randomlygenerated, and an email is sentto the new user informing themabout their new account inJIRA.Note: this parameter is notcompatible withreporterusername. Ifcreateusers is set to true,and the reporterusernameis also supplied, users will becreated if they cannot be foundusing the from addresses of thereceived messages. That is,the reporterusername willbe ignored.By default (if not supplied),createusers is set to false.

notifyusers This parameter is only used ifcreateusers is set to true. Ifnotifyusers is set to false theywill not receive a notificationthat their account has beencreated via email. The defaultvalue is true to preserve thebehaviour before thisparameter was added.By default (if not supplied),notifyusers is set to true.

true or false

catchemail If set, only emails to thespecified recipient (To:, Cc:,Bcc:) are processed.

E.g. [email protected]

Table 1: CVSLogHandler parameters

7.3.7. Building Services from source

To build any of the linked sample code:

• If you have JIRA Standalone, download to the external-source/src/ directory, and read theinstructions in external-source/README.txt) for build instructions.

• If you have the JIRA WAR/Webapp distribution, download the source to the src/ directory.The code will be compiled into the webapp when build.sh/build.bat is run.

7.4. Jelly Tags

Jelly is a scripting and templating language from Apache's Jakarta project. It is similar to Ant, inthat scripts are XML, and each tag maps to a Java class, but has a more sophisticated internalpipeline model for tag interaction, much like JSP taglibs. See the Jelly website for more details.

JIRA comes with a number of Jelly tags implementing core operations in JIRA. This provides ascriptable interface to JIRA. There are many possible uses for JIRA Jelly tags, the most commonbeing importing data into JIRA from other systems, and automating common admin tasks (seethe examples).

7.4.1. Enabling Jelly

JIRA's Jelly support is disabled by default, as it is a potential security hazard. To enable Jelly

JIRA Documentation

Page 344Copyright © 2002-2005 Atlassian All rights reserved.

Page 345: Jira Manual

support, set the jira.jelly.on system property when starting your app server. System properties areset with parameters to the java command; eg. java -Djira.jelly.on=true .... How toset this property depends on your app server. For example, with Tomcat (JIRA standalonedistribution), set the environment variable JAVA_OPTS=-Djira.jelly.on=true, or when runningJIRA Standalone as a service, set the service JVM parameter.

7.4.2. Using Jelly

JIRA Jelly scripts can be run by pasting the Jelly script into the Jelly Runner, located in theAdministration section of JIRA. Alternatively, acom.atlassian.jira.jelly.service.JellyService Service can be set up to run ascript periodically.

Scripts are generally of the form:

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><!--

Add your own Jelly XML here--></JiraJelly>

JIRA Enterprise has a few extra tags available; to use them, the outer tag should instead be:

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib"><!--

Add your own Jelly XML here--></JiraJelly>

In addition to the JIRA tags, you can use tags from the email, http, soap, sql, and core Jelly taglibs.More can be added by the user if necessary.

Many of JIRA's Jelly tags set context variables, so subsequent tags can refer to their output bydereferencing the context variable (eg. ${jira.new.username}). Other tags let you explicitlyspecify the name of a variable to store some output in. Eg., <jira:CreateUser> has issueKeyVarand issueIdVar parameters:<jira:CreateIssue project-key="TP" summary="Issue One" issueKeyVar="issuekey" issueIdVar="issueid"/>

Raised issue ${issuekey} with id ${issueid}

Note that the variable is only set after the tag is closed, not inside the tag.

The list of currently available tags:• jira:AddComment• jira:AddComponent• jira:SelectComponentAssignees• jira:AddUserToGroup• jira:AddVersion• jira:CreateGroup• jira:AssignIssue• jira:CreateIssue• jira:LinkIssue• jira:TransitionWorkflow• jira:CreateProject• jira:CreateUser• jira:RemoveUser• jira:CreatePermissionScheme• jira:AddPermission• jira:Login• jira:CreateCustomField

JIRA Documentation

Page 345Copyright © 2002-2005 Atlassian All rights reserved.

Page 346: Jira Manual

• jira:AddFieldToScreen• jira:AttachFile

7.4.3. jira:AddComment

This function adds a comment to an Issue.

Attribute name Type Default value Description

issue-key string The issue to add thecomment to (required).

commenter string Currently logged inuser

Username of the userto make the comment(Must have browseand commentpermissions).

comment string Comment to be addedto the issue (required).

commentLevel string none Name of group thatcan see this comment.

created string Current Date/Time Date/Time theComment was createdin format yyyy-MM-ddhh:mm:ss.0

Table 1: Attributes

7.4.3.1. Examples

Create comment

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:AddComment comment="Issue comment" issue-key="ABC-1"commentLevel="admin-group"/></JiraJelly>

Create Issue and Comment<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateIssue project-key="TP" issueType="Bug" summary="Issue summary" issueKeyVar="key"/><jira:AddComment issue-key="${key}" comment="A comment on ${key}"/>

</JiraJelly>

7.4.4. jira:AddComponent

Adds a component to a project.

Attribute name Type Default value Description

project-key string The key of the projectyou want to add thecomponent to (notrequired if nestedinside ajira:CreateProject tag).

name string Name of thecomponent (required).

description string Description of the

JIRA Documentation

Page 346Copyright © 2002-2005 Atlassian All rights reserved.

Page 347: Jira Manual

component.

componentLead string For JIRA Enterpriseonly. The username ofthe Component's lead.Leave blank for nolead.

Table 1: Attributes

7.4.4.1. Examples

Create Component

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:AddComponent project-key="ABC" name="Comp 1" description="Comp 1 description"/></JiraJelly>

Create Component in a Project

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateProject key="ABC" name="A Project" lead="logged-in-user"><jira:AddComponent name="Comp 1"/></jira:CreateProject></JiraJelly>

Create Component with a Component Lead (Enterprise-only)

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:AddComponent project-key="ABC" name="Comp 1" description="Comp 1 with lead" componentLead="user-name"/></JiraJelly>

7.4.5. jira:SelectComponentAssignees

Selects the default assignees for newly created issues of the component. This tag is only available inJIRA Enterprise.

Attribute name Type Default value Description

project-key string The key of the projectyou want to add thecomponent to(required).

componentName string Name of thecomponent (required).

assigneeType string Default assignee type(required).

Assignee Types

projectDefault

componentLead

projectLead

unassigned

Table 1: Attributes

7.4.5.1. Examples

JIRA Documentation

Page 347Copyright © 2002-2005 Atlassian All rights reserved.

Page 348: Jira Manual

Select a Component Assignee

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib"><jira:SelectComponentAssignees project-key="ABC" componentName="Comp 1" assigneeType="componentLead"/></JiraJelly>

7.4.6. jira:AddUserToGroup

Makes a user a member of a Group. Adds the username and/or group name into the context ifspecified.

Attribute name Type Default value Description

username string Username to add toGroup (required if notin a jira:CreateUsertag).

group-name string Group to add User to(required if not in ajira:CreateGroup tag).

Table 1: AttributesContext Variable Type Description

jelly.new.username string Username is set in the contextif specified in the tag.

jelly.group.name string Group name is set in thecontext if specified in the tag.

Table 2: Context Variables

7.4.6.1. Examples

Add User to Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:AddUserToGroup username="new-user" group-name="new-group"/></JiraJelly>

Add New User to Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateUser username="new-user" password="password" confirm="password"fullname="Full name" email="[email protected]"><jira:AddUserToGroup group-name="new-group"/></jira:CreateUser></JiraJelly>

Add User to New Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateGroup group-name="new-group"><jira:AddUserToGroup username="new-user"/></jira:CreateGroup></JiraJelly>

Add New User to New Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateUser username="new-user" password="password" confirm="password"

JIRA Documentation

Page 348Copyright © 2002-2005 Atlassian All rights reserved.

Page 349: Jira Manual

fullname="Full name" email="[email protected]"/><jira:CreateGroup group-name="new-group"><jira:AddUserToGroup/></jira:CreateGroup></jira:CreateUser></JiraJelly>

7.4.7. jira:AddVersion

Adds a version to a project.

Attribute name Type Default value Description

project-key string The key of the projectyou want to add thecomponent too (notrequired if nestedinside ajira:CreateProject tag).

name string Name of the version(required).

Table 1: Attributes

7.4.7.1. Examples

Create a Version

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:AddVersion project-key="ABC" name="Ver 1"/></JiraJelly>

Create a Version in a Project

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateProject key="ABC" name="A Project" lead="logged-in-user"><jira:AddVersion name="Ver 1"/></jira:CreateProject></JiraJelly>

7.4.8. jira:CreateGroup

Creates a Group in JIRA.

Attribute name Type Default value Description

group-name string Name of group tocreate (required).

Table 1: AttributesContext Variable Type Description

jelly.group.name string Name of group being created.

Table 2: Context Variables

7.4.8.1. Examples

Create Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateGroup group-name="new-group"/></JiraJelly>

JIRA Documentation

Page 349Copyright © 2002-2005 Atlassian All rights reserved.

Page 350: Jira Manual

7.4.9. jira:AssignIssue

Assigns an issue to a user.

Attribute name Type Default value Description

key string Key of the issue toassign.

assignee string User to assign issueto.

Table 1: Attributes

7.4.9.1. Examples

Create and assign issue<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateIssue project-key="TST" summary="My Issue summary" issueKeyVar="keyvar"/><jira:AssignIssue key="${keyvar}" assignee="testuser"/>

</JiraJelly>

7.4.10. jira:CreateIssue

This tag creates a new issue in JIRA and places the issue id in the context.

Attribute name Type Default value Description

project-key string Key of the project toadd the issue to(required if not nestedin a jira:CreateProjecttag).

issueType string First issue type The string name of theIssue Type this issueshould be created for(e.g. Bug).

summary string Summary of the issuebeing created(required).

priority string First priority The string name of thePriority (e.g. Major).

components string The string name of theComponent.

versions string The string name of theAffected Version.

fixVersions string The string name of theFix For Version.

assignee string The username of theuser to assign thisissue to (logged in userrequires the assignissue permission anduser specified requiresthe assignablepermission). Set to "-1"for Automatic

JIRA Documentation

Page 350Copyright © 2002-2005 Atlassian All rights reserved.

Page 351: Jira Manual

assignment.

reporter string Currently logged inuser

The username of who isreporting this issue, theuser is logged in and thenthe issue created. Theuser is logged out againwhen the create issue tagcloses. (broken? SeeJRA-5620)

environment string Description of theenvironment.

description string Detailed description ofthe issue.

duedate string Due date of the issue.The format required isthe current JIRA dateformat.

Note:As the default JIRAdate format islocale-specific (eg.12/Jan/05), you may wishto use the yyyy-mm-ddISO format instead. Todo this, set the followinginWEB-INF/classes/jira-application.properties:

jira.date.picker.java.format = yyyy-MM-djira.date.picker.javascript.format = %Y-%m-%e

created string Current Date/Time Date/Time the Issuewas created in formatyyyy-MM-ddhh:mm:ss.0

updated string Current Date/Time Date/Time the Issuewas updated in formatyyyy-MM-ddhh:mm:ss.0

issueIdVar string The name of thevariable to place the IDof the new Issue.

issueKeyVar string The name of thevariable to place theKey of the new Issue.

duplicateSummary string Setting this attribute to'ignore' will allow Issuewith the samesummary to becreated.

security-level string Enterprise-only - setsthe security level of anissue. Value is thename of a level, eg.'Secret'.

JIRA Documentation

Page 351Copyright © 2002-2005 Atlassian All rights reserved.

Page 352: Jira Manual

Table 1: Attributes

7.4.10.1. Examples

Create Issue

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateIssue project-key="ABC" assignee="-1" summary="Issue summary"><!- other jelly tags -></jira:CreateIssue></JiraJelly>

Create Issue from Project

This example is more complicated as a permission scheme is required for the project before anissue can be created.

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateProject key="ABC" name="A Project" lead="logged-in-user"><jira:CreatePermissionScheme name="admin-scheme"><jira:AddPermission permissions="Assignable,Browse,Create,Assign"type="group"/><jira:SelectProjectScheme/></jira:CreatePermissionScheme><jira:CreateIssue summary="Issue summary"><!- other jelly tags -></jira:CreateIssue></jira:CreateProject></JiraJelly>

Create Issue with Custom Field values

Use the subtag jira:AddCustomFieldValue

Attribute Name Type Description

id long ID of the custom field with thecustomfield_ prefix

value string string representation of thecustom field value. Note thatthis may be different to thedisplayed value (e.g. Theproject picker uses the projectid as the String value butdisplays the project name)

key string Key is used formulti-dimensional data.Currently, only Cascadingselects supports its use. Omitto specify the value of parent,use "1" as the value for child

name String deprecated Name of thecustom field.

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateIssue project-key="ABC" summary="Issue summary"><jira:AddCustomFieldValue id="customfield_10000" value="field value"/><jira:AddCustomFieldValue name="Environment Select list" value="Windows XP"/>

<!-- For Cascading Selects : Note also that the value for cascading selects is the optionId--><jira:AddCustomFieldValue id="customfield_10001" value="Parent Option Id" />

JIRA Documentation

Page 352Copyright © 2002-2005 Atlassian All rights reserved.

Page 353: Jira Manual

<jira:AddCustomFieldValue id="customfield_10001" value="Child Option Id" key="1" />

<!-- For Multi Selects --><jira:AddCustomFieldValue id="customfield_100002" value="Value 1" /><jira:AddCustomFieldValue id="customfield_100002" value="Value 2" />

</jira:CreateIssue></JiraJelly>

Note:Using the name attribute has been deprecated. While it will work in 3.0 its use is discouraged.

7.4.11. jira:LinkIssue

This tag creates a link from one issue to another issue.

Attribute name Type Default value Description

key string The key of the issue tolink from (origin of link -required)

linkKey string The key of the issue tolink to (destination oflink - required)

linkDesc string linkDesc is taken fromthe 'Inward Description'or the 'OutwardDescription' of the link.(required)

Table 1: Attributes

7.4.11.1. Examples

Create a Link between two existing issues

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:LinkIssue key="TST-1" linkKey="TST-2" linkDesc="duplicates"/></JiraJelly>

Create two issues and link them

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateIssue project-key="HSP" assignee="-1" summary="Issue summary 1" reporter="admin" issueKeyVar="issuekey1"/><jira:CreateIssue project-key="NDT" assignee="-1" summary="Issue summary 2" reporter="admin" issueKeyVar="issuekey2"/><jira:LinkIssue key="${issuekey1}" linkKey="${issuekey2}" linkDesc="duplicates"/></JiraJelly>

7.4.12. jira:TransitionWorkflow

Warning:Broken in 3.3 and 3.3.1 - see JRA-7690

This tag executes a workflow transition on an issue.

Attribute name Type Default value Description

user string Currently logged inuser

Username of the userto execute theworkflow transition.

JIRA Documentation

Page 353Copyright © 2002-2005 Atlassian All rights reserved.

Page 354: Jira Manual

The user needs tohave the adequatepermissions to executethe transition. Pleasenote that thepermissions requiredalso depend on thefields that are updatedduring the transition.(See other attributesbelow).

key string The key of the issue toexecute the transitionon.

workflowAction string The id or name of theworkflow transition toexecute. If theargument can beconverted to a numberit is assumed to be anid of the transition.Otherwise it isassumed to be aname.

resolution string The id or name of theresolution to set on theissue during thetransition. Please notethat the transition mustexpect the resolution tobe updated, otherwisean error is generated ifthis attribute issupplied. If theargument can beconverted to a numberit is assumed to be anid of the resolution.Otherwise it isassumed to be aname.

assignee string The username of the userto assign an issue toduring the transition. The"user" executing thetransition must havepermissions to assignissues if this attribute issupplied. Please note thatthe transition must expectthe assignee to beupdated, otherwise anerror is generated if thisattribute is supplied.

Use value "-automatic-"to let JIRA assign theissue to the defaultassignee.

JIRA Documentation

Page 354Copyright © 2002-2005 Atlassian All rights reserved.

Page 355: Jira Manual

fixVersions string A comma separatedlist of version ids ornames to set as "fixfor" versions during thetransition. The "user"executing the transitionmust have permissionsto set "fix for" versionsif this attribute issupplied. Please notethat the transition mustexpect the "fix for"versions to beupdated, otherwise anerror is generated ifthis attribute issupplied. If a value inthe provided commaseparated list can beconverted to a numberit is assumed to be anid of a version.Otherwise it isassumed to be aname.

comment string The comment to add tothe issue during thetransition. The "user"executing the transitionmust have permissionsto add comments andthe transition must beexpecting comments tobe added during itsexecution for thecomment to be addedsuccessfully.

commentLevel string The level for thecomment. The levelmust be a name of agroup the user is amember of.

Table 1: Attributes

7.4.12.1. Examples

Execute Workflow Transition<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">

<jira:TransitionWorkflow key="TST-6" user="testuser" workflowAction="Resolve issue"resolution="fixed" fixVersions="version 1,version 3" assignee="-automatic-"comment="Test comment" commentLevel="jira-developers" />

</JiraJelly>

7.4.13. jira:CreateProject

This tag creates a new project in JIRA and places the project id in the context.

Attribute name Type Default value Description

JIRA Documentation

Page 355Copyright © 2002-2005 Atlassian All rights reserved.

Page 356: Jira Manual

key string The project key usedto create Issue Keys(required).

name string The name of theproject (required).

lead string The username of theuser that is the projectlead (required).

url string The URL of the site forthis project.

description string The description of thisproject.

Table 1: AttributesContext Variable Type Description

jelly.project.id string Id of the Project that wascreated.

jelly.project.key string Key of the Project that wascreated.

Table 2: Context Variables

7.4.13.1. Examples

Create Project

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateProject key="ABC" name="A Project" lead="a-user"><!- other jelly tags -></jira:CreateProject></JiraJelly>

7.4.14. jira:CreateUser

Creates a user in JIRA and places their username in the context.

Attribute name Type Default value Description

username string Username of the userbeing created(required).

password string Users password(required).

confirm string Confirmation of userspassword (required).

fullname string Descriptive name ofthe user (required).

email string Email address of theuser (required).

Table 1: AttributesContext Variable Type Description

jelly.new.username string Username of the user beingcreated.

JIRA Documentation

Page 356Copyright © 2002-2005 Atlassian All rights reserved.

Page 357: Jira Manual

Table 2: Context Variables

7.4.14.1. Examples

Create User

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateUser username="new-user" password="password" confirm="password"fullname="Full name" email="[email protected]"/></JiraJelly>

7.4.15. jira:RemoveUser

Removes an existing JIRA user by their username

Attribute name Type Default value Description

username string Username of the userto remove (required).

Table 1: Attributes

7.4.15.1. Examples

Remove User

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:RemoveUser username="existing-user"/></JiraJelly>

7.4.16. jira:CreatePermissionScheme

Creates a Permission Scheme

Attribute name Type Default value Description

name required string Name of thepermission scheme.

description string Permission schemedescription.

Table 1: AttributesContext Variable Type Description

jelly.permission.scheme.id string Id of the created permissionscheme

Table 2: Context Variables

7.4.17. jira:AddPermission

Grants a permission within a permission scheme. Often nested within a CreatePermissionSchemetag.

Attribute name Type Default value Description

schemeId string If not nested in aCreatePermissionSchemetag, specifies thescheme Id to add thepermission to (0 is thedefault permissionscheme).

JIRA Documentation

Page 357Copyright © 2002-2005 Atlassian All rights reserved.

Page 358: Jira Manual

permissions required string A comma-separated listof permissions to grant:

String Permission

Project Administer Projects

Browse Browse Projects

Create Create Issues

Edit Edit Issues

ScheduleIssue Schedule Issues

Move Move Issues

Assign Assign Issues

Assignable Assignable User

Resolve Resolve Issues

Close Close Issues

ModifyReporter Modify Reporter

Comment Add Comments

Delete Delete Issues

Work Work On Issues

Link Link Issues

Attach Create Attachments

ViewVersionControl View Version Control

ViewVotersAndWatchers View Voters and Watchers

ManageWatcherList Manage Watcher List

SetSecurity Set issue security level

type string Type of permission

String

group

user

lead

assignee

reporter

group string If type is 'group' (ortype is unspecified),specifies the groupname to grantpermissions to.

user string If type is 'user',specifies the group

JIRA Documentation

Page 358Copyright © 2002-2005 Atlassian All rights reserved.

Page 359: Jira Manual

name to grantpermissions to.

Table 1: Attributes

7.4.17.1. Examples

Grant permissions to jira-users and jira-developers in a new permission scheme

(See also the example scripts)<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreatePermissionScheme name="New Permission Scheme"><jira:AddPermission group="jira-users" permissions="Browse,Create,Comment,Attach" type="group"/><jira:AddPermission group="jira-developers" permissions="Move,Assignable,Link,ViewVersionControl" type="group"/>

</jira:CreatePermissionScheme></JiraJelly>

Grant issue reporters the ability to edit/delete their own issues, in a new permission scheme(Enterprise-only)<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib"><jira:CreatePermissionScheme name="New Permission Scheme"><jira:AddPermission type="reporter" permissions="Delete, Edit"/>

</jira:CreatePermissionScheme></JiraJelly>

Make projects using default permission scheme visible to certain users (Enterprise-only)<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib"><jira:AddPermission schemeId="0" permissions="Browse" type="user" user="johnc"/><jira:AddPermission schemeId="0" permissions="Browse" type="user" user="ebf"/>

</JiraJelly>

7.4.18. jira:Login

This tag sets Logs a user into JIRA using the username and password provided.

Attribute name Type Default value Description

username string Username of the userto log (not required ifalready Logged in).

password string Password of the userto log (not required).

Table 1: AttributesContext Variable Type Description

jelly.user User User logged in.

jelly.username string Username of the User loggedin.

Table 2: Context Variables

7.4.18.1. Examples

Login a user in with username and password and set in context

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:Login username="misc-user" password="password"><!- other jelly tags -></jira:Login></JiraJelly>

JIRA Documentation

Page 359Copyright © 2002-2005 Atlassian All rights reserved.

Page 360: Jira Manual

7.4.19. jira:CreateCustomField

The tag creates a new Custom Field. Only System custom fields can be added with Jelly tags.

Attribute name Type Default value Description

fieldType string Field type as appearsas the key in the plugindescriptor

fieldScope string One of global, projector issuetype

fieldName string Name of custom field

projectKey string Key of the relatedproject. Only valid forscope "project"

issueType string Issue type. Only validfor scope "issuetype"

description string Description of the fieldto be displayed whenadding a value

searcher string A valid related customfield searcher

customFieldIdVar string The name of thevariable to place thenew custom field.

Table 1: Attributes

7.4.19.1. Examples

Create Cascading Custom Field

jira:AddCustomFieldSelectValue subtag can be used to add values for select lists.They can also be nested for Cascading Select Lists.

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateCustomField fieldType="cascadingselect"fieldScope="issuetype"fieldName="Issue cascadingselect Bug"issueType="Bug"description="Bank have requested Y2K fixes to be sent as an EBF."searcher="cascadingselectsearcher"><jira:AddCustomFieldSelectValue value="Parent 1" /><jira:AddCustomFieldSelectValue value="Parent 2"><jira:AddCustomFieldSelectValue value="Child 1" /><jira:AddCustomFieldSelectValue value="Child 2" /></jira:AddCustomFieldSelectValue><jira:AddCustomFieldSelectValue value="Parent 3" /></jira:CreateCustomField></JiraJelly>

7.4.20. jira:AddFieldToScreen

Adds a field to a specific tab on a screen. Can also specify in which position to insert the field.

JIRA Documentation

Page 360Copyright © 2002-2005 Atlassian All rights reserved.

Page 361: Jira Manual

Attribute name Type Default value Description

fieldId string Field ID of the field toadd (required). eg."description","duedate", etc.

screen string Screen ID or Name(required). eg. "1" or"Default Screen".

tab string 0 Tab ID or Name. eg."0" or "Field Tab".

fieldPosition int last position Position to insert thefield into. Range ofvalues is from 1 to thenumber of fields on thescreen.

Table 1: Attributes

7.4.20.1. Examples

Add Fields to a Screen

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><!-- Adds 'description' field to the 'Field Tab' on 'Default Screen' --><jira:AddFieldToScreen fieldId="description" screen="Default Screen" tab="Field Tab"/>

<!-- Adds 'duedate' field to same screen as above. duedate is inserted in position 1 --><jira:AddFieldToScreen fieldId="duedate" screen="1" tab="0" fieldPosition="1"/></JiraJelly>

Create a new Customfield and Add it to a Screen

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:CreateCustomField fieldType="cascadingselect"fieldScope="issuetype"fieldName="Issue cascadingselect Bug"issueType="Bug"description="Bank have requested Y2K fixes to be sent as an EBF."searcher="cascadingselectsearcher"customFieldIdVar="customField"><jira:AddCustomFieldSelectValue value="Parent 1" /><jira:AddCustomFieldSelectValue value="Parent 2"><jira:AddCustomFieldSelectValue value="Child 1" /><jira:AddCustomFieldSelectValue value="Child 2" /></jira:AddCustomFieldSelectValue><jira:AddCustomFieldSelectValue value="Parent 3" /></jira:CreateCustomField>

<jira:AddFieldToScreen screen="Default Screen" fieldId="${customField.getId()}"/></JiraJelly>

7.4.21. jira:AttachFile

Attaches a file to an issue.

Attribute name Type Default value Description

JIRA Documentation

Page 361Copyright © 2002-2005 Atlassian All rights reserved.

Page 362: Jira Manual

key string Key of the issue toattach the file to

filepath string Path (on the server) tothe file to attach

option string Behaviour when a filewith same name isalready attached. Theoptions are:

• skip - do not attachfile if a file with thisname is alreadyattached.

• override - overwriteexisting attached file

• add - add the file asanother attachment

Table 1: Attributes

7.4.21.1. Examples

Adding an attachment

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib"><jira:AttachFile key="TST-1" filepath="/tmp/somefile" option="override"/>

</JiraJelly>

7.4.22. Beta Tags

There are also a number of BETA tags that have not been fully tested or documented. Thefollowing list contains the tags and the attributes that can be passed to them:

• AddIssueSecurity• schemeId (required)• security (required)• type (required)

• AddIssueSecurityLevel• name (required)• description (required)

• Output• jelly.issue.scheme.level.id

• CreateIssueSecurityScheme• name (required)• description (required)

• Output• jelly.issue.scheme.id

• LoadManager• var (variable to put manager in)• manager (name of manager e.g. IssueManager)

• LoadProject

JIRA Documentation

Page 362Copyright © 2002-2005 Atlassian All rights reserved.

Page 363: Jira Manual

• var (variable to put project in)• project-name (name of project)

• RemoveGroup• name (required)

• RemovePermissionScheme• schemeId (required)• confirm (required))

• RemoveProject• pId (required)

• RunSearchRequest• var (variable to put all issues within system)

• SelectProjectScheme• projectKey (required)• permission-scheme (Name of permission scheme)or• issue-scheme (Name of issue security scheme)

• StringContains• value (String to look in)• possiblyContains (String to look for)• doesContain (true or false) if value contains possiblyContains == doesContain, the inside of

the tag is executed.

If you would like more information on how to use the Beta tags, please read the source and/or post tothe JIRA Development Forum.

7.4.23. Sample scripts

7.4.23.1. Creating a new Project

To properly partition projects, one needs a permission scheme per project, and project-specificgroups to allocate permissions to. Setting up a new project can be a time-intensive process. Thefollowing sample Jelly scripts automate this:

This script might be used for a publicly visible project:<?xml version="1.0"?><JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib" xmlns:j="jelly:core">

<j:set var="name" value="Test Project"/><j:set var="key" value="TEST"/><j:set var="lowerkey" value="test"/><j:set var="lead_username" value="joe"/><j:set var="lead_password" value="joe"/><j:set var="lead_fullname" value="Joe Bloggs"/><j:set var="lead_email" value="[email protected]"/><j:set var="url" value="http://example.com/TestProj"/>

<jira:CreateUser username="${lead}" password="${lead}" confirm="${lead}" fullname="${lead_fullname}" email="${lead_email}"/><jira:CreateGroup group-name="${lowerkey}-developers"><jira:AddUserToGroup username="${lead}"/>

</jira:CreateGroup>

<jira:CreateProject key="${key}" name="${name}" url="${url}" lead="${lead}"><jira:CreatePermissionScheme name="${name} permissions"><jira:AddPermission type="reporter" permissions="Close"/><jira:AddPermission group="jira-administrators" permissions="Close,Delete" type="group"/>

JIRA Documentation

Page 363Copyright © 2002-2005 Atlassian All rights reserved.

Page 364: Jira Manual

<jira:AddPermission group="jira-users" permissions="Create,Edit,Comment,Link,Attach" type="group"/><jira:AddPermission group="${lowerkey}-developers" permissions="Project,ScheduleIssue,Move,Assign,Assignable,Resolve,Close,Work" type="group"/><jira:AddPermission group="Anyone" permissions="Browse,ViewVersionControl"/><jira:SelectProjectScheme/>

</jira:CreatePermissionScheme></jira:CreateProject>

</JiraJelly>

This script is more complicated, with multiple groups per project:<?xml version="1.0"?><!-- This script handles some of the administrative chores required when addinga new project to JIRA. It creates the project, groups, permission scheme, and givesgroups the relevant permissions in the permission scheme. --><JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib" xmlns:j="jelly:core">

<!-- Name of the project to create --><j:set var="name" value="Jelly Test Project"/><!-- Key for the new project --><j:set var="key" value="TEST"/><!-- Existing user who will become the project lead (default assignee) --><j:set var="admin" value="admin"/>

<jira:CreateGroup group-name="${key}-users"/><jira:CreateGroup group-name="${key}-developers"/><jira:CreateGroup group-name="${key}-managers"/><jira:CreateGroup group-name="${key}-bizusers"/><jira:CreateGroup group-name="${key}-qa"/>

<jira:CreateProject key="${key}" name="${name}" lead="${admin}"><jira:CreatePermissionScheme name="${key} Permission Scheme"><jira:AddPermission type="reporter" permissions="Edit"/><jira:AddPermission type="assignee" permissions="Resolve"/><jira:AddPermission group="jira-administrators" permissions="Project,Delete" type="group"/><jira:AddPermission group="${key}-users" permissions="Browse,Create,Comment,Attach" type="group"/><jira:AddPermission group="${key}-developers" permissions="Move,Assignable,Link,ViewVersionControl" type="group"/><jira:AddPermission group="${key}-managers" permissions="Edit,Assign,Assignable,Resolve,Close,Delete" type="group"/><jira:AddPermission group="${key}-bizusers" permissions="Assignable" type="group"/><jira:AddPermission group="${key}-qa" permissions="Assignable" type="group"/><jira:AddPermission group="opsmgrs" permissions="Browse,Edit,Assignable,Comment" type="group"/><jira:AddPermission group="dba-user-group" permissions="Browse,Assign,Assignable,Comment" type="group"/><jira:AddPermission group="help-desk-group" permissions="Browse,Assign,Assignable,Comment" type="group"/><jira:AddPermission group="webadmin-group" permissions="Browse,Assign,Assignable,Comment" type="group"/><jira:AddPermission group="unix-admin-group" permissions="Browse,Assign,Assignable,Comment" type="group"/><jira:SelectProjectScheme/></jira:CreatePermissionScheme></jira:CreateProject></JiraJelly>

7.4.23.2. For a list of projects, perform a project-specific operation.

This script iterates through a (comma-separated) list of projects, creates a project-specific group,and adds a user to that group.<?xml version="1.0"?><!-- Jelly script to create 'support' group per project --><JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib" xmlns:util="jelly:util" xmlns:j="jelly:core"><util:tokenize var="projects" delim=",">ARM,QWI,DWI,DBOR,DBSQ,LYX,MMM,MOI,TPAI,SEP,AMR,SLA,TP,TRBC,YRD</util:tokenize><j:forEach var="proj" items="${projects}"><jira:CreateGroup group-name="${proj}-support"/><jira:AddUserToGroup username="jeff" group-name="${proj}-support"/></j:forEach></JiraJelly>

7.4.23.3. Create a user, issue, and assign the issue to the user

The following script creates a user (called new-user), creates a new issue, adds the user to thejira-developers group and assigns the issue to the user. It illustrates the use of contextvariables.

JIRA Documentation

Page 364Copyright © 2002-2005 Atlassian All rights reserved.

Page 365: Jira Manual

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">

<jira:CreateUser username="new-user" password="password" confirm="password" fullname="Full name" email="[email protected]"/>Username is ${jelly.new.username}<jira:CreateIssue project-key="TP" summary="New issue summary" issueKeyVar="ik"/><jira:AddUserToGroup username="new-user" group-name="jira-developers"/><jira:AssignIssue key="${ik}" assignee="${jelly.new.username}"/>

</JiraJelly>

7.4.23.4. Assigning and Starting Progress

Here we create an issue, assign it to 'bob' (who must be in jira-developers), and startprogress:<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">

<jira:CreateIssue project-key="TP" summary="New issue" issueKeyVar="ik"/><jira:AssignIssue key="${ik}" assignee="bob"/><jira:TransitionWorkflow key="${ik}" user="bob" workflowAction="Start Progress" /></JiraJelly>

7.5. The JIRA Toolkit (Customer Support Extensions)

As an extension to JIRA, Atlassian have developed a set of JIRA custom fields, collectively calledthe "JIRA Toolkit". It can be found online at:

http://confluence.atlassian.com/display/JIRAEXT/JIRA+Toolkit

These custom fields are particularly useful in customer-facing JIRA instances. They were initiallydeveloped for use in Atlassian's own JIRA Support installation at http://support.atlassian.com. Seethe JIRA Toolkit documentation for details.

7.6. Developer Guides

7.7. JIRA Source

7.7.1. Building JIRA from source

Commercial users get access to JIRA source. This documentation shows how to build the JIRAsource back into an application that can be deployed.

You would only be interested in this documentation if you are making modifications to the JIRAsource code. Changes to JSP files do not require rebuilding JIRA. Also, you should be aware of thepossibilities the plugin system affords - often changes can be developed and packaged as a pluginwithout requiring core source modifications.

7.7.1.1. Building JIRA WAR from JIRA Source release

1. Ensure you have JDK 1.4 or higher.2. Download Maven 1.0.x from http://maven.apache.org3. Extract Maven somewhere, say c:\Dev\testing4. Set MAVEN_HOME:

> set MAVEN_HOME=c:\Dev\testing\maven-1.05. Download JIRA Source zip from

http://www.atlassian.com/software/jira/JIRASourceDownloads.jspa. You will need to log in as auser with a commercial licence to access this page.

6. Extract the JIRA Source zip somewhere, say c:\Dev\testing.7. Your c:\Dev\testing should look somewhat like:

JIRA Documentation

Page 365Copyright © 2002-2005 Atlassian All rights reserved.

Page 366: Jira Manual

C:\Dev\testing>dir

Volume in drive C is COOKIEVolume Serial Number is 3F3F-14F0

Directory of C:\Dev\testing

24/02/2003 04:30p <DIR> .24/02/2003 04:30p <DIR> ..24/02/2003 04:18p <DIR> atlassian-core24/02/2003 04:18p <DIR> atlassian-ofbiz24/02/2003 04:18p <DIR> atlassian-profiling24/02/2003 04:18p <DIR> atlassian-velocity24/02/2003 04:18p <DIR> bandana24/02/2003 04:18p <DIR> configurableobjects24/02/2003 04:18p <DIR> jira24/02/2003 04:18p <DIR> johnson12/02/2003 05:26p <DIR> maven-1.024/02/2003 04:18p <DIR> lib24/02/2003 04:18p <DIR> mail24/02/2003 04:18p <DIR> plugins24/02/2003 04:18p <DIR> rpc-jira-plugins24/02/2003 04:18p <DIR> scheduler24/02/2003 04:18p <DIR> seraph24/02/2003 04:18p <DIR> trackback

0 File(s) 0 bytes10 Dir(s) 16,352,509,952 bytes free

8. Change into the jira\ subdirectory, and build using Maven.C:\Dev\testing\jira> maven war:webapp

9. Confirm that the open .war has been created in .\target\atlassian-jira

C:\Dev\testing\jira\target\atlassian-jira>dirVolume in drive C is COOKIEVolume Serial Number is 3F3F-14F0

Directory of C:\Dev\testing\jira\target\atlassian-jira

24/02/2003 04:41p <DIR> .24/02/2003 04:41p <DIR> ..24/02/2003 04:41p <DIR> decorators24/02/2003 04:41p <DIR> images24/02/2003 04:41p <DIR> includes24/02/2003 04:41p <DIR> portlets24/02/2003 04:41p <DIR> secure24/02/2003 04:41p <DIR> styles24/02/2003 04:41p <DIR> template24/02/2003 04:41p <DIR> views24/02/2003 04:41p <DIR> WEB-INF24/02/2003 04:41p 8781 500page.jsp24/02/2003 04:41p 1593 bugzillasearch.jsp24/02/2003 04:41p 328 default.jsp24/02/2003 04:41p 894 favicon.ico24/02/2003 04:41p 211 login-error.jsp24/02/2003 04:41p 203 login.jsp24/02/2003 04:41p 733 logoutconfirm.jsp24/02/2003 04:41p 939 logout.jsp8 File(s) 13,68211 Dir(s) 56931786752 bytes free

You should now be able to point a suitably configured Servlet 2.3+ compliant app server at thisdirectory, and run JIRA.

7.7.1.2. Developing using Intellij IDEA

If you are an IDEA user, you may wish to use the atlassian-idea plugin we have developed to

JIRA Documentation

Page 366Copyright © 2002-2005 Atlassian All rights reserved.

Page 367: Jira Manual

quickly generate a work environment.

7.7.1.3. Obtaining the source of JIRA's dependencies

Most of JIRA's dependencies are either shipped in binary (compiled) form with the sourcedistribution, or are available on Maven's public repository. Maven will fetch the dependencies that itrequires automatically during the build process, so you do not have to do it manually. Hence, you donot need the source of every dependency to build JIRA from source. However, sometimes you mightwant to "look inside" these dependencies. If so, this section is for you.

The source distribution of JIRA is shipped with a project.xml file. All of JIRA's dependenciesare listed inside this file. Most of the dependencies are open source libraries but some are Atlassian'scode. All of the Atlassian code is included in the source distribution. The source of the otherdependencies is usually available on the library's website (try googling for the library name).

In some cases JIRA uses unofficial 'snapshot' releases of a library, sometimes additionally patched tofix bugs or add features. In these cases the library source can be obtained from Atlassian'srepository, at http://repository.atlassian.com/dependencyId/distributions/, where dependencyId isthe dependency name found in the project.xml record.

For example, source for the dependency:<dependency><id>javacvs</id><version>20050531-patched</version><properties><war.bundle>true</war.bundle>

</properties></dependency>

can be found athttp://repository.atlassian.com/javacvs/distributions/javacvs-20050531-patched-src.tar.gz. If sourcemodifications were made, a patch is usually available athttp://repository.atlassian.com/dependencyId/patches/

If you have any questions regarding the build process, please post to the JIRA Development Forum.Atlassian developers continually monitor this list.

7.7.2. API Docs

The JIRA API docs are available online. They are most useful for:

• users writing Listeners and Services• users with commercial licenses who wish to modify JIRA• partners embedding JIRA as a J2EE component

7.7.2.1. API Docs (by JIRA version)

• latest version• JIRA 3.5.2• JIRA 3.5.1• JIRA 3.5• JIRA 3.4.3• JIRA 3.4.2• JIRA 3.4.1• JIRA 3.4• JIRA 3.3.2• JIRA 3.3.1• JIRA 3.3

JIRA Documentation

Page 367Copyright © 2002-2005 Atlassian All rights reserved.

Page 368: Jira Manual

• JIRA 3.3 Beta1• JIRA 3.2.3• JIRA 3.2.2• JIRA 3.2.1• JIRA 3.2• JIRA 3.1.1• JIRA 3.1• JIRA 3.0• JIRA 2.6.1• JIRA 2.6• JIRA 2.5.3• JIRA 2.5.2• JIRA 2.5.1• JIRA 2.5• JIRA 2.4.1• JIRA 2.4• JIRA 2.3• JIRA 2.2.1• JIRA 2.2• JIRA 2.1

8. Miscellaneous

8.1. Frequently Asked Questions

8.1.1. Questions

1. General• Got a question we haven't answered here?• Where do I look if I have a problem, error message or feature request?• Is there an online demo that I can test?• I can't seem to post to the forum, is it broken?• What does JIRA mean?• How is JIRA pronounced?• What features are unique to JIRA?

2. Licensing & Pricing• Sales & Licensing questions

3. Technical• When running startup.bat I get an error message: "Windows cannot find '-Xms128m'"• Someone has left the company. How do I delete their user account if they have reported

issues?• With an Oracle database, it seems I can only store up to 4000 characters of text in fields

(comments, issue description etc).• Why are international characters in notification email subjects are being replaced with '?'• After upgrading JIRA I get an error containing 'com/atlassian/jira/license/LicenseFactory'.• When starting JIRA, I get an error "java.lang.NoClassDefFoundError:

com/atlassian/jira/issue/search/parameters/lucene/SingleFieldMultiValueLuceneParameter"• Can I change the default attachment size limit?• What servers does JIRA run on? What servers has it been tested on?• Is it possible to enter a bug that has not been assigned to a developer?• Does JIRA support clustering?• How do I change the due date input format?• How can I import data from existing systems?

JIRA Documentation

Page 368Copyright © 2002-2005 Atlassian All rights reserved.

Page 369: Jira Manual

• To what degree can project and data visibility be controlled?• How do I allow anonymous access of JIRA?• In the Quick Search bar (top-right), sometimes it allows you to enter just the number, other

times it requires the prefix to be included?• When configuring issue link types, what do the "outward" and "inward" descriptions

(duplicate, duplicates, is duplicated by) mean?• Can I store customer details, like company, address and contact information in JIRA?• How do I go about allowing users to submit tickets via email? Particularly if I wish to allow

anonymous users to enter tickets without having JIRA accounts already?• How do I setup JIRA using a different database to the one provided as default?• Can I define multiple intake forms so that they do not expose all fields to users?• We already have users & groups defined elsewhere, can JIRA make use of this?• Is the XML format for the import/export files (which also contains the configuration)

documented?• Using email notifications, can separate templates be setup for projects or events?• Can the system send notifications based on a set issue turnaround time being exceeded? Can

it automatically escalate issues that have exceeded a preset turnaround time?• Can two issues in the same project be linked together by a user?• How can I add custom content to the front page?• I have manually reset a user's password, but still cannot log in as that user.• I have forgotten the JIRA administrator password, and cannot retrieve it as mail notification

is not set up. Help!• I cannot get past the login page. After clicking the "Log In" button, the login page just

refreshes.• How can I migrate my data from JIRA Enterprise to JIRA Professional?• How do I change custom field scope (eg. from project-specific to global)?• When I try to import an XML backup, I get an error about CDATA sections or invalid

unicode characters• Why doesn't JIRA have a Severity field like Bugzilla?

8.1.2. Answers

8.1.2.1. 1. General

1.1. Got a question we haven't answered here?

Contact us

1.2. Where do I look if I have a problem, error message or feature request?

If you are evaluating JIRA, then you should subscribe to the mailing list. If you have a problem, youshould first search the mailing list archives. If you do not find an answer - post your question to themailing list, or raise your bug online.

1.3. Is there an online demo that I can test?

Yes. We have created a test project at http://jira.atlassian.com, where you can create and updateissues online.

Note:you cannot access the administration area of this demo - you'll need to download to do that. Downloading is still the best way to fullyevaluate JIRA!

JIRA Documentation

Page 369Copyright © 2002-2005 Atlassian All rights reserved.

Page 370: Jira Manual

1.4. I can't seem to post to the forum, is it broken?

No. JIRA forums work on a mailing-list system to post questions and replies, rather than using amessage board. The online forum section is only an archive of past emails.

To post a message, you should:

1. Subscribe to the jira-user list.2. Wait for a confirmation email.3. Email jira-user at lists.atlassian.com (replace 'at' with '@').

1.5. What does JIRA mean?

Like all good names in the software industry, it started as an in-house code name.

Our experience with Bugzilla was less than pleasant, and the developers in the office startedcalling it by the name Japanese name for Godzilla, Gojira (the original black-and-white JapaneseGodzilla films are also office favourites). As we developed our own bug tracker, and then itbecame an issue tracker, the name stuck, but the Go got dropped - hence JIRA!

Further investigation into the name has revealed that Gorira is Japanese for gorilla, whilst Kujirais Japanese for whale. So Gojira is roughly translated to mean "gorilla the size of a whale"!

For those who care - it sounds best if you yell it loudly, as though charging into battle. C'mon -try it!

1.6. How is JIRA pronounced?

We pronounce it 'JEEra', based on the pronunciation of 'Kujira' (see above FAQ).

1.7. What features are unique to JIRA?

On a purely functional level JIRA has a number of unique features which separate it from thecompetition:

• Real time project road map and automatic change log generation• Platform independent - runs on most operating system, application server and database

combinations.• Use of listeners and services - allows JIRA to integrate with external systems and processes.• RSS views that allows you to subscribe to any filter as an XML feed• An Excel view of any filter, which makes producing reports, graphs etc much easier• Brilliantly simple, superior user interface - the functions you want are where you want (and

expect!) them to be.• Simple, functional permissions structure - gives you precise control over who can do what.• Installs in seconds - anywhere!

8.1.2.2. 2. Licensing & Pricing

2.1. Sales & Licensing questions

Please see the Sales FAQ.

8.1.2.3. 3. Technical

3.1. When running startup.bat I get an error message: "Windows cannot find '-Xms128m'"

The Java JDK is not installed or the JAVA_HOME environment variable has not been set

JIRA Documentation

Page 370Copyright © 2002-2005 Atlassian All rights reserved.

Page 371: Jira Manual

correctly. Please refer to the Java installation guide.

3.2. Someone has left the company. How do I delete their user account if they have reportedissues?

It's best not to - rather, disable their account by removing their membership from all groups. Thiswill prevent that account from being used, and prevents it appearing in user pickers (assignee, etc).

If you really want to delete the account (and historical revisionism doesn't bother you), you canbulk-edit the issues involved and change the reporter to someone else. You'll need the ModifyReporter permission to do this. You can then delete the user.

3.3. With an Oracle database, it seems I can only store up to 4000 characters of text in fields(comments, issue description etc).

Oracle VARCHAR fields can only store up to 4000 characters, and CLOBs could not be accessed ina standard way until the Oracle 10g driver was released (and then only with a special flag). Theprocess of adopting the Oracle 10g driver fix is described here.

3.4. Why are international characters in notification email subjects are being replaced with '?'

This happens if the system encoding is not the same as the JIRA encoding (by default UTF-8).System encoding can be seen in Administration -> System -> System Info, and JIRA encoding canbe seen in Admin -> Global Settings -> General Configuration.

If there is a discrepancy, this can be fixed by setting the system encoding with a command-lineoption (-Dfile.encoding=utf-8) when starting JIRA. Eg. with Tomcat (JIRA Standalone), setJAVA_OPTS=-Dfile.encoding=utf-8 before running the startup script. See JRA-5176 formore details.

3.5. After upgrading JIRA I get an error containing'com/atlassian/jira/license/LicenseFactory'.

Your application server is using old cached JSPs from the previous JIRA version. Please delete thedirectory where the app server keeps these (the work/ directory in Tomcat; theapplication-deployments/ directory in Orion etc), and restart.

3.6. When starting JIRA, I get an error "java.lang.NoClassDefFoundError:com/atlassian/jira/issue/search/parameters/lucene/SingleFieldMultiValueLuceneParameter"

Windows XP's unzip is broken. See the install guide for now to avoid this.

3.7. Can I change the default attachment size limit?

Yes, see the Configuring file attachments page.

3.8. What servers does JIRA run on? What servers has it been tested on?

See the requirements document for a detailed discussion of JIRA and application servers.

3.9. Is it possible to enter a bug that has not been assigned to a developer?

The short answer - Yes, you can choose to leave bugs unassigned. This can be achieved by alteringthe 'Allow Unassigned Issues' flag in the configuration options. To do this go to the GeneralConfiguration page of the Administration section. Now simply edit the configuration and turn the

JIRA Documentation

Page 371Copyright © 2002-2005 Atlassian All rights reserved.

Page 372: Jira Manual

'Allow Unassigned Issues' flag on. For more detail please refer to the documentation relating tothis function.

This function is not enabled as default as different companies tend to have different approachesto handling issues. We have found that many of our customers prefer to have issues alwaysassigned to an owner, to ensure that somebody is responsible for it's handling and resolution.

3.10. Does JIRA support clustering?

No. To date, a need for clustering has never really become apparent, as JIRA performs quiteadequately on a single instance. When performance problems do occur, they are usually traceableto fixable JIRA bugs or misconfigurations.

If you are deploying JIRA to a clustered environment (e.g. due to your company's policy), pleaseensure that JIRA web application is deployed to only one node in the cluster. Most clusteredapplications support this feature (e.g. WebLogic). Also ensure that your load balancer(s) areconfigured to direct all requests for JIRA to the correct node in the cluster.

3.11. How do I change the due date input format?

The default JIRA input format is locale-specific (eg. 12/Jan/05). You may wish to use anotherformat, such as the yyyy-mm-dd ISO format instead. To do this, set the following inWEB-INF/classes/jira-application.properties:jira.date.picker.java.format = yyyy-MM-djira.date.picker.javascript.format = %Y-%m-%e

3.12. How can I import data from existing systems?

For importing from CSV, Bugzilla or Mantis, see the documentation (CSV, Bugzilla), Mantis.

For other types of import, please contact us as we may have done it before. See also JIRA's Jellysupport - a scriptable interface to JIRA that is useful for importing data.

3.13. To what degree can project and data visibility be controlled?

At the moment project visibility can be restricted to particular groups of users using projectpermissions.

For example, if customers from Company X were put into the group "Cust-X" and given"Browse" permission for project Y, they will only be able to see Project Y (assuming you turn offthe global browse permission).

You should of course also give your developers permission to browse and operate on the project.

The enterprise edition of JIRA provides even finer grained permissions. With this edition, youcan set security on an issue by issue basis. For more information on JIRA's Issue Level Security,please consult the documentation.

3.14. How do I allow anonymous access of JIRA?

Anonymous access can be enabled simply by adding a permission for 'Anyone' to browseparticular projects.

3.15. In the Quick Search bar (top-right), sometimes it allows you to enter just the number,other times it requires the prefix to be included?

It only requires a prefix if you have no 'selected project' - this is a somewhat amorphous JIRA

JIRA Documentation

Page 372Copyright © 2002-2005 Atlassian All rights reserved.

Page 373: Jira Manual

notion, a bit of magic if you like. Basically, if you have done something recently, that projectbecomes your selected project. JIRA tries to 'guess' which issue you are talking about given theselected project.

That is, View JRA-52, then type '53' and you will see JRA-53 (as it knows you are using projectJRA). If you just try '53' by itself, it doesn't know that.

3.16. When configuring issue link types, what do the "outward" and "inward" descriptions(duplicate, duplicates, is duplicated by) mean?

Both descriptions show up in the box so you can determine which way you want to link. Duplicate isa bad example of this because it's fairly bi-directional. Think of a Parent-Child link. In this case thebox would contain "is a parent of" and "is a child of" - so you're saying that the current link is eithera parent OR a child of the key you enter in the form (and hence the key entered is the oppositerelation to this issue).

3.17. Can I store customer details, like company, address and contact information in JIRA?

No. JIRA itself stores only minimal user data (username, name, email, preferences). For everythingelse, we recommend storing user data in an LDAP server (eg. ActiveDirectory or OpenLDAP). Youcan then authenticate users in JIRA against their LDAP password (see the docs).

Having external user management is more flexible in the long run, because:

• You can choose exactly which user info you wish to store, without being constrained by JIRA'sdata model.

• Systems other than JIRA can use the user database. For instance, users could log into yourwebsite using the same details they log into JIRA with.

• You can use external, purpose-specific tools for managing the user database, rather than have todo everything through JIRA.

3.18. How do I go about allowing users to submit tickets via email? Particularly if I wish toallow anonymous users to enter tickets without having JIRA accounts already?

In order to allow users to submit tickets via email - this functionality can very simply be added viathe use of listeners and services (see http://www.atlassian.com/software/jira/docs/extending.jsp).

There are couple of ways of allowing anonymous users to submit issue tickets.

1. Configure the email handler to automatically create accounts for new users (new in 2.6).2. Adding a dummy user, and thus adding all anonymous issues to be under that user.3. Setting JIRA up to use your existing user-base, in which case all users would already be in your

system. If your users are already stored in LDAP, or a database, then this is relatively simpleusing OSUser (http://www.opensymphony.com/osuser/), which JIRA uses for all itsauthentication.

3.19. How do I setup JIRA using a different database to the one provided as default?

If you are using JIRA Standalone (with a built-in Tomcat server), see these instructions for changingdatabases.

Otherwise, if you are using an external application server (Weblogic, Websphere, Orion, Resin, etc),this takes two steps:

1. Configure your application server to talk to the database, and export a database connectionfactory (DataSource) via JNDI. The documentation for your application server should provideinstructions on how to do this. It generally involves:

JIRA Documentation

Page 373Copyright © 2002-2005 Atlassian All rights reserved.

Page 374: Jira Manual

• adding a JDBC driver jar to the classpath (usually a lib/ directory)• and editing a configuration file to set up a new DataSource, specifying the database JDBC

URL, username and password.2. Edit JIRA's entityengine.xml file to tell JIRA what type of database it is talking to,

and where (in the JNDI tree) to find the DataSource provided by the application server. Themodified entityengine then needs to be built (using the build.sh / build.bat scripts)into a webapp and deployed in the suitably configured app server.

The instructions on this page are all valid, apart from assuming Tomcat as the app server.

3.20. Can I define multiple intake forms so that they do not expose all fields to users?

This can be easily achieved with JIRA source code - by defining new JSP views for the 'create'actions.

3.21. We already have users & groups defined elsewhere, can JIRA make use of this?

Yes. If you have users and groups defined elsewhere then you can either use an existing OSUserprovider (such as LDAP or JDBC) or write your own if you have custom needs.

3.22. Is the XML format for the import/export files (which also contains the configuration)documented?

Not as such - it is an XML version of the underlying entity model, pulled out of the database. Asa result it is always changing with new fields and entities being added. The entity model itself isdefined in WEB-INF/classes/entitymodel.xml

3.23. Using email notifications, can separate templates be setup for projects or events?

Unfortunately templates are global. We anticipate adding this feature to the JIRA enterprise infuture.

3.24. Can the system send notifications based on a set issue turnaround time beingexceeded? Can it automatically escalate issues that have exceeded a preset turnaroundtime?

No, not automatically - but this is exactly what services are for.

For example, a simple service query could be written in order to query the system at regularintervals (for example, every hour) and automatically perform operations (such as automaticescalation of particular issues). This would enable issues to be automatically updated within timeconstraints.

3.25. Can two issues in the same project be linked together by a user?

Yes, this is what issue linking does. Arbitrary link types can be setup (for example to indicateduplicates, parent-child relationships etc) and then give permissions for any groups of users to beable to create links.

Links may also be configured to run across projects.

3.26. How can I add custom content to the front page?

Custom HTML content can be easily added to the dashboard by an Administrator, by clicking onGeneral Configuration, clicking 'Edit Configuration', and editing the Introduction field.

JIRA Documentation

Page 374Copyright © 2002-2005 Atlassian All rights reserved.

Page 375: Jira Manual

3.27. I have manually reset a user's password, but still cannot log in as that user.

Check in Admin -> Global Settings -> Global Permissions that your users are in a group with theJIRA Users permission.

3.28. I have forgotten the JIRA administrator password, and cannot retrieve it as mailnotification is not set up. Help!

You will need to temporarily remove security restrictions, reset the password, then reenable them.

This can be done as follows:

1. Locate the WEB-INF/classes/seraph-config.xml file (in 2.4.1 and earlier it is calledsecurity-config.xml).

2. Comment out everything between the <services> tags:

<security-config>...<services>

<!--<service class="com.atlassian.seraph.service.PathService">

<init-param><param-name>config.file</param-name><param-value>/seraph-paths.xml</param-value>

</init-param></service>

<service class="com.atlassian.seraph.service.WebworkService"><init-param>

<param-name>action.extension</param-name><param-value>jspa</param-value>

</init-param></service>-->

</services>...

</security-config>3. Restart JIRA

You will now be able to access all of JIRA without logging on. You won't get any menus however,so you will need to access all the URLs directly, eg.

• For setting Administrator and User global permissions: http://<yourserver>/secure/admin/jira/GlobalPermissions.jspa

• For adding a group: http://<your-server>/secure/admin/user/GroupBrowser.jspa• Searching for and editing users: http://<your-server>/secure/admin/user/UserBrowser.jspa

After you have fixed up the permissions, remember to reenable the commented-out section inseraph-config.xml, and restart JIRA.

3.29. I cannot get past the login page. After clicking the "Log In" button, the login page justrefreshes.

This usually occurs when JIRA cannot set a browser cookie. Ensure that cookies are allowed in yourbrowser settings.

If you are using IE6, check that your server name does not have an underscore ("_") in it, as IE6 hasa problem with this (see JRA-1624).

3.30. How can I migrate my data from JIRA Enterprise to JIRA Professional?

JIRA Documentation

Page 375Copyright © 2002-2005 Atlassian All rights reserved.

Page 376: Jira Manual

JIRA cannot "automatically" downgrade, because it would require silently removing uses ofenterprise features that could potentially render the system inoperable. There is a manual processfor downgrading from Professional to Enterprise, described here, and a similar guide formigrating from Professional to Standard here.

3.31. How do I change custom field scope (eg. from project-specific to global)?

This is not currently possible through the user interface, but can be done by editing the JIRAdatabase, as described in this guide.

3.32. When I try to import an XML backup, I get an error about CDATA sections orinvalid unicode characters

It's possible for characters that cannot be represented in Unicode (and hence XML) to get in theJIRA database. When an XML backup is made and later imported, the importer chokes on thesecharacters.

The solution is to run the XML through the XML cleaner utility, and then import the cleanedXML.

3.33. Why doesn't JIRA have a Severity field like Bugzilla?

Originally, JIRA did have a priority and a severity field. It was removed for a number of reasons,but principally because it was confusing to business users. To a software developer, it seemsobvious that the severity of the bug ("The system crashes completely") is unrelated to the priorityof it ("There is a one in a million chance of this occurring"). However JIRA succeeds so wellbecause business users can actually use it. If you present a business user with these two fields,they are instantly confusing. Hence why it was removed in the first place.

In order to re-implement severity, you can use a "severity" select-list custom field, order it (withfield layouts), put it on your filters (with column layouts) and indeed search and filter it (in thenavigator). See Custom Fields Overview

9. Documentation

JIRA Documentation

Page 376Copyright © 2002-2005 Atlassian All rights reserved.