Process feedback
- Configuration

Process feedback

With this feature, users can provide feedback directly as they navigate the process. The feedback is created as a data item and can be triaged, planned, and tracked within a ticket system. Every generated item contains a link back to the original process element where the feedback was created, ensuring full traceability of process change requests.

Configuration

Changes in the Stages config.xml, metamodel and language properties are required. In general, this configuration looks like the following:

<?xml version="1.0" encoding="UTF-8" ?>
<stages-config>
 
  <!-- Insert this block to your stages config.xml file -->
  <feedback-systems>
    <feedback-system name="jira|rtc|redmine|ptcilm|codebeamer|link">
      <host default="true" url="https://some.example.com/feedback-system" ident="system1" displayName="Feedback System 1">
 
        <property name="propertyKey" value="propertyValue" />
 
        <attributes>
          <attribute ident="description" type="text" target="MyDescriptionField" targetType="MyFieldType" />
        </attributes>
 
        <system-attribute-mappings>
          <attribute source="elementUrl" target="MyField" targetType="MyFieldType" />
        </system-attribute-mappings>
 
        <custom-attribute-mappings>
          <attribute value="Stages" target="MySourceSystemField" targetType="MyFieldType" />
        </custom-attribute-mappings>
 
      </host>
      <!-- Add more hosts of same feedback system type here -->
    </feedback-system>
    <!-- Add more feedback system types here -->
  </feedback-systems>
</stages-config>

It is possible to define multiple feedback system types and feedback hosts. You can define a default feedback system by adding “default=”true”” to the host in config.xml, e.g., the first configured one. You can furthermore change the feedback system for each workspace in the workspace settings. Choosing a specific feedback system to set it permanently for the current workspace. Choose “Default” to set the feedback system to the configured default feedback system in config.xml (if no default=”true” is set, it is “Default (None)”). Choose “None” to not display the feedback widget in the current workspace.

Stages config

The changes in config.xml They are system-specific. Please refer to the right manual page:

Properties

<property name="propertyKey" value="propertyValue" />

Properties are configuration parameters for the feedback system. Every feedback system defines its own parameters, such as a username and password for authentication or a project name, etc. Properties are configured as key: value pairs.

Attributes

Attributes define the values visible to the feedback-creator. Each attribute will appear as a text box in the feedback widget and will be sent to the feedback system when the user clicks “save” in the Stages Application.

<attribute ident="description" type="text" target="MyDescriptionField" targetType="MyFieldType" />

ident: Stages translation property
type: Type of text field in Stags:
- string: Text Field (single line)
- text: Text Field (multi line)
target and targetType: Defines the feedback system-specific configuration

System Attribute Mappings

System attribute mappings are similar to the attributes, but are NOT visible in the Stages Application. The values for these attributes come directly from Stages.

<attribute source="elementUrl" target="MyField" targetType="MyFieldType" />

sourceWhich information from Stages should be taken? See also the picture below.
- Attributes of the current view where the user provides feedback
  - elementName: e.g., “Analyze Scope” (Since Stages 7.8)
  - elementShortname: e.g., “AS” (Since Stages 7.8)
  - elementLabel: e.g., “AS: Analyze Scope” (Since Stages 7.8)
  - elementType: e.g., “Workflow” (Since Stages 7.8)
  - elementIdentity: e.g. _wUV9sBbNHr-aicWx33VsQA (Since Stages 7.5.1.3)
  - elementUrl: Url to element
  - elementStableUrl: Url to element with specific version (Since Stages 7.5.1.3)
  - processVersionName: e.g. V1 (Since Stages 7.5.1.3)
  - workspaceName: e.g., Software Engineering
  - workspacePath: e.g., Company > Software
  - workspaceFullPath: e.g. Company > Software > Software Engineering (Since Stages 7.5.1.3)
  - creatorFullname: e.g., John Doe
  - creatorUsername: e.g., jdoe
  - creatorEmail: e.g. jdoe@example.com (Since Stages 7.5.2.2)
- If the process element was imported via a module import, the following attributes belong to the imported source module. Otherwise, or if the process element is overwritten, the attributes belong to the current view (Since Stages 7.9)
  - sourceModuleElementUrl: Url to element if the current element is imported by a module import
  - sourceModuleElementStableUrl: Url to element with specific version if the current element is imported by module import
  - sourceModuleWorkspaceName: e.g., Software Engineering
  - sourceModuleWorkspacePath: e.g., Company > Software
  - sourceModuleWorkspaceFullPath: e.g. Company > Software > Software Engineering
- If a process element is imported by multiple module imports, the following attributes belong to the module where the process element was originally created and can be edited. Otherwise, or if the process element is overwritten, the attributes belong to the current view
  - originElementUrl: Url to editable element if current element is imported by module import (Since Stages 7.5.1.3)
  - originElementStableUrl: URL to editable element with specific version if current element is imported by module import (Since Stages 7.5.1.3)
  - originWorkspaceName: e.g., Software Engineering (Since Stages 7.5.2.2)
  - originWorkspacePath: e.g. Company > Software (Since Stages 7.5.2.2)
  - originWorkspaceFullPath: e.g. Company > Software > Software Engineering (Since Stages 7.5.2.2)
target and targetType: Defines the feedback system-specific configuration

Custom Attribute Mappings

(Since Stages 7.5.1.3)

Custom attribute mappings are similar to the attributes, but are NOT visible in the Stages Application. The values for these attributes come directly from config.xml. You can map static values to fields in the feedback system.

<attribute value="Stages" target="MySourceSystemField" targetType="MyFieldType" />

value: The value that should be mapped
target and targetType: Defines feedback system-specific configuration

Script Attribute Mappings

If you want to map more complex values to your feedback system, you can run a script in Stages to aggregate additional mappings. The script can access the Facade API. Create a script feedback-demo.js like this and store it in your Stages conf folder:

if(currentElement) {
    var user = currentElement.getProperty("LastChangeUser");
    result.mappings.put("lastChangedBy", user); // Add script-attribute-mapping 'lastChangedBy'
}
result.properties.put("project", "Demo"); // Override property 'project'

Add to your feedback host configuration the attribute script with the file name as a value, and add a script-attribute-mappings section:

<?xml version="1.0" encoding="UTF-8" ?>
<stages-config>
  <feedback-systems>
    <feedback-system name="jira|rtc|redmine|ptcilm">
      <host url="https://some.example.com/feedback-system" script="feedback-demo.js" ident="system1" displayName="Feedback System 1">
        <!-- ... -->
        <property name="project" value="DefaultValue" />
        <script-attribute-mappings>
          <attribute source="lastChangedBy" target="MyField" targetType="MyLastChangedField" />
        </script-attribute-mappings>
      </host>
    </feedback-system>
  </feedback-systems>
</stages-config>

The script can access several pieces of information about the process:

Current process element: currentElement (In case of the process start page, it is null.)
Current user: currentUser
Logger: log
Pkit: pkit
- Current version of process: pkit.getCurrentProcess()
- Current workspace: pkit.getCurrentProject()
- …

The script cannot access the information that the user entered into an Attribute.

All results have to be stored in the predefined result variable.

Values in result.mappings are configurable in the XML via script-attribute-mappings
Values in result.properties will add or override the properties of the XML file

Stages metamodel

The feedback widget must be added to your Stages metamodel. We suggest to consult your Product Consultant for this step.

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>

Stages language properties

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.

Table of Contents