Documentation for JIRA 6.3 EAP developer (EAP) releases only. Not using this? See below:
(JIRA 6.2.x documentation | JIRA OnDemand documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

JIRA has a number of advanced configuration options, each of which is defined as an individual property (or 'key' associated with a value). These key-value pairs are stored in one of three areas for use by JIRA:

The JIRA Database

The values of a small number of most commonly edited advanced configuration options are stored in the JIRA database. These values can be edited from the Advanced Settings page of JIRA's administration area. To access the values for editing:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > System. Select General Configuration to open the Administration page. See Configuring Advanced Settings for details.

Once any of these properties' values are changed, they become effective immediately.

The jira-config.properties file

Custom values for JIRA's remaining advanced configuration options (i.e. not stored in the JIRA database) are stored as individual key-value pairs in a file called jira-config.properties (located in the JIRA Home Directory). Typically, these options are of little interest to most JIRA system administrators. While these key-value pairs can be edited, JIRA must be restarted for any changed values to take effect.

Example contents to demonstrate format

 

(info) In new JIRA installations, this file may not initially exist and if so, needs to be created manually. For more information about editing the jira-config.properties file see here: How to edit the jira-config.properties file

The jpm.xml file

Default values for all* of JIRA's available advanced configuration options are stored in a file called jpm.xml (located in the <jira-application-dir>/WEB-INF/classes subdirectory of the JIRA Installation Directory). These default values are only used by JIRA if a property's value has not already been customized in either the JIRA database (via JIRA's 'Advanced Settings' page) or the jira-config.properties file.

(warning) The jpm.xml file should not be edited because any values that you customize in it will not be migrated automatically during subsequent JIRA upgrades. To change the value of a property for an advanced configuration option in JIRA, override the value of this property by redefining it in either:

  • The JIRA database (via JIRA's 'Advanced Settings' page).
    OR
  • The jira-config.properties file.

* JIRA recognises a small number of properties, which can be set in your jira-config.properties file but have no definition in the jpm.xml file. These properties:

  • typically represent advanced configuration options that are disabled when they are not defined in your jira-config.properties file and
  • when not specified in your jira-config.properties file, typically affect JIRA's behavior differently to when they are specified in your jira-config.properties file with no value.

Making changes to the jira-config.properties file

To make changes to the jira-config.properties file:

  1. Shut down JIRA (for example, by executing either the /bin/stop-jira.sh or \bin\stop-jira.bat file in your JIRA Installation Directory, or by stopping the JIRA service).
  2. Open the jira-config.properties file (located at the root of your JIRA Home Directory) in a text editor.
    (warning) This file may not exist if you are using a new JIRA installation or an upgraded JIRA installation where your previous JIRA version(s) had never been customized. If this file does not exist, create it using a text editor.
  3. Edit the appropriate properties in this file.
    (tick) Editing tips:
    • To determine the default value of a property whose value you wish to redefine, search for that property in the <jira-application-dir>/WEB-INF/classes/jpm.xml file (of your JIRA Installation Directory). The default value is defined in the <default-value/> sibling element of the relevant property's <key/> element.
    • To override a property's default value in jpm.xml (which is not already defined in your jira-config.properties file or available on the 'Advanced Settings' page):
      1. Copy the value of the relevant property's <key/> element from the jpm.xml file to the jira-config.properties file.
      2. In the jira-config.properties file, add an '=' after that property's key, followed by your custom value.
    • To disable a custom property's value in the jira-config.properties file, either 'comment out' the property with a preceding '#' symbol or remove the property from the file.
  4. Save your modifications to the jira-config.properties file.
  5. Restart JIRA.

See also

Setting Properties and Options on Startup — for changes like setting available memory, disabling email, enabling Jelly, etc.

17 Comments

  1. It would be splendid with some elaboration on the different properties that can be set this way.

    I am, in particular, interested in Project Key Pattern, and want to know what caveats there are if I change this. I have requests from the developers to try to make the project key better reflect the particual branch of the code they apply to and am considering changing this to include underscore and digits, and perhaps even allowing lower case characters.

     I realise that there might be problems involved with this but I can not forsee them all, hence the need for some best-practices here, I suppose.

    1. Hi, you should be able to use most ASCII characters without a problem.
      It usually best practice to keep the keys, short and memorable. I have seen numbers work well as well.
      Lower case will not work as we upper a lot of the keys. All keys are case insensitive.

      Cheers,
      Nick

  2. Is it possible to specify the component in the project key? For example, for issues in project "Foo" and component "Bar", then the pattern might be something like "Foo$Bar", and the keys would be FooBar1, FooBar2, etc.

    1. Oops... what I meant was "Foo$component" produces FooBar1, FooBar2, etc.

      1. I doubt this idea will ever be implemented. An issue is tracked under a project with the possibility of being under multiple components of it.

        I can't imagine how complex the key name will turn out to be due to multiple components or component name changes.

        Cheers,
        Kay Nny

        1. The rationale for this is that the issue number is a commonly-used term in discussion, e.g. "who's dealing with FOO-UE-289?" In this example, I know it's a user experience issue.

          1. I don't think it is a good idea to specify the component in a key.  You know some issues are caused by a defect in system design and we cannot simply say that they are in a single component. 

            What's more, I even doubt the fact that an issue's key is associated with the project key.  A project will be closed but the product will exist.  Not all issue, or bugs found in a project will necessarily be fixed before the project is closed.  Later you will start a new project to improve the product, those issues not fixed should be reused instead of creating some issues same as those not fixed before. 

            In short, a bug is found in, as a negative feature of, a product, a release, a build, or a work product. It is not a feature of a project. Its ID or key should be maintained automatically by the bug tracking system and independently of any projects.

            You know what. I don't like many phrases and terms used in JIRA. For example, project component is very confusing. A product component, or simply a component, is more reasonable.

        2. I agree with you on an issue possibly being in multiple components.

          And also we thought an issue was in component A and now we know it is in component Z in fact. Change its key? Yes! But you will find the references to it become rubbish!! A key should not be changed at will!!!

  3. For jira.subtask.quickcreateform.fields, the comment says "The values must be valid issue field ids (see IssueFieldConstants class)". I looked at IssueFieldConstants (http://docs.atlassian.com/software/jira/docs/api/3.10/com/atlassian/jira/issue/IssueFieldConstants.html), I found summary,assignee but not issuetype. Maybe the comment need to be corrected?

  4. how would I add "Original Estimate" to the subtask quick-form? I tried using the value specified in (http://docs.atlassian.com/software/jira/docs/api/3.12/constant-values.html#com.atlassian.jira.issue.IssueFieldConstants.TIME_ORIGINAL_ESTIMATE):

    jira.subtask.quickcreateform.fields = summary, issuetype=7, assignee, timeoriginalestimate

    when I try to submit the quick subtask form. stacktrace below: 

    java.lang.NullPointerException
    at com.atlassian.jira.issue.fields.screen.issuetype.DefaultIssueTypeScreenSchemeManager.getFieldScreenScheme(DefaultIssueTypeScreenSchemeManager.java:126)
    at com.atlassian.jira.issue.fields.screen.FieldScreenRendererImpl.(FieldScreenRendererImpl.java:50)
    at com.atlassian.jira.issue.fields.screen.FieldScreenRendererFactoryImpl.getFieldScreenRenderer(FieldScreenRendererFactoryImpl.java:35)
    at com.atlassian.jira.web.action.issue.IssueCreationHelperBeanImpl.createFieldScreenRenderer(IssueCreationHelperBeanImpl.java:167)
    at com.atlassian.jira.web.action.issue.CreateIssue.getFieldScreenRenderer(CreateIssue.java:228)
    at com.atlassian.jira.web.action.issue.CreateSubTaskIssueDetails.getFieldScreenRenderer(CreateSubTaskIssueDetails.java:133)
    at com.atlassian.jira.web.action.issue.CreateSubTaskIssueDetails.hasMandatoryFields(CreateSubTaskIssueDetails.java:142)
    at com.atlassian.jira.web.action.issue.CreateSubTaskIssueDetails.doValidation(CreateSubTaskIssueDetails.java:78)
    at webwork.action.ActionSupport.validate(ActionSupport.java:373)
    at webwork.action.ActionSupport.execute(ActionSupport.java:150)
    at com.atlassian.jira.action.JiraActionSupport.execute(JiraActionSupport.java:54)
    at webwork.dispatcher.GenericDispatcher.executeAction(GenericDispatcher.java:132)
    at com.atlassian.jira.web.dispatcher.JiraServletDispatcher.service(JiraServletDispatcher.java:211)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:802)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:252)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.jira.web.filters.AccessLogFilter.doFilter(AccessLogFilter.java:73)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.opensymphony.module.sitemesh.filter.PageFilter.parsePage(PageFilter.java:119)
    at com.opensymphony.module.sitemesh.filter.PageFilter.doFilter(PageFilter.java:55)
    at com.atlassian.jira.web.filters.SitemeshExcludePathFilter.doFilter(SitemeshExcludePathFilter.java:38)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.seraph.filter.SecurityFilter.doFilter(SecurityFilter.java:192)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.seraph.filter.TrustedApplicationsFilter.doFilter(TrustedApplicationsFilter.java:114)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.seraph.filter.BaseLoginFilter.doFilter(BaseLoginFilter.java:110)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.util.profiling.filters.ProfilingFilter.doFilter(ProfilingFilter.java:132)
    at com.atlassian.jira.web.filters.JIRAProfilingFilter.doFilter(JIRAProfilingFilter.java:16)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.jira.web.filters.ActionCleanupDelayFilter.doFilter(ActionCleanupDelayFilter.java:43)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.jira.web.filters.RequestCleanupFilter.doFilter(RequestCleanupFilter.java:50)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.johnson.filters.AbstractJohnsonFilter.doFilter(AbstractJohnsonFilter.java:72)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at org.tuckey.web.filters.urlrewrite.UrlRewriteFilter.doFilter(UrlRewriteFilter.java:350)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.gzipfilter.GzipFilter.doFilter(GzipFilter.java:89)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.core.filters.AbstractEncodingFilter.doFilter(AbstractEncodingFilter.java:37)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at com.atlassian.jira.appconsistency.db.DatabaseCompatibilityEnforcerFilter.doFilter(DatabaseCompatibilityEnforcerFilter.java:39)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:202)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:173)
    at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:213)
    at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:178)
    at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:126)
    at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:105)
    at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:107)
    at org.apache.catalina.valves.AccessLogValve.invoke(AccessLogValve.java:541)
    at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:148)
    at org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:869)
    at org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConnection(Http11BaseProtocol.java:664)
    at org.apache.tomcat.util.net.PoolTcpEndpoint.processSocket(PoolTcpEndpoint.java:527)
    at org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorkerThread.java:80)
    at org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool.java:684)
    at java.lang.Thread.run(Thread.java:619)

    1. Hi Luke and Francis,

      The solution to this is to use "timetracking" instead of "timeoriginalestimate". See JRA-14542. As documented there, I was able to reproduce that the field didn't appear if you used "timeoriginalestimate", but not your NullPointerException.

      If using "timetracking" doesn't fix it for you, can you please create a case in our support system, https://support.atlassian.com.

      Kind regards,
      Ian


      Ian Daniel
      JIRA Support Lead
      ATLASSIAN - http://www.atlassian.com
      Tried our new products yet? http://www.atlassian.com/software

  5. I made some edits to the Sub-Task display and Quick Create functionality to display more info, but I am having a hard time displaying the Fix Version in the Sub-Task display. I tried the following, but none of them seem to work. Any suggestions what the naming convention is for FixVersion so it will display in the Sub-Task display?

    I tried the following options:

    jira.table.cols.subtasks = issuekey,issuetype,status,assignee,fix_for_versions,progress
    jira.subtask.quickcreateform.fields = issuetype,summary,components,priority,assignee,fix_for_versions,timetracking

    jira.table.cols.subtasks = issuekey,issuetype,status,assignee,fixforversions,progress
    jira.subtask.quickcreateform.fields = issuetype,summary,components,priority,assignee,fixforversions,timetracking

    jira.table.cols.subtasks = issuekey,issuetype,status,assignee,fixversions,progress
    jira.subtask.quickcreateform.fields = issuetype,summary,components,priority,assignee,fixversions,timetracking

    1. I am using 'fixVersions' which works just fine (note the capital V)

  6. Would be nice if the jpm.xml file had the comments previously found in jira-application.properties. That way it was easy to know you were changing the right thing.

    Now you need to look it up on the interweb, paste it into jira-config.xml etc...

    1. This article does not mention if we should stop using jira-application.properties to set custom settings.

      Does this mean that jira-application.properties is only for the "jira.home" settings and nothing else?
      Does this mean that customisations, that are not available through JIRA Web Administration should be put into jira-config.properties, directly into the $JIRA_HOME directory?

      Running JIRA 5.1.8