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">
 
        <!-- Define Jira variant - defaults to "server"-->
        <property name="jira.variant" value="server"/>
 
        <!-- 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>

Add the host property jira.variant to your config.xml to configure which variant of Jira you are using, i.e. cloud, server or data-center. The default value is server.

<property name="jira.variant" value="cloud" />

Note that for Jira Cloud jira.variant must be set in order to use user-singleChoice and user-multipleChoice fields.

There are different authentication methods for Jira Data Center and Jira Cloud. Choose the method that works best for your system.

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

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

<property name="jira.variant" value="data-center" />
<property name="authentication.type" value="basic" />
<property name="user" value="jdoe" />
<property name="password" value="my-secret*password" />

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

<property name="jira.variant" value="data-center" />
<property name="authentication.type" value="bearer" />
<property name="bearer" value="NTkzMzQ1ODIyNTAwOtuxKyI7Q2dPtIVtSTr7+Viwg6H3" />

A Jira user can request API tokens with and without scopes. An Atlassian service account can only obtain API tokens with scopes.

In order to create a feedback issue, the user or service account needs to have write access to the specific project.

In Jira Cloud, the user property is the email address (e.g. john.doe@example.com). The API token, not the user's password, is used for the password property:

<property name="jira.variant" value="cloud" />
<property name="authentication.type" value="basic" />
<property name="user" value="john.doe@example.com" />
<property name="password" value="ATATT3xS68pShK-hY6D84jrZdck3wHFEYraLpRqgvXA8mcPxiAPYfLpkBvQZm5g-mP3JkfCYnvePqLAjSssTQAmjKACSgXcrffEbKDLmv2jJpj_KGs7R2LfQHgbe5v-6FMwLx66pPsAuxJdzdR8Sx92JHuoFctJ6VCKozo5Q_F3hEFQwKWw2G-U=5AF3BC19" />

One of the following scopes needs do be configured for the API token:

• Classic: write:jira-work
• Granular: write:issue:jira

If you want to map a value to a user field in Jira (targetType user-singleChoice or user-multipleChoice) you need in addition one of the following scopes:

• Classic: read:jira-user
• Granular: read:user:jira

In Jira Cloud, the user property is the email address (e.g. example-4jaisfjasdjf@serviceaccount.atlassian.com). The API token, not the user's password, is used for the password property:

Tokens with scopes have to use a special REST endpoint provided by Atlassian. The URL of the Endpoint contains the cloud id of your Jira Cloud instance. The endpoint has a specific format that must be specified in the configuration:

https://api.atlassian.com/ex/jira/{cloud-id}/rest/

<property name="jira.variant" value="cloud" />
<property name="authentication.type" value="basic" />
<property name="user" value="example-4jaisfjasdjf@serviceaccount.atlassian.com" />
<property name="password" value="ATATT3xS68pShK-hY6D84jrZdck3wHFEYraLpRqgvXA8mcPxiAPYfLpkBvQZm5g-mP3JkfCYnvePqLAjSssTQAmjKACSgXcrffEbKDLmv2jJpj_KGs7R2LfQHgbe5v-6FMwLx66pPsAuxJdzdR8Sx92JHuoFctJ6VCKozo5Q_F3hEFQwKWw2G-U=5AF3BC19" />
<property name="jira.rest.endpoint" value="https://api.atlassian.com/ex/jira/11111111-1111-1111-1111-111111111111/rest/" />

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”
• User Picker (single user): targetType=“user-singleChoice”
• User Picker (multiple users): targetType=“user-multipleChoice”
• Assignee: target=“assignee” targetType=“user-singleChoice”
• Reporter: target=“reporter” targetType=“user-singleChoice”
• Components: target=“components” targetType=“components”
• Radio Buttons: targetType=“radio”
• Checkboxes: targetType=“checkbox”
• Labels: targetType=“labels”
• Affects Versions: target=“versions” targetType=“version-multipleChoice”
• Fix Versions: target=“fixVersions” targetType=“version-multipleChoice”
• Version Picker (single version): targetType=“version-singleChoice”
• Version Picker (multiple versions): targetType=“version-multipleChoice”

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.