Installation

This page guides you through the installation of the TOPdesk Jira integration.
The TOPdesk Jira integration works with an app that needs to be installed in Jira. In the app, you can then configure the API details of TOPdesk. This is necessary to have Jira and TOPdesk communicate with each other.

Step 1: Install the app in Jira

A Jira admin can install the app in Jira by following these steps:
  1. 1.
    Login to Jira as an administrator.
  2. 2.
    Select
    > Apps.
  3. 3.
    Search for the TOPdesk Jira integration app and open it.
  4. 4.
    Click on Try it free or Buy now at the top of the page.
Jira will let you know when the app is installed successfully.

Step 2: Create a functional operator in TOPdesk

The Jira app needs access to your TOPdesk instance. We're going to create a functional operator in TOPdesk with sufficient rights to the relevant TOPdesk API's. In step 3, we're going to use this functional operator to give the Jira app access to TOPdesk.

2.1: Create an operator

  1. 1.
    Create a new operator: TOPdesk Menu > New > Supporting Files > Operator.
  2. 2.
    In the surname field, fill out Jira integration.
  3. 3.
    Fill out the mandatory Site field.
  4. 4.
    Select
    under TOPdesk login to add login credentials.
  5. 5.
    Save the new operator.

2.2: Create a permission group

  1. 1.
    Create a new permission group: TOPdesk Menu > New > Supporting files > Permission Group.
  2. 2.
    Give it a clear name, such as Jira integration permissions.
  3. 3.
    Enable the permissions as stated in the 4 tabs below.
  4. 4.
    Save the new permissions group.
Call Management
Change Management
Supporting Files
Reporting API
Permission
Read
Write
Create
First line calls
Second line calls
Standard Solutions
Permission
Read
Write
Create
Request for Simple Change
Request for Extensive Change
Templates
Permission
Read
Persons
Permission
Read
Write
REST API
Use application passwords
The permissions that need to be configured
  1. 1.
    At the top of the permission group, select the Operators tab.
  2. 2.
    Select the blue Links Wizard. (If you can't find this button, make sure to save the permission group first)
  3. 3.
    Find and check the box for the Jira integration operator you created earlier.
  4. 4.
    Select the Link button.

2.4: Create an application password

The TOPdesk Jira Integration requires an application password, not the password used to login to the web interface. To create an application password:
  1. 1.
    Login with the Jira integration operator you created earlier.
  2. 2.
    Select
    and choose My Settings.
  3. 3.
    Go to Application passwords and click on the Add button.
  4. 4.
    For Application name, choose TOPdesk Jira Integration.
  5. 5.
    Choose an expiration date in the future and select Create.
  6. 6.
    Save the application password so you can use it in the next step.

Step 3: Configure the TOPdesk API details in Jira

Once the app is installed in Jira and you created a functional operator in TOPdesk, you can fill out the API details in Jira. You can find the API settings by following these steps:
  1. 1.
    Login to Jira as an administrator.
  2. 2.
    Select
    > Apps.
  3. 3.
    Find TOPdesk integration in the menu on the left and open API settings.
On the API settings page, you are presented with three fields that are used to give the app access to TOPdesk.
Input field
Description
Url
This is the URL that points to your TOPdesk SaaS instance. The URL is typically in the format https://<your-company>.topdesk.net/tas/api.
Username
This is the name of the functional operator that you created in 2.1: Create an operator.
Application password
This is the application password of the functional operator that you created in step 2.4: Create an application password.
When you have correctly filled in the API settings, you will get the following success message:
Success message for API settings
If there is something wrong, you will get the following error message:
If you need any help with the installation, you can reach out to our service desk: https://avisi-support.atlassian.net/servicedesk/customer/portal/55

Installation complete

When the API settings are set correct, you are connected to TOPdesk. You can now start to create issues from Jira or changes/incidents from TOPdesk.