With this feature, users are able to provide feedback directly while navigating through the process. The feedback is created as a Jira item and can be triaged, planned, and tracked within Jira. Every generated Jira item contains a link back to the original process element where the feedback was being created, so full traceability of process change requests is assured.

For configuration a Jira project is necessary. In Stages changes in config.xml and metamodel are required.

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-system name="jira">
    <host url="https://jira.example.com/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  -->
 
      <!--
      The user will be asked to enter the following text fields. All text fields are optional.
      - The "ident" must be unique and is used to identify the right translation property.
      - The "type" defines if the field is a multi-line text ("text") or a single line string ("string").
      - 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" />
        <!-- The following fields could be enabled if you want the users to provide more data with every feedback item: -->
        <!--
        <attribute ident="annual_savings" type="string" target="customfield_10100" />
        <attribute ident="priority" type="string" target="customfield_10101" />
        <attribute ident="component" type="string" target="components" targetType="components" />
        -->
      </attributes>
 
      <!--
      You can map element specify information to your Jira issue. These sources are available:
      - elementUrl e.g. https://stages.example.com/stages/index.html#/workspace/200/_vv/(process/activity/_wUV9sBbNHr-aicWx33VsQA)
      - workspaceName e.g. "Software Engineering"
      - workspacePath e.g. "Company | Software"
      - creatorFullname "John Doe"
      - creatorUsername "jdoe"
      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>
    </host>
  </feedback-system>
</stages-config>

• Description: targetType=“” (Empty)
• Text Field (single line): targetType=“” (Empty)
• Text Field (multi line): targetType=“” (Empty)
• Select List (single choice): targetType=“selectList-singleChoice”
• Components: targetType=“components”

Be aware: If you choose Select or Component then the user entered values must be configured in Jira. 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" />

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

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

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

The feedback widget must be added to your Stages metamodel. The XML-Element is:

<widget:feedback/>

For adding the widget to the social section, you can adopt it like this:

<widget:definition id="social">
    <layout:tabbed-card id="info">
        <layout:tab id="feedback" translate="process.feedback">
            <widget:feedback/>
        </layout:tab>
        <layout:tab id="comments" translate="process.comments">
            <widget:comments/>
        </layout:tab>
        <layout:tab id="history" translate="process.history">
            <widget:activity-stream translateNone="none" />
        </layout:tab>
    </layout:tabbed-card>
</widget:definition>

As last step you have to provide translations for the introduced custom fields. The translation property consists of the prefix process.feedback.mapping. and the ident you defined in the config.xml file. For the example the translations are:

process.feedback.mapping.summary = Summary
process.feedback.mapping.description = Description
process.feedback.mapping.annual_savings = Estimated annual savings
process.feedback.mapping.priority = Priority

After all, don't forget to execute update.bat / update.sh and restart your Stages.