This page last changed on Jun 24, 2010 by rosie@atlassian.com.
JIRA 4.1+ now uses form tokens as an additional level of security against cross-site request forgery. See Form Token Handling for details on how your external HTML form will handle form tokens

If you would like your users to create issues from another site, you can by putting links to your JIRA's create issue page. You can also populate the fields on the page with values to select the project, the issue type or even the summary of the issue. This document will detail how to construct theses links and how to populate the fields. This feature is available from JIRA 3.5 onwards.

How to construct the link

The minimal HTML link to create issues has the following structure:

<a href="[JIRA BASE URL]/secure/CreateIssueDetails!init.jspa?[ARGUMENTS]">[DESCRIPTION]</a>

where

Component Description Example
[JIRA BASE URL]  The Base URL of the JIRA you wish to create issues in http://jira.atlassian.com
[ARGUMENTS]  List of key value pairs separated by '&' which represent the field and its value to be set in the create issue screen pid=10420&issuetype=4
[DESCRIPTION]  The link description visible to users create issue in Test Project

JIRA Base URL

This Base URL is the same as the JIRA Base URL you wish to create issues in. This can be found under the admin section -> General Configuration -> Settings. For example, http://jira.atlassian.com is the base URL of the JIRA running at Atlassian.

The Arguments

The list of key value pairs included define which fields will have what values set. The argument list has the following properties:

  • Each key value pair is separated by an '&'
    • For Example: [keyValuePair]&[keyValuePair]&[keyValuePair]...
  • Each key value pair has the form 'key=value' where key is a field name and the value is the desired value to be set for its corresponding field
    • For Example: 'pid=10420&issuetype=1&summary=helloWorld&description=greetings'...
  • The list must comply with HTML link syntax - that is all characters must be escaped.
    • Characters like space cannot be used directly, they must be encoded (escaped). Hence to use a space, we would replace the space with a '+' or '%20' which is the space equivalent. An excellent HTML URL-encoding reference listing all the characters and their corresponding encoded symbol can be found here
    • For Example: 'summary=This+is+a+summary%20with%20escaped+spaces'

As you can see, constructing the argument list is relatively simple. All we need is the name of the fields we want to set values for, and just structure it as above.

Fields thats not set will simply be assigned their normal default values. And the issue is not created until the user submits the form (this includes a validation check to confirm the field values are correct).
Finding out the field names and its possible values

The key in the key-value pair is the fields name, and to set a value for that field, we first need to know its name. The name of the field can be found by examining the source code of the page in which the field is in (To view the source code of a page, right click on the browser and select 'View source' or alike). Each field has a name attribute which represents the fields name. So all you need to do is find that attribute.

To find the possible values you can set is a bit more tricky. For any fields which accept plain text (such as summary, description and environment) there are no restrictions. However for other fields (such as Project, Issue Type, etc which take in Id) will require you to find the Id values. The range of Id values you can set can be found examining the same source code you found the field name from.

For example, the following is the HTML source code from the create issue page. From this we know that the Components field has the key 'components' with values '10013', '10014' and '10015' for each of the 3 components.

...
<select multiple name="components" id="components" size=" 3 ">
  <option value="-1">Unknown</option>
  <option value="10013" title="New Component 1  - ">New Component 1</option>
  <option value="10014" title="New Component 2  - ">New Component 2</option>
  <option value="10015" title="New Component 3  - ">New Component 3</option>
</select>
...

The following table shows a sample list of the standard JIRA fields with their name (key), the type of value expected and an example of the value

Display Name
Key Value Type Value Examples
Project pid
Project Id
' 10420'
Issue Type
issuetype
Issue Type Id
standard JIRA issue type values range from '1' to '4'
Summary summary
Plain Text
'issue+created%20via+link'
Priority
priority
Priority Id
standard JIRA priority values range from '1' to '5'
Due Date duedate Date
'15-Dec-2005' - may have different format depending on your JIRA date settings
Components components Component Id
'10014'
Affects Version/s versions Version Id
'10015'
Fix Version/s: fixVersions Version Id
'10015'
Assign To assignee Username
'admin' or 'sam@atlassian.com'
Reporter reporter Username
'admin' or 'sam@atlassian.com'
To have the reporter field default to the currently logged in user, the user must be logged in and must not have the Modify Reporter permission.
Environment environment Plain Text
'this+is+the+environment'
Description description Plain Text
'this+is+the+description'
Custom Fields
Custom Fields key and value can be found by examining the source code also. There name/key are prefixed by 'customfield_' followed by their custom field id. For Example: 'customfield_10000'

Examples

Here are some simple examples to help you on your way. These examples provide links to create issue in JIRA Atlassian Test Project.

Source Code  Output
To create an improvement issue in the Test project, click
<a href="http://jira.atlassian.com/secure/CreateIssueDetails!init.jspa?pid=10420&issuetype=4">here</a>
To create an improvement issue in the Test project, click here
To create a task with summary 'say hello world', click
<a href="http://jira.atlassian.com/secure/CreateIssueDetails!init.jspa?pid=10420&issuetype=3&summary=say+hello+world">here</a>
To create a task with summary 'say hello world', click here
To create a task with multiple values selected for a field, click
<a href="http://jira.atlassian.com/secure/CreateIssueDetails!init.jspa?pid=10420&issuetype=3&summary=say+hello+world&fixVersions=10331&fixVersions=13187">here</a>
To create a task with multiple values selected for a field, click here

   A more detailed example to
   <a href="http://jira.atlassian.com/secure/CreateIssueDetails!init.jspa?pid=10420&issuetype=2&summary=detailed+example
   &description=description+goes+here&components=10240&duedate=7%2dDec%2d2005
   &customfield_10010=this+is+a+custom+field">
   create an issue.</a> Has description, components, due date and a custom field preset.

A more detailed example to create an issue. Has description, components, due date and a custom field preset.
Document generated by Confluence on Mar 27, 2011 18:51