First of all, create a Jira project where the feedback will be collected. If you want to collect more information than the summary and a description, you have to add custom fields to your Jira project and add them to your Create Issue Screen. To locate the correct fields, use the Jira assistant “Where is my field?” for more info.

To configure Stages, ids of the Jira custom fields are required. There are several ways to find them out in the Jira documentation. The ids consist of the prefix customfield_ and a number e.g. customfield_10101.

Stages will use the Jira REST interface to create the issue. See here for more info.

To enable the following configuration section must be added in the conf/config.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<stages-config>
  <!-- Insert this block to your stages config.xml file -->
  <feedback-systems>
    <feedback-system name="jira">
        <host url="https://jira.example.com/jira" ident="jira1" displayName="Example Jira">
 
        <!-- Credentials for a (technical) user who is allowed to create issues in the Jira project -->
        <property name="authentication.type" value="basic" />
        <property name="user" value="user" />
        <property name="password" value="secret" />
 
        <!-- Define the project where the issue should be created in -->
        <property name="projectKey" value="FEED" />
        <!-- As alternative to the project key you can specify the project by its id -->
        <!-- <property name="projectId" value="1234" /> -->
 
        <!-- Define the name of the issue type that should be created -->
        <property name="issuetypeName" value="Task" />
 
        <!-- The summary field will always be available and is automatically mapped to the Jira "summary" field  -->
 
        <!-- 
        See common feedback documentation
        - The "target" defines the id of the custom field in Jira (e.g. "customfield_10101").
        - Optional: The targetType defines the type of the Jira field. Supported Jira fields see below.
        -->
        <attributes>
            <attribute ident="description" type="text" target="description" />
        </attributes>
 
        <!--
        See common feedback documentation
        The "target" defines the id for the custom field in Jira (e.g. "customfield_10101").
        Optional: The targetType defines the type of the Jira field. Supported Jira fields see below.
        -->
        <system-attribute-mappings>
            <attribute source="elementUrl" target="customfield_10104" />
            <attribute source="workspaceName" target="customfield_10105" />
            <attribute source="workspacePath" target="customfield_10106" />
            <attribute source="creatorFullname" target="customfield_10107" />
            <attribute source="creatorUsername" target="customfield_10108" />
        </system-attribute-mappings>
 
        <!--
        See common feedback documentation
        The "target" defines the id for the custom field in Jira (e.g. "customfield_10101").
        Optional: The targetType defines the type of the Jira field. Supported Jira fields see below.
        -->
        <custom-attribute-mappings>
            <attribute value="Stages" target="customfield_10200" />
        </custom-attribute-mappings>
        </host>
    </feedback-system>
  </feedback-systems>
</stages-config>

There are different ways to authenticate with Jira Server. Most common are Basic Authentication and Personal Access Tokens (Bearer).

You need credentials for a (technical) user who is allowed to create issues in the Jira project.

<property name="authentication.type" value="basic" />
<property name="user" value="user" />
<property name="password" value="secret" />

• The user and password are the normal username and password of the user.
• Basic authentication must not be deactivated

In Jira cloud there are no usernames. The username is the mail address (e.g. user@example.com). The password is a API-Token and not the password of the user. You can create a Token in your Atlassian Account Management.

Since Jira 8.14 it is possible to generate Personal Access Tokens to authenticate with Jira.

<property name="authentication.type" value="bearer" />
<property name="bearer" value="NTkzMzQ1ODIyNTAwOtuxKyI7Q2dPtIVtSTr7+Viwg6H3" />

This is a very special use case for a specific API gateway and not a standard Jira feature.

We support also OAuth 2.0 with Password Grant. To configure it there are different properties:

<property name="authentication.type" value="oauth20" />
<property name="authentication.oauth20.granttype" value="password" />
 
<!-- URL to your OAuth 2.0 Token Endpiont -->
<property name="authentication.oauth20.tokenendpoint" value="https://example.com/oauth/token" />
 
<!-- OAuth 2.0 Client Id -->
<property name="authentication.oauth20.clientid" value="" />
 
<!-- OAuth 2.0 Client Secret -->
<property name="authentication.oauth20.clientsecret" value="" />
 
<!--  OAuth 2.0 Scope -->
<property name="authentication.oauth20.scope" value="" />
 
<!-- OAuth 2.0 (technical) user -->
<property name="authentication.oauth20.user" value="" />
 
<!-- OAuth 2.0 password -->
<property name="authentication.oauth20.password" value="" />

This is a very special use case for a specific API gateway and not a standard Jira feature.

If there should be no authentication with Jira you can configure it. You probably want to set a Custom Header.

<property name="authentication.type" value="none" />

• Description: targetType=“” (Empty)
• Text Field (single line): targetType=“” (Empty)
• Text Field (multi line): targetType=“” (Empty)
• URL Field: targetType=“” (Empty)
• Select List (single choice): targetType=“selectList-singleChoice”
• Select List (multiple choices): targetType=“selectList-multipleChoice” (Since Stages 7.9.10.0 / 7.10.1.0)
• User Picker (single user): targetType=“user-singleChoice” (Only Jira Server, not Jira Cloud)
• User Picker (multiple users): targetType=“user-multipleChoice” (Since Stages 7.9.10.0 / 7.10.1.0, Only Jira Server, not Jira Cloud)
• Assignee: target=“assignee” targetType=“user-singleChoice” (Only Jira Server, not Jira Cloud)
• Reporter: target=“reporter” targetType=“user-singleChoice” (Only Jira Server, not Jira Cloud)
• Components: target=“components” targetType=“components”
• Radio Buttons: targetType=“radio” (Since Stages 7.9.10.0 / 7.10.1.0)
• Checkboxes: targetType=“checkbox” (Since Stages 7.9.10.0 / 7.10.1.0)
• Labels: targetType=“labels” (Since Stages 7.9.10.0 / 7.10.1.0)
• Affects Versions: target=“versions” targetType=“version-multipleChoice” (Since Stages 7.9.10.0 / 7.10.1.0)
• Fix Versions: target=“fixVersions” targetType=“version-multipleChoice” (Since Stages 7.9.10.0 / 7.10.1.0)
• Version Picker (single version): targetType=“version-singleChoice” (Since Stages 7.9.10.0 / 7.10.1.0)
• Version Picker (multiple versions): targetType=“version-multipleChoice” (Since Stages 7.9.10.0 / 7.10.1.0)

Be aware:

• If you choose Select or Component then the user entered values must be configured in Jira. Otherwise the ticket creation will fail.
• If you choose User Picker, Assignee or Reporter then the users must be vald Jira user. Otherwise the ticket creation will fail.
• To set the Reporter field it is mandatory to grant "Modify Reporter" to the technical user. Otherwise the ticket creation will fail.

Other Jira fields are not supported at the moment.

If your Jira REST-Endpiont differs from the standard location, you can specify it. If your link to the Jira-API is for example like https://api.example.com/example/api/2/issue then you have to specify https://api.example.com/example/ as value for this property.

<property name="jira.rest.endpoint" value="https://api.example.com/example/" />

You can specify a proxy server.

<property name="proxy.enabled" value="true" />
<property name="proxy.type" value="https" />
<property name="proxy.port" value="3128" />
<property name="proxy.hostname" value="proxy.example.com" />

You can set custom header to the Jira-REST-Requests.

<property name="jira.rest.customheader.key" value="" />
<property name="jira.rest.customheader.value" value="" />

If the username/​password settings are not correct or the password is changed on the Jira side, but not in Stages, Jira might lock the account after a few tries. This will result in a “HTTP 403 Forbidden”​ error in stages.log.

In that case, the Jira account needs to be unlocked again. Log into Jira as an administrator and follow these steps:

• Click on the Gear icon in the upper right of Jira
• Select “User Management”​
• Find the right user
• Click on the “Reset Failed Login Count” link in the “Login Details”​ column.