Differences

This shows you the differences between two versions of the page.

--- 712:process_feedback_jira_new [2025/11/19 12:15] – Policnik, Florian
+++ 712:process_feedback_jira_new [2025/11/19 12:33] (current) – removed Policnik, Florian
@@ Line 1: / Line 1: @@
-====== 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 [[https://confluence.atlassian.com/adminjiraserver/adding-a-custom-field-938847222.html|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 [[https://confluence.atlassian.com/jirakb/how-to-find-id-for-custom-field-s-744522503.html|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. [[https://docs.atlassian.com/software/jira/docs/api/REST/8.2.1/?_ga=2.49222754.599077736.1559584770-75849189.1559330334#api/2/issue-createIssue|See here]] for more info.
-===== Stages config.xml =====
-To enable the following configuration section must be added in the ''conf/config.xml'':
-<code 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>
-</code>
-===== Configuring Jira Variant =====
-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''.
-<code xml>
-<property name="jira.variant" value="cloud" />
-</code>
-Note that for Jira Cloud ''jira.variant'' must be set in order to use ''user-singleChoice'' and ''user-multipleChoice'' fields.
-===== Authentication =====
-There are different authentication methods for Jira Data Center and Jira Cloud. Choose the method that works best for your system.
-==== Jira Data Center ====
-=== Username / Password Authentication ===
-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.
-  * [[https://confluence.atlassian.com/enterprise/disabling-basic-authentication-1044776464.html|Basic authentication must not be disabled]]
-<code xml>
-<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" />
-</code>
-=== Personal Access Tokens ===
-Since Jira Data Center 8.14 it is possible to [[https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html|generate Personal Access Tokens]] to authenticate with Jira.
-<code xml>
-<property name="jira.variant" value="data-center" />
-<property name="authentication.type" value="bearer" />
-<property name="bearer" value="NTkzMzQ1ODIyNTAwOtuxKyI7Q2dPtIVtSTr7+Viwg6H3" />
-</code>
-==== Jira Cloud ====
-A [[https://id.atlassian.com/manage-profile/security/api-tokens|Jira user can request API tokens]] with and without scopes. An [[https://support.atlassian.com/user-management/docs/understand-service-accounts/|Atlassian service account]] can only [[https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/|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.
-=== API token without scopes ===
-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:
-<code xml>
-<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" />
-</code>
-=== API token with scopes ===
-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 [[https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/|cloud id of your Jira Cloud instance]]. The endpoint has a specific format that must be specified in the configuration:
-''<nowiki>https://api.atlassian.com/ex/jira/{cloud-id}/rest/</nowiki>''
-<code xml>
-<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/" />
-</code>
-==== 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:
-<code xml>
-<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="" />
-</code>
-==== No Authentication ====
-**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-optional|Custom Header]].
-<code xml>
-<property name="authentication.type" value="none" />
-</code>
-===== Supported Jira fields =====
-  * 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 [[https://community.atlassian.com/t5/Answers-Developer-Questions/Re-Assigning-a-reporter-when-creating-an-issue-with-rest/qaq-p/475645/comment-id/13300#M13300|mandatory to grant "Modify Reporter" to the technical user]]. Otherwise the ticket creation will fail.
-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 ''<nowiki>https://api.example.com/example/api/2/issue</nowiki>'' then you have to specify ''<nowiki>https://api.example.com/example/</nowiki>'' as value for this property.
-<code xml>
-<property name="jira.rest.endpoint" value="https://api.example.com/example/" />
-</code>
-===== Proxy (Optional) =====
-You can specify a proxy server.
-<code xml>
-<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" />
-</code>
-===== Custom Header (Optional) =====
-You can set custom header to the Jira-REST-Requests.
-<code xml>
-<property name="jira.rest.customheader.key" value="" />
-<property name="jira.rest.customheader.value" value="" />
-</code>
-===== 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:
-  * 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.