Ovyka Satisfaction for JIRA is delivered as a Java Archive (JAR file). To install Ovyka Satisfaction plugin, the steps are the following :
Once the plugin is installed, you'll see Ovyka Satisfaction in the User-installed add-ons list.
By default, Ovyka Satisfaction for JIRA sends the satisfaction mail when a workflow transition triggers a "resolved" event or "closed" event.
Since version 1.6.0 you can choose to change this behaviour with the global configuration, see Notificationtriggerselection
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 :
Step by step instructions :
Please note the Satisfaction Survey Sending Post Function can also work in parallel to event based notification triggers.
Here is the transition post functions with Satisfaction post function added.
Please note that the survey will be resent to the reporter if another resolved/closed event or postfunction is triggered and the reporter hasn't answered yet.
Example use case: You can use this to make sure that the reporter receives another notifications when "closing" the ticket 7 days after it has been "resolved".
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 :
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.
These features are available since plugin version 1.3.4. |
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 |
|---|---|
 |  |
These features are available since plugin version 1.4.0 |
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 |
|---|---|
 |  |
These feature is available since plugin version 1.6.0. For JIRA versions prior to 7.0.0, you will need version 1.6.1, as version 1.6.0 is not compatible with JIRA 6.3 and 6.4. |
The default behaviour of Ovyka Satisfaction for JIRA is to send notification when a specific issue event (Resolved or Closed) is fired. You can choose to also add a post-function, or to only use post functions and completely disable issue events handling in the plugin. To do this, choose the notigcation trigger(s) you prefer in the global administration page, as shown below :
These feature is available since plugin version 1.6.0 For JIRA versions prior to 7.0.0, you will need version 1.6.1, as version 1.6.0 is not compatible with JIRA 6.3 and 6.4. |
For finer control of which tickets need a satisfaction form to be sent, you can configure a JQL query.
Here are a few example use cases :
only send the survey to reporters who are external customers:
reporter in membersof("external customer group") |
only for specific issue types: e.g. if you want satisfaction surveys for bug resolution only
issuetype = "Bug" |
To configure JQL context, go into global administration page for Ovyka Satisfaction for JIRA and update the JQL query int the JQL context section, as shown below :
The plugin comes with 4 preconfigured fields :
The administration page presents these fields in a table, along with their description, their status (active or inactive), and action links.
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.
The values you change (field name or description) are updated for the current locale (ie. the locale you're using as an adminstrator). Ovyka Satisfaction plugin provides translation for 2 languages : English and French. If you want to change fields in a locale different of yours, change your locale in your profile and come back to the plugin administration page to edit field names/descriptions. |
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.
You should know that when you deactivate a field in the global plugin administration, it is automatically deactivated for all projects using the plugin. This does not lead to data losses, but a globally deactivated field will not be available to projects until it is reactivated. |
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 :
All values are mandatory.
Once your field is created, it appears in the table above, and can be modified or deactivated like other fields.
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.
Below is a screenshot of a sample configuration, where you'll see some features depicted :
This feature is available since plugin version 1.1.0. |
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.
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 :
under each template input area allow to switch between edition mode and preview mode.Here are the different sample templates shown in the pop up :
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 :
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.
If your project is a JSD project, and you're using recent version of JIRA Service Desk, a customer satisfaction feature is provided, and your customers will receive two satisfaction surveys notifications - one for JIRA Service Desk, and one for Ovyka Satisfaction for Jira. You should disable JIRA Service Desk satisfaction surveys to make sure that only Ovyka Satisfaction for JIRA surveys notifications are sent to your customers. To do this, go to your project administration, select Satisfaction settings, and disable "Collect customer satisfaction feedback". See screenshot below for the target configuration.
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.
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.
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 :
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.
These features are available since plugin version 1.4.1. |
Satisfaction data can be retrieved using REST API. An URL allows to retrieve all evaluations in one call.
The url to call to retrieve satisfaction data is :
http://<jira_base_url>/rest/satisfaction/1.0/project/evaluations/all/<project_id> |
Or to export the evaluations data as CSV, here is the URL to call :
http://<jira_base_url>/rest/satisfaction/1.0/project/evaluations/csv/<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 data can be provided in three ways :
You can provide credentials using a basic way, like this :
curl -D- -u login:password -X GET <aPI_URL> |
You can also send the credentials Base64 encoded, as follows :
curl -D- -X GET -H "Authorization: Basic ZnJlZDpmcmVk" <API_URL> |
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 Links. Enter your application URL (the one going to call the REST API), then click Create New Link. If your application does not have an URL, enter any non existing URL, it's not important (unless you really want the full OAuth mechanism, with callbacks).
Sometimes, or if your application does not have any URL, you'll see this window, complaining that the application does not answer. Just click Continue.
You'll then be asked for OAuth configuration data, as shown below :
Enter the following information :
For the example, the base url (JIRA_BASE_URL) is http://localhost:2990/jira. So, for example, the Request Token URL is : http://localhost:2990/jira/plugins/servlet/oauth/request-token
Then click on Continue. JIRA will ask you again the consumer details (consumer key and public shared key), you have to enter them again.
Click on Continue. Cliquez sur Continue. JIRA will configure the link, and it will appear in your list of application links, as shown below. JIRA Application link configuration is done now. You can start using the REST API using OAuth authorization.
In next section, I'll demonstrate an example, of authorization setup and REST API usage.
Here I'm using the REST client mentionned above. Some commands are not mandatory when using a more advanced application that knows how to handle OAuth protocol.
First, I'm asking for a RequestToken.
Note here that I do not provide a callback URL. This url would be called by OAuth processor, to continue OAuth protocol conversation. I'm doing everything by hand here, on the command line. If you provide this url, the verification we'll get below will be sent back to our application automatically. |
$ java -jar rest-oauth-client-1.0.one-jar.jar requestToken http://localhost:2990/jira Token is mnVb4mCmjWO9PBmeN5jYXvb6g3q8w2bw Token secret is InO6HnmbWGbhJCDr5aWvmpT2r0OTrlfz Retrieved request token. go to http://localhost:2990/jira/plugins/servlet/oauth/authorize?oauth_token=mnVb4mCmjWO9PBmeN5jYXvb6g3q8w2bw |
JIRA answers with :
Here is what is shown when accessing the url :
JIRA asks me to authorize the access and indicates that the calls made using this allowed OAuth token will be made using the credentials of the user who opens the authorization url (admin here). If you want a specific user to be used for API calls, make sure to use this user to access this authorization url.
I click on Allow, and JIRA provides me the verification code (the one that would be sent to your application directly if you provide a callback url).
I can then request for an AccessToken, that I will be using to make calls to the plugin REST API.
$ java -jar rest-oauth-client-1.0.one-jar.jar accessToken http://localhost:2990/jira mnVb4mCmjWO9PBmeN5jYXvb6g3q8w2bw InO6HnmbWGbhJCDr5aWvmpT2r0OTrlfz rbi2v9 Access token is : lZNpyhPR6YmpQ3b0iM69bhcMVpjM3K3e |
I gave here, ordered :
JIRA then provides the AccessToken.
I can then call the plugin REST API :
$ java -jar rest-oauth-client-1.0.one-jar.jar request lZNpyhPR6YmpQ3b0iM69bhcMVpjM3K3e http://localhost:2990/jira/rest/satisfaction/1.0/project/evaluations/all/10000
RESPONSE IS[{"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"},"field1":{"name":"Overall answer satisfaction","fieldId":1,"issueId":10000,"value":"4","rating":true},"field2":{"name":"Time to answer satisfaction","fieldId":2,"issueId":10000,"value":"2","rating":true},"field3":{"name":"Agent satisfaction","fieldId":3,"issueId":10000,"value":"4","rating":true}}] |
If you don't provide the authentication, you'll receive an empty response :
$ curl -X GET http://localhost:2990/jira/rest/satisfaction/1.0/project/evaluations/all/10000 RESPONSE IS[] |
By default, users allowed to call the REST API are users having access to the target project. Whatever the authentication method used, if the user cannot see the project, he'll receive no answer for the REST API.
You can narrow this down by using the permission administration tab of the project admin panels :
Only users from the groups listed here will be allowed to retrieve the plugin data via the REST API. If no group is mentioned here, then the default project permission rule applies.
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