Admin Guide

JIRA


The JIRA app integrates Deskpro with the Atlassian JIRA issue tracker software.

jira-pane-example.png

Warning

Note that this documentation relates to the improved JIRA app introduced in November 2014 (Deskpro build #384).

If you are using the previous version of the app, it will be disabled when your helpdesk upgrades to the latest build. Installing the new app using the instructions below will restore all your JIRA links.

Once you install the app:

  • agents can link Deskpro tickets to existing JIRA issues or create a linked JIRA issue from a Deskpro ticket.

  • agents can add comments to a JIRA issue from a linked ticket.

  • when replying to a ticket, agents can also choose to send the message to JIRA as a comment or as a new issue.

  • details of linked issues can be viewed from a collapsible JIRA pane on the right of each ticket.

  • details of linked tickets are shown in JIRA.

  • with some extra setup in JIRA, Triggers can run based on changes in linked JIRA issue properties.

    ../_images/jira-trigger-event.png

  • you can add comments to JIRA issues using actions from Deskpro triggers.

Note

You should be logged in to a JIRA account with global Administrator permissions to set up the app.

To avoid infinite loops, Deskpro will not respond to changes you make in JIRA using that account. You should therefore use an account that is not actually used by a person for everyday work.

Issues and comments sent from Deskpro to JIRA will be created using the JIRA Administrator account. However, each comment will be prefixed with the name of the Deskpro agent who made it.

Installing the JIRA app

  1. Go to Apps within the Deskpro admin interface, and select the JIRA app.

  2. Enter the full Base URL of your JIRA installation e.g. https://example.atlassian.net.

  3. Enter an Application Link consumer key. This can be anything - it acts as the “password” to authorize the link between your helpdesk and JIRA, so make it hard to guess.

  4. You can either use the default Application Link Private/Public Key settings, or generate your own key pair for extra security (see at the end of this section).

    • If you wish to use the default keys, do not edit the Private Key.
    • If you wish to use your own key pair, replace the default Private Key with your own, and use the associated public key in step 9 below, not the value shown in the JIRA app.
  5. Go to the JIRA web interface. Using the gear icon at the top right, select Add-ons, then in the far left-hand column select Application Links.

  6. Enter the URL of your helpdesk and click Create new link. You will have to wait for a timeout - you’ll get a warning that there is no response from the URL you entered. Ignore it and click Continue.

  7. In the Link applications pop-up, enter:

    • Application Name: an identifying name e.g. “Deskpro”, “Acme Helpdesk”.
    • Application Type: select Generic Application.
    • Leave the rest of the fields blank.

    Click Continue.

  8. The application link is created. Click Edit then click Incoming Authentication.

    ../_images/jira-editlink.png

  9. Enter:

    • Consumer Key: enter the consumer key you used in step 3.
    • Consumer Name: e.g. “Deskpro”, “Acme Helpdesk”.
    • Public Key: paste in the public key from the JIRA app within Deskpro (or your own public key) - make sure not to include any extra spaces.
    • Leave Consumer Callback URL blank.

    Click Close.

  10. Go back to Deskpro and click Install App, then Continue.

  11. A new Get Access Token button should be displayed in the app settings. Click it.

  12. You will be prompted to allow the app access to your JIRA data. Click Allow.

  13. You will be redirected back to the JIRA app settings. In the Config section, you can select:

  • Default project: the default project when you create a JIRA issue from Deskpro.

    • Default issue type: the default issue type when you create JIRA issue from Deskpro.

    • JIRA fields to be shown within the Deskpro interface - note that even if you select a field, it will not be shown if it is not enabled for the issue type in JIRA.

      • List view fields are shown in a custom JIRA pane that opens when you click or mouse over the JIRA icon.../_images/jira-list.png
      • Create & Detail view fields are shown when you create an issue and when you click the View details link for an individual issue. image7

Note that if you open it by mousing over the icon, the JIRA pane will collapse when you move your mouse away, unless you lock it open by clicking the padlock icon.

The counter on the JIRA icon shows the number of linked JIRA issues.

Warning

To be able to use JIRA triggers, you must do some further configuration within JIRA; see the section below.

Enabling JIRA triggers

To enable JIRA-related triggers in Deskpro, you must do the following within JIRA admin:

  1. Select System in the top-right gear menu, then near the bottom of the left-hand column, select WebHooks.

  2. Click Create a Webhook.

    ../_images/jira-webhook-setup.png

    For the URL, use your helpdesk URL e.g. http://yourcompany.deskpro.com or https://support.example.com, with /jira/webhook at the end.

    Check all the event types under IssueWorklog and Version.

  3. Click Create.

  4. Make sure that the /jira/webhook URL on your helpdesk is accessible to the server where JIRA is running (either your On-Premise or the Atlassian cloud servers). You may need to change your network configuration to allow this.

  5. In the Events area of your triggers, you will now see JIRA options in the By an app section that can make each trigger run when a linked JIRA ticket is updated or deleted.

../_images/jira-trigger-event.png

Warning

You must enable the By an app events for every trigger that you want to respond to changes in a linked JIRA ticket.

Troubleshooting JIRA install

You must make sure that your Deskpro and JIRA servers are accessible to each other for the integration to work.

See Atlassian’s documentation for the IPs used by their Cloud services

Here is a list of relevant articles from our Knowledgebase:

JIRA “400: Bad Request oauth_problem=timestamp_refused” error

Custom public/private key pair

For extra security, you can provide your own public/private key pair.

You should use a 1024-bit RSA key. The JIRA application link will accept either a public key or a certificate in X.509 format.

This command in openssl will generate a suitable self-signed certificate:

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj 'CN=www.example.com' -keyout ~/privatekey.pem -out ~/rsacert.pem

When installing the JIRA app, enter the contents of the privatekey.pem file into the Private Key field, and use the rsacert.pem contents for the Public Key field in the JIRA Application Link settings.

Warning

The certificate generated by the above command will expire after 365 days.

Comments (0)

Add a comment

Add a comment

You need to log in before you can submit a comment.

Need a password reminder?