Differences

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

--- 711:process_feedback_jira_new [2025/04/14 08:30] – [Configuring Jira Variant] Heindl, Christoph
+++ 711:process_feedback_jira_new [2025/04/15 14:23] (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">
-        <!-- Optionally 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>
-===== 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.
-=== Jira Data Center with username and password ===
-  * The ''user'' and ''password'' are the normal username and password of the user.
-  * [[https://confluence.atlassian.com/enterprise/disabling-basic-authentication-1044776464.html|Basic authentication must not be deactivated]]
-<code xml>
-<property name="authentication.type" value="basic" />
-<property name="user" value="jdoe" />
-<property name="password" value="my-secret*password" />
-</code>
-=== Jira Cloud with API-Token ===
-In Jira cloud there are no usernames. The ''username'' is the mail address (e.g. ''john.doe@example.com''). The **password is a API-Token** and not the password of the user. You can create a token in your [[https://id.atlassian.com/manage-profile/security/api-tokens|Atlassian Account Management]].
-<code xml>
-<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>
-==== Personal Access Tokens (Bearer) Authentication on Jira Data Center ====
-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="authentication.type" value="bearer" />
-<property name="bearer" value="NTkzMzQ1ODIyNTAwOtuxKyI7Q2dPtIVtSTr7+Viwg6H3" />
-</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 (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-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"'' (Since Stages 7.9.10.0 / 7.10.1.0)
-  * User Picker (single user): ''targetType="user-singleChoice"'' (Jira Cloud: Since Stages XXXX)
-  * User Picker (multiple users): ''targetType="user-multipleChoice"'' (Jira Data Center: Since Stages 7.9.10.0 / 7.10.1.0, Jira Cloud: Since Stages XXXX)
-  * Assignee: ''target="assignee" targetType="user-singleChoice"''
-  * Reporter: ''target="reporter" targetType="user-singleChoice"''
-  * 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 [[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.
-===== 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.
-===== 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.