Administrator Guide

Setup

Ovyka Satisfaction for JIRA is delivered as a Java Archive (JAR file). To install Ovyka Satisfaction plugin, the steps are the following :

• Go to Add-ons administration by clicking on Add-ons in administration drop down menu (you may be asked your password to access and administration page);
  
  
  
• In the left menu bar, click on Manage Add-ons;
  
  
  
• Once the Manage Add-ons page is loaded, click on the Upload Add-on link on the right of the page;
  
  
  
• In the popup window, click on the file chooser button, navigate to the place you downloaded the plugin jar file and click the upload button.

Once the plugin is installed, you'll see Ovyka Satisfaction in the User-installed add-ons list.

Workflow Requirements

Ovyka Satisfaction for JIRA sends the satisfaction mail when a workflow transition triggers a "resolved" event or "closed" event.

Please make sure to fix your workflow if you only use "generic events" in transitions, which are the default event for new transitions when creating workflows in JIRA.

Step by step instructions :

• Edit the relevant workflow (for the projects/issue types you wish to cover with Satisfaction surveys)
• Edit the last transition postfunctions. The last transition is usually going the one going to "Resolved" or "Closed", or whatever your final statuses are
• Edit the "generic event" postfunction, replace it with a "issue resolved" event (or "closed issue" event)
• save / publish your workflow
• finish activating / configuring the global & project configuration for Satisfaction for JIRA

Global Administration

In the administration area, in the left menu bar, you'll find a new section called Ovyka Satisfaction containing two links : Configuration and Email Template. Clicking the Configuration link will open the administration page for Ovyka Satisfaction plugin.

Ovyka Satisfaction plugin administration allows you to configure :

• the maximum evaluation value (5 or 10 stars);
• the global satisfaction survey fields available for projects.

Maximum evaluation value

To select between 5 or 10 stars as a maximum evaluation value, just select one of the radio buttons (default is 5). The modification is persisted immediatly, and a message informs you that your choice has been saved.

Minimum evaluation value and value display

Since version 1.3.4, it is possible to allow users to vote 0 star (instead of a minimum value of 1). This 0-based evaluation can be allowed by checking the miminum rating option reading 'Allow zero evaluations'.

The numeric value checkbox, reading 'Display numeric value', allows to display the value of each rating star in the satisfaction form, instead of only displaying stars. Here are two screenshots, showing the difference with the numeric value display turned off and on.

Numeric value display : OFF	Numeric value display : ON

Allow JIRA decoration

The Survey Decoration option allows to choose wether the JIRA header (navigation bar with menus) and footer must be displayed on the satisfaction survey page presented to your customers.

Here are two screenshots, showing the difference with the decoration allowed or not.

Allow JIRA decoration : ON	Allow JIRA decoration : OFF

Survey fields

The plugin comes with 4 preconfigured fields :

• Overall answer satisfaction
  • A rating field, where users can provide their global satisfaction about the resolution of their issues, by giving a rating from 1 to 5 stars.
  • This field cannot be deactivated or deleted.
• Time to answer satisfaction
  • A rating field where users can express their satisfaction about the time taken to resolve their issue, by giving a rating from 1 to 5 stars.
• Agent satisfaction
  • A rating field where users can express their feeling about the agent in charge of their issue, by giving a rating from 1 to 5 stars.
• Comment
  • A multi-line comment field where users can enter comments about the resolution of their issue.

The administration page presents these fields in a table, along with their description, their status (active or inactive), and action links.

Field actions

Change field name or description

When you hover your mouse over the name or description of a field, you'll see a small pen appear on the right of the field you're above. To change the field name or description, when your mouse is above the field you want to change, click on it, and the line will switch to Edit mode.

This will allow you to change the field name and/or description. Once you're done, click the Update button on the right of the line to save your changes. You are not allowed to enter empty field names and descriptions.

Deactivate field

Except for the first field (Overall answer satisfaction), all fields are can be deactivated. On the right of the field line, you'll see a Deactivate link. Click it to deactivate the field. Its status will change to Inactive and the link text will change to Activate. You can use this link again to reactivate the field.

Add field

Under the fields table, you'll find an Add new field button. If you want to add a new field, click on the Add new field button. It will open a popup window, where you can enter :

• the name of your field
• the description of your field
• the type of your field (rating (User evaluation) or comment (Multine user comment)).

All values are mandatory.

Once your field is created, it appears in the table above, and can be modified or deactivated like other fields.

Delete field

The fields preconfigured by Ovyka Satisfaction plugin when it's installed cannot be deleted (but may be deactivated, except for the Overall answer satisfaction field).

Fields created by administrators of your JIRA instance, on the other hand, can be deleted. For these fields, in the Action column, you'll see a Delete link. To delete your field, click on the Delete link. A warning popup will appear, explaining that deleting a field implies data losses, because all answers provided by users for this field will be deleted. If you click the Confirm popup link, your field and all its related data will disappear.

Administration sample view

Below is a screenshot of a sample configuration, where you'll see some features depicted :

• a field line in Edit mode;
• an administrator-added field (with a delete link);
• an inactive field;
• the Add new field button.

Notification Email Administration

In the administration area, in the left menu bar, the second link in Ovyka Satisfaction menu, Email Template, opens a page allowing to manage the template of the notification email sent to users.

Email template mode

Email template form and samples

When installed for the first time, the default template is selected, so the plugin works immediatly, out-of-the-box. But if you prefer, you can choose to create your own HTML email template. For this, check the Custom template option. When this is done, a template creation/testing form appears, as shown in the screenshot below :

Let's see what each element is for :

• Issue to use for preview : This input let's you select one of your existing issues, which allows to preview email templates with real values from the selected issue. Start typing an issue key, and the matching issues will appear in a selectable list. Continue typing to reduce the number of available issues : 
  
• Template title: This is the title of your template, only used internally.
• Subject template : The template of the email subject. In this template, you can use placeholders to inject values from the issue (either the selected issue for preview, or the closed/resolved issue for real notification emails).
• Body template : the HTML body of the email notification. This is where you create your email content. As in the subject, you can include placeholders, to inject values from the issue. This template must use at least one place holder : [survey.link], which injects the url of the survey form. You can use it in the href attribute of a <a> html tag.
• The blue buttons   under each template input area allow to switch between edition mode and preview mode.
• Buttons :
  • Save : saves your template;
  • Delete : deletes your template and replaces it by the default template;
  • Load sample : You can use this button to load one of the provided examples. Click this button, and a pop up window will open, with a carrousel showing the three available samples. Select the one you want to load, then click the Load Sample button. 

Here are the different sample templates shown in the pop up :

Placeholders

In both the subject and body templates of your notification email, you can use placeholder to inject values extracted from the issue for which the notification is being sent.

Close to the body template preview button, you'll find a help button :  .

Clicking this button will open a help screen, showing the placeholders that you can use in your templates, as shown on the screenshot below :

Among the available placeholders are :

• [summary]
  • Replaced by the issue summary
• [description]
  
  • Replaced by the issue description
• [last-comment]
  
  • Replaced by the last issue comment
• [custom-field-XXX]
  
  • Replaced by the value of the custom field identified by its id (XXX must be replaced by the custom field value) in the processed issue.
  • If the field contains a date, the default format will be used : yyyy-MM-dd HH:mm:ss
• [survey.link]
  
  • Adds url of the Satisfaction survey, to be added in a link href, for example.
• [custom-field-XXX|yyyy-MM-dd HH:mm:ss]
  • Same placeholder as above, but with a date/time format. If the custom field contains a date, it will be displayed using the provided format.
• [issue.XXX]
  • Allows to include any issue field value. XXX must be replaced by the name of the field to extract. For example, to extract the issue creation date, the placeholder must be : [issue.created]
  • If the field contains a date, the default format will be used : yyyy-MM-dd HH:mm:ss
  • Available issue fields :
    • reporter : the issue reporter
    • assignee : the issue assignee
    • reporterId : the reporter username
    • assigneeId : the assignee username
    • created : the issue creation date
    • updated : the issue update date
    • resolution : the issue resolution status
    • status : the issue workflow status
    • priority : the issue priority
    • issueType : the issue type
    • votes : the number of votes of this issue
    • watches : the number of watchers for this issue
    • resolutionDate : the issue resolution date
    • dueDate : the issue due date
    • summary : the issue summary
    • description : the issue description
    • key : the issue key (for example DEMO-1)
    • affectedVersion : the list of affected version for this issue
    • fixVersions : the list of fix versions for this issue
• [issue.XXX|yyyy-MM-dd HH:mm:ss]
  
  • Same placeholder as above, but with a date/time format. If the issue field contains a date, it will be displayed using the provided format.

Project Administration

To administrate Ovyka Satisfaction plugin for a specific project, first go to the Browse Project page for the project you want to configure (top menu > Projects > your-project-key ), then clink on the Administration link. This will open the main project administration page, showing panels for administration sections. You'll see a new panel, dedicated to Ovyka Satisfaction, looking like this :

This panel shows the current activation status of the plugin for the project (Active or Inactive), and provides a link to plugin configuration for the project. This link is also available in the left menu bar, and is called Ovyka Satisfaction.

Click on either link, and you'll access the plugin configuration page for your project.

Plugin Activation

When the plugin is not activated for a project, this page only contains one tab, showing the activation status, and a button to activate/deactivate the plugin for the project. It will look like this :

To activate Ovyka Satisfaction for the project, just click the Activate button. The activation status will change to Active, the button will change to Deactivate, and a new tab allowing to configure the plugin will appear, called Configuration.

Plugin Configuration for Project

Once the plugin is activated, click the Configuration tab, and you'll see a list of fields you can configure, like shown in the image below :

The fields shown here are fields that are active in the global plugin configuration. If you deactivate a field in the project configuration page, the field is deactivated for this project only. Other projects can continue to use this field, as long as it's active in the global plugin configuration.

You have not other action to take to configure Ovyka Satisfaction for your project. You can even leave it as it is. Basically, clicking the Activate button in project administration is enough for your project to benefit from Ovyka Satisfaction for JIRA features.

Statistics Access Permissions

The Permissions tab (added in version 1.2.2) adds  a new configuration tab called Permissions.

In this tab, you'll find a zone where you can select as many project roles as you wish, with the following effect :

• No role is configured : Every user with access to the project will be able to see the Satisfaction statistics;
• One (or more) role(s) is(are) configured : Only user having at least one of the configured role(s) will be allowed to see the Satisfaction statistics. Actually, users with none of the configured role(s) will not even see that the plugin is present (not appearing in the left-hand side menu).

To add roles, just start typing in the select box. The plugin will show you a drop box with all project roles matching the text you entered. To narrow down the list of roles, just continue typing. When you select a role, it is added to the select box and the permissions are immediately effective for the project.

REST API

Satisfaction data can be retrieved using REST API. An URL allows to retrieve all evaluations in one call.

API URL

The url to call to retrieve satisfaction data is :

http://<jira_base_url>/rest/satisfaction/1.0/project/evaluations/all/<project_id>

Here is an example call and the response (here there is only one evaluation :

curl -D- -u login:password -X GET  http://localhost:2990/jira/rest/satisfaction/1.0/project/evaluations/all/10000
[
   {
      "satisfaction":{
         "projectId":10000,
         "issueId":10000,
         "reporterId":"tstark",
         "answers":[
            {
               "fieldId":1,
               "fieldName":"Overall answer satisfaction",
               "intAnswer":4,
               "fieldType":"EVALUATION",
               "overall":true
            },
            {
               "fieldId":2,
               "fieldName":"Time to answer satisfaction",
               "intAnswer":2,
               "fieldType":"EVALUATION",
               "overall":false
            },
            {
               "fieldId":3,
               "fieldName":"Agent satisfaction",
               "intAnswer":4,
               "fieldType":"EVALUATION",
               "overall":false
            }
         ],
         "date":1491895646549,
         "issueDate":1491842255195
      },
      "issueTypeIconUrl":"/images/icons/issuetypes/story.svg",
      "userName":"Anthony Stark",
      "userAvatarlUrl":"http://www.gravatar.com/avatar/6c2823e1531be820e8c2a4d719e1d38f?d=mm&s=16",
      "userProfileUri":"/secure/ViewProfile.jspa?name=tstark",
      "issue":{
         "created":true,
         "subTask":false,
         "editable":true
      },
      "displayDate":"11/Apr/17 9:27 AM",
      "iso8601DisplayDate":"2017-04-11T09:27:26+0200",
      "creationDisplayDate":"10/Apr/17 6:37 PM",
      "iso8601CreationDisplayDate":"2017-04-10T18:37:35+0200",
      "overallScore":4,
      "issueDisplay":{
         "baseUrl":"/jira",
         "iconUrl":"/images/icons/issuetypes/story.svg",
         "key":"TP-1"
      },
      "userDisplay":{
         "id":0,
         "baseUrl":"/jira",
         "avatarUrl":"http://www.gravatar.com/avatar/6c2823e1531be820e8c2a4d719e1d38f?d=mm&s=16",
         "profileUrl":"/secure/ViewProfile.jspa?name=tstark",
         "name":"Anthony Stark"
      },
      "agentDisplay":{
         "id":0,
         "baseUrl":"/jira",
         "avatarUrl":"http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=16",
         "profileUrl":"/secure/ViewProfile.jspa?name=admin",
         "name":"admin"
      }
   }
]

In this example, you can find first the evaluation itself, then data about the issue, project, the agent in charge of the issue, and the reporter (user).

Authentication & Authorization

To access the API, you must provide an authentication. The user calling the API must also have access to target project, otherwise no data will be sent back to API calls.

Authentication

Authentication data can be provided in three ways :

Basic

You can provide credentials using a basic way, like this :

curl -D- -u login:password -X GET  <aPI_URL>

Base64

You can also send the credentials Base64 encoded, as follows :

curl -D- -X GET -H "Authorization: Basic ZnJlZDpmcmVk" <API_URL>

OAuth

Finally, you can use JIRA Application Links functionality to connect using OAuth.

To configure OAuth, here is the step by step guide. Here I'm using a command line rest client, but you can configure any OAuth-capable application instead.

First, you need to configure an application link.

Go in JIRA Applications administration, then select Application LinksRendez-vous dans l'administration de Confluence (General Configuration) et cliquez sur Application Links dans le menu de gauche. Sur l'écran listant les appLinks, entrez l'url de l'application devant se connecter au plugin et cliquez sur Create New Link. Si votre application n'a pas d'url, entrez une url qui ne répondra pas, peu importe pour la suite.

Lorsque vous cliquez sur le bouton de création, Confluence risque (dans certains cas) d'afficher une fenêtre indiquant que l'application ne répond pas, comme ci-dessous. Ce n'est pas important, cliquez sur Continue.

Confluence vous demande ensuite les informations de paramétrage de la connexion OAuth, comme dans l'écran ci-dessous :

Entrez les informations suivantes :

• Application Name : Donnez un nom à l'application cible.
• Application Type : Obligatoirement Generic Application, normalement pré-rempli.
• Service Provider Name : C'est Confluence, entrez ce que vous voulez pour l'identifier.
• Consumer key : la clef identifiant le consumer OAuth (la même que configurée dans votre application). Ici j'utilise une clef codée en dur dans le client de test que j'utilise : harcoded-consumer.
• Shared secret : la clef partagée (ou clef publique) associée au consumer entré au dessus.
• Request Token URL : CONLFUENCE_BASE_URL + "/plugins/servlet/oauth/request-token"
• Access Token URL : CONLFUENCE_BASE_URL + "/plugins/servlet/oauth/access-token"
• Authorize URL : CONLFUENCE_BASE_URL + "/plugins/servlet/oauth/authorize"

Pour exemple, l'url de base (CONFLUENCE_BASE_URL) de l'instance Confluence utilisée ici est http://localhost:1990/confluence. Par conséquent, la Request Token URL est donc : http://localhost:1990/confluence/plugins/servlet/oauth/request-token.

Cliquez ensuite sur Continue. Confluence vous demande les détails du consumer (la consumer key et le public key (shared secret) ont déjà été entrées à l'étape précédente, mais il faut les entrer de nouveau ici...

Cliquez sur Continue. Confluence configure le lien, et il doit apparaître ensuite dans la liste des AppLinks configurés, comme ci-dessous :

La configuration de l'AppLink dans Confluence est terminée. Vous pouvez commencer à utiliser le plugin depuis votre application, en utilisant le protocole d'autorisation OAuth. Dans le paragraphe suivant, une démonstration est présentée en utilisant un client simple en ligne de commande.

Appel du plugin via un client OAuth

La démonstration qui suit utilise un client en ligne de commande. Certaines manipulations ne sont pas nécessaires avec une application plus évoluée qui sait gérer le protocole OAuth seul.

D'abord, j'utilise mon client pour demander à Confluence un RequestToken.

zeus:rest-oauth phoenix$ java -jar rest-oauth-client-1.0.one-jar.jar requestToken http://localhost:1990/confluence
Token is MdJ8Zqsokinlsr3XgGGufBRHsrKYf3JH
Token secret is 8bH6kMgIuTHFqIu1ZR6DbkKUMBB287jc
Retrieved request token. go to http://localhost:1990/confluence/plugins/servlet/oauth/authorize?oauth_token=MdJ8Zqsokinlsr3XgGGufBRHsrKYf3JH 

Confluence me répond en me fournissant une url que je dois ouvrir pour autoriser l'accès de mon client dans Confluence. L'écran présenté lors de l'ouverture de l'url est le suivant :

Confluence me demande d'autoriser l'accès et m'indique que les accès effectués via le token OAuth qui sera généré le seront en mon nom (admin). L'utilisateur utilisé est celui qui est connecté à Confluence lors de l'accès à l'url fournie. Si vous n'êtes pas connecté, Confluence vous demandera d'abord de vous connecter avant d'afficher l'écran d'autorisation OAuth.

Je clique sur Allow, et  Confluence m'affiche un écran contenant le code de vérification :

Je peux donc demander à mon client de récupérer un AccessToken, qui me servira pour effectuer mes appels au plugin.

zeus:rest-oauth phoenix$ java -jar rest-oauth-client-1.0.one-jar.jar accessToken http://localhost:1990/confluence MdJ8Zqsokinlsr3XgGGufBRHsrKYf3JH 8bH6kMgIuTHFqIu1ZR6DbkKUMBB287jc k621j4
Access token is : oSsNuFfMwL3MDDxYZQ1J1DeU05LDPRiV

Ici j'ai fourni, dans l'ordre, le RequestToken et le Token Secret fournis lors de mon premier appel ci dessus, suivis du code de vérification fourni par confluence après l'autorisation de l'accès. Confluence me répond en me fournissant l'AccessToken.

Je peux ensuite appeler le plugin directement depuis mon client, sans fournir de login/password :

zeus:rest-oauth phoenix$ java -jar rest-oauth-client-1.0.one-jar.jar request oSsNuFfMwL3MDDxYZQ1J1DeU05LDPRiV http://localhost:1990/confluence/rest/docfinder/1.0/find/key/AAA123457
RESPONSE IS {"key":"AAA123457","status":401,"message":"One document found.","results":["http://localhost:1990/confluence/download/attachments/983044/gefco-atlas.csr?version=1&modificationDate=1445446105491&api=v2"]}

Si vous appelez le plugin sans fournir d'accès token, le plugin vous répondra qu'il n'a pas pu identifier l'utilisateur, comme ci-dessous :

zeus:rest-oauth phoenix$ curl  -X GET "http://localhost:1990/confluence/rest/docfinder/1.0/find/key/AAA123457"
{"status":201,"message":"User was not found."}

Contact

Should you have any questions about Ovyka Satisfaction for JIRA plugin, or should you encounter any problem using it, feel free to contact us by dropping an email to this address : contact@ovyka.com