Tutorial - Old style

Check authentication settings

Make sure you can login via either TOPdesk or LDAP Authentication. (Operator's Section)
Kerberos or SAML Single Sign-on are not possible.

Create a user that will call the API

For every application/app/purpose it is recommended to create a separate user (operator or person), so that in the future you can distinguish between purposes, apps and when debugging.

Create a permission group that allows the use of the API

Create a separate permission group that only allows the use of the API.

Link the user to the permission groups

Link the newly created permission group and other groups to the API user. The permissions/rights for the other modules can come from other permission groups.

Note: This tutorial will use Firefox to demonstrate the API. If you want to use another browser, please check if there is a convenient plugin available.

For the first steps we are going to call the API from a plugin in Firefox: HttpRequester.

Install FireFox Add-on 'HttpRequester'

Use Google to search for firefox httprequester plugin or browse to https://addons.mozilla.org/en-US/firefox/addon/httprequester/.

Add the plugin to Firefox and restart your browser.

Start HttpRequester

After installation you should have an icon in your status bar to start the plugin

TIP: It's the one with the green/red arrows.

Click the icon and the following window should appear

Note: To work with the API it expects a token and not a login. So the first step is to get this token with the login information. A token can be generated by using one of the following options:

Option 1: Logging in as an operator

Call the url http://localhost/tas/api/login/operator and use BASIC authentication to supply the login details.

Click on the button "Authentication..." so that the row 'Auth' appears.

Enter the url http://localhost/tas/api/login/operator and use the login information of the previously created user. Press the button "GET". In the memo-field on the right a string containing hexadecimal numbers should appear.

Option 2: Logging in as a person

Call the url http://localhost/tas/api/login/person and use BASIC authentication to supply the login details.

Click on the button "Authentication..." so that the row 'Auth' appears.

Enter the url http://localhost/tas/api/login/person and use the login information of the previously created user. Press the button "GET". In the memo-field on the right a string containing hexadecimal numbers should appear.

If you get the error message "User does not have permission to access the REST realm", you forgot to link the API permission group. You will need to restart TOPdesk to refresh the permissions.

The hexadecimal string is the token we will need in the next step, in this example we got "0f83ee44-5ff7-462f-9cf5-855c455a4bca"

The token has a limited validity. After 8 hours or after a restart of TOPdesk it will become invalid and you will need to obtain a new token.

List incidents

The following example will list some incidents.

FIRST clear both the "Auth" fields and click on the "Authentication..." button to hide them.

Change the url to http://localhost/tas/api/incidents

Click on the tab "Headers", we are going to add a header to our request

• Name: Authorization
  
• Value: TOKEN id="0f83ee44-5ff7-462f-9cf5-855c455a4bca"

(Use your own token from the previous step and beware, everything is case-sensitive.)

By using this token, the API knows who your are and what you are allowed to do.

Click the button "Add".

Add another header, to indicate that we want json as a result and not an error message.

• Name: Accept
  
• Value: application/json
  

Click the button "Add" again.

Push the button "GET", you will see the incidents from the demo-database on the right.

TIP: Check the checkbox 'Pretty format' at the top right to organize the mess in the memo field.

If you get an error message like No authentication token provided, you used the wrong token or you forgot to clear the Auth fields.

This method will list the full details of the first ten incidents; newest first. In the next step, we will see how more incidents can be retrieved.

Paging

A maximum number of ten incidents is returned when listing incidents. To retrieve more incidents, you can iteratively step through the complete list by specifying an offset parameter.

To get the next ten incidents, we will add an offset of 10 to the url: http://localhost/tas/api/incidents?start=10

Click the GET button and the list will appear.

If you get the response "204 No Content" instead of the list, it means that there are no more than ten incidents in the total list. The list might be so short because the user does not have the rights to see all incidents.

If you get the response "206 Partial Content" together with the list, it means that there are more than twenty incidents incidents in the total list.

A response of "200 OK" together with the list indicates that there are no more than twenty incidents in the total list.

Filter incidents

It is possible to filter the list of incidents on certain values. For instance we could get a list of second line incidents, that aren't completed.

To filter incidents we use the same url as we previously used to retrieve the list: http://localhost/tas/api/incidents.

We will add both our filters to the url as parameters: http://localhost/tas/api/incidents?status=secondLine&completed=true

Click the GET button and the list will appear.

There are more filters than just the two filters mentioned. Sorting the incident in a different order is also possible. The filtering and sorting of incidents can be combined with paging. Check the documentation for details on how to combine the different options.

Retrieve a single incident

In this step we will retrieve all information for a single incident.

For this we are going to change the url to: http://localhost/tas/api/incidents/number/I 1602 001

By adding /number to the url, you indicate you want to search on an incident number and add the number as well to retrieve it.

If you press the "GET" button again, you will get all information for the incident:

The information for the incident does not include the complete list of actions for the incident. They have to be retrieved using a separate url which is given in the incident information.

Edit an incident

Until now we only retrieved information from the API and we didn't send data to the API. We are now going to send data to TOPdesk. For this we are going to change from a GET to a PUT and we are going to send content.

A HTTP request with the method PUT means that you want to change some data.

Now switch to the tab Content to send.

First we say we are going to send JSON data to the API. We do that by saying that the Content-Type is application/json. This will add an extra HTTP header to our request.

Then we will add this line in the memo field below, with the information we are going to change:
{"briefDescription": "Error 42"}

Next we will click on the button "PUT" to send it to the API and it will respond with the changed incident.

Of course you can check it in TOPdesk as well.

Create an incident

The next step is to create a new incident.

To do this, we will post this data:

{
  "request" : "some request",
  "action" : "some action",
  "caller" : {
    "id" : "e127ddc1-0df3-5ee4-9144-95f751bc13ee"
  },
  "operator" : {
    "id" : "751E0A70-5B2B-572D-8CAE-99F52651B6D0"
  },
  "operatorGroup" :  {
    "id" : "997F35AE-4490-5FDE-BA1C-72044499EA41"
  }
}

to this URL:
http://localhost/tas/api/incidents

Click the POST button to send to the API and as the response you will get your newly created incident.

Which methods are available in the api

The documentation lists all the available methods for the TOPdesk version you are running.

Here you can also find details on parameters and returned values.

Create a change using the API

Use case: I want to connect a third party application to TOPdesk, so that I can trigger changes from it.

Imagine having a third party tool to manage your HR matters. When an HR colleague enters a new employee into the system, a TOPdesk change should be created from that system and the correct template should be used for this specific use case. This can be achieved with the change management API as long as the third party tool can trigger Webhooks.

Change management offers you a variety of ways to create such a connection. Before you start creating a connector App, you need to identify the exact use case. For this example we set the requirements as follows:

• The event that triggers the creation of a change in TOPdesk knows exactly which template it should use (of course the template should exist in TOPdesk).
• The event also knows which optional activities should be used (In case the template offers optional activities).
• To get a token for the API, it's necessary to log in as an operator. This operator should have permissions to create a change and to read a template.

Create a change with a template and optional activities

When the requirements are met you can start using the Change Management API to create changes in TOPdesk. For that we use the endpoint 'Operator Changes' that allows you to send data to TOPdesk. The endpoint sends a POST request to the TOPdesk API at http://localhost/tas/api/operatorChanges. The data needs to be sent in the JSON format.

{
  "requester" : {
    "id" : "32916B7D-3890-45E6-82CA-43E0F3165969"
  },
  "briefDescription" : "New employee development department",
  "template" : {
    "number" : "CHT 0011",
    "optionalActivities" : [
      "OA 0078",
      "OA 0084",
      "32916B7D-3890-45E6-82CA-43E0F3165969",
      "OA 0145"
    ]
  }
}

• The requester-id is the person that will be set as the caller of the change. You can get the correct requester-id using the endpoint 'Get list of persons'.
• The briefDescription overwrites the Brief Description of the template.
• The template-number can be derived from TOPdesk or by using the endpoint. 'applicableChangeTemplates'.
• Specifying a list of optional activities is not mandatory. Only the listed optional activities will be created. If there's no list specified in the request, all optional activities will be created. If an empty list is provided, no optional activities will be created. In the example you can see that you can use either the number of the optional activity or the id. The id of an optional activity can be derived from the TOPdesk-database. Using the id has the advantage that even if the number of the optional activity changes, your connection still works.

Note: All the business logic of TOPdesk will still be executed. Example: The request-phase of a certain template is set to 'auto-approve'. The request phase of a change based on this template will always be auto-approved, it doesn't matter if the change is created via the SSP, by an operator or via the API.

When everything is ok, the API will return the status code 201 and the change will be created.

{
  "id": "5856006a-e851-4af1-9882-e58cc279ae8d",
  "number": "CH 1702 003",
  "requester":{
    "id": "32916B7D-3890-45E6-82CA-43E0F3165969",
    "name": "Palmer, B."
  },
  "briefDescription": "New employee development department",
  "changeType": "extensive"
}

The response can be used by your connector to indicate that the change was created successfully and to communicate the number of the created change in TOPdesk.