Table of Contents

Process Feedback Jira specific

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.

Stages config.xml

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>

Authentication

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

Basic Authentication

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" />

Jira Server / Data Center

Jira Cloud

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.

Personal Access Tokens (Bearer) Authentication (Since Stages 7.9.10.0 / 7.10.1.0)

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" />

OAuth 2.0 Password Grant (Optional)

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="" />

No Authentication (Since Stages 7.9.10.0 / 7.10.1.0)

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" />

Supported Jira fields

Be aware:

Other Jira fields are not supported at the moment.

Custom Endpoint (Optional)

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/" />

Proxy (Optional)

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" />

Custom Header (Optional)

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

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

Troubleshooting

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: