Tutorial
These tutorials will guide you through the steps needed to access and view the API in TOPdesk and see some examples. It will not tell you anything about the techniques used: HTTP, REST and JSON.
Note: As you are reading this we assume you already have a TOPdesk 7.11.005 or later running. If you are using an older TOPdesk version, please refer to the old tutorial
In the tutorials we refer to a TOPdesk installation that is running on localhost (http://localhost).
General configuration
Configure TOPdesk
Create a permission group that allows the use of the API
In your TOPdesk, navigate to Modules > Supporting Files > Permission Groups and click the "New Permission Group" button on the top right. Give your new permission group a name in the "General" block. In the "Permissions" block underneath, navigate to "API access" and select the read permission API access → REST API and the write permission API access → Use application passwords.
Save the new permission group.
Link the user to the permission groups
Link the newly created permission group to users that should be able to use the API. The permissions/rights for the other modules can come from other permission groups.
Download and set up Postman
Note: This tutorial will use Postman to demonstrate the API. Alternatively, some browsers offer plugins that can be used for sending HTTP requests.
Download and install Postman
Use a search engine to search for "Postman downloads" or browse to Postman downloads.
Download and install the application.
Start and set up Postman
After installation you should have an icon on your desktop or task bar to start the application. Click the icon and the following window should appear:
In order to use Postman you first need to create a workspace. This can be done by going to the "Workspaces" menu tab and selecting "New workspace". The following window should appear:
Enter a name for your workspace (required), and fill in any other field you need, then click the "Create workspace and team" button.
A confirmation screen will appear; click the "Go to Workspace" button to open your new workspace. The following window should appear:
Click "Create a request" in the "Get started" menu on the right-hand side. A new tab should open as follows:
Using the API
Create an application password
To work with the API it expects an application password, not the password used to login to the web interface. So the first step is to set up an application password. This is currently only possible for operators, to use the public API one should refer to the old tutorial
To create an Application password, go to the user settings via the Operator menu in the top right of TOPdesk -> My Settings Choose 'Add' in the Application passwords block.
A "Create a new application password" popup should open. In the popup, fill in the application name or purpose this application keyword will be used for. This name is only used to tell application passwords apart. It is recommended to use different passwords for different applications that will use the API
In addition to a name an expiry date can be set for the password. After this date, the password can no longer be used to access the API and a new one must be generated. The default expiry date is one year into the future.
Press the "Create" button. The application password will be displayed in the "Copy the application password now" popup. This is the only time the password will be displayed, because it will be hashed before it is stored in the database. Copy this password to the password field of the tool that will be used to access the API.
In Postman the username and application password can be added to your HTTP request by navigating to the "Authorization" tab of your open request window. In the 'Type' dropdown, select the "Basic Auth" option. Two fields will appear on the right-hand side, "Username" and "Password". Fill the login name of your TOPdesk user into the "Username" field and the application password you just created for this user in the "Password" field.
Now you are ready to send requests to the TOPdesk API.
Incident Management API examples
List incidents
The following example will list some incidents.
In your Postman request window, change the url to http://localhost/tas/api/incidents and set the method to GET (default value).
Press the button "Send", you will see the incidents from the demo-database below.
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 "Send" 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 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 "Send" 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 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 2211 016
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 "Send" 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 the method from a GET to PUT and we are going to send content.
An HTTP request with the method PUT means that you want to change some data.
Now switch to the tab "Body", click the "raw" radio button, and choose "JSON" instead of "Text" as content type in the dropdown located to the right of the radio buttons.
Then we will add this line in the memo field below, with the information we are going to change:
{"briefDescription": "Coffee machine is not working"}
Next we will click on the button "Send" to send it to the API and it will respond with the changed incident in the response viewer at the bottom of the page.
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 change the method to POST and insert this data in the body field:
{
"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"
}
}
Change the URL to:
http://localhost/tas/api/incidents
Click the "Send" button to send to the API and as the response you will get your newly created incident.
Which methods are available in the Incident Management 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.
Change Management API examples
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).
- Set up an application password for the 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.
- 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.
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.
FIQL queries
Using FIQL queries
FIQL queries are designed to be used in query parameters without having to URL escape them. All fields from the returned resource should be available, unless otherwise specified by the endpoint documentation. The following operations are available:
field==value
: Equals. Not available for memo values.field!=value
: Not equal. Not available for memo values.field==null
: Is null. Special case of Equals, works for all field types.field!=null
: Is not null. Special case of Not equal, works for all field types.field=gt=value
: Greater than. Only available for numeric and date values.field=ge=value
: Greater than or equal. Only available for numeric and date values.field=lt=value
: Less than. Only available for numeric and date values.field=le=value
: Less than or equal. Only available for numeric and date values.field=sw=value
: Starts with. Only available for text and memo values.field=in=(oneValue,otherValue)
: In list. For querying resources that have one of several values, for example all reservations and requests. Not available for memo values.field=out=(oneValue,otherValue)
: Not in list. For querying resources that don't have one of several values, for example all reservations except cancelled and rejected ones. Not available for memo values.oneCondition;otherCondition
: And operation. Conditions can be and-ed together using a;
.oneCondition,otherCondition
: Or operation. Conditions can be or-ed together using a,
.- You can use brackets to group
and/or
sets together. By default,and
takes precedence.
A value
can be specified without quoting or escaping, unless it contains a white space or reserved character.
- String values can be quoted using either
'
or"
. - If you need to use both single and double quotes inside a quoted argument, then you must escape one of them using
\
(backslash). - If you want to use
\
literally, then double it as\\
. Backslash has a special meaning only inside a quoted argument, not in unquoted argument. - The reserved characters are
' " ( ) ; , = ! ~ > >
. - Date values can be specified using ISO 8601 format which is
yyyy-MM-ddTHH:mm:ssZ
. The time zone can be specified asZ
for UTC, or as offset+/-0900
or+/-01:00
.
Not all API endpoints will support FIQL queries immediately. The documentation for endpoints that use FIQL mentions this in the section about the query
parameter
Examples
Querying all rejected and cancelled reservations for room 1.12a
or asset LAP1337
tas/api/reservations?query=status=in=(rejectedRequest,cancelled); (reservedFacilities.location.roomNumber=='1.12a',reservedFacilities.asset.name==LAP1337)
Querying all planned reservations that start and end in May 2019, except for two specific laptops
tas/api/reservations?query=status==planned; plannedStartDate=ge=2019-05-01T00:00:00Z; plannedEndDate=lt=2019-06-01T00:00:00Z; reservedFacilities.asset.name=out=('LAP 0001',"LAP 1337")
Querying all unarchived visitors that are invited by someone in Delft, and have a phone number like +31612345678 or 06-12345678. Note: The =phone=
operator is only available in the visitor API
tas/api/visitors?query=archived==false; visitor.phoneNumber=phone='6-123 456 78'; host.branch.name=='TOPdesk Delft'
Reporting API
Overview
The Reporting API lets you fetch data from your TOPdesk environment and makes it accessible for your business intelligence tool.
To work with Reporting API:
- Set appropriate permissions
- Configure filters
- Create an application password
- Set up access in BI tools
Configure permissions and filters
Permissions
It is recommended to create a separate permission group for the Reporting API.
To create a permission group:
- Navigate to Modules → Supporting files → Permission groups
- Create a new Permission group, e.g. Reporting. Add the following permissions:
- Read permissions on API access → REST API
- Write permissions on API access → Use application passwords
- Read permissions on API access → Advanced Reporting data access
Filters
You can configure branch, operator and category filters for your reporting operator. You can set up your reporting operator to get all data from TOPdesk. If you specify filters for your operator, it will be reflected in the data exposed to the BI tool.
To configure filters:
- Navigate to Supporting files → Filters, for Branch, Operator or Category.
- Check the All filters option to allow the operator to see all data, or set up the appropriate filters.
Application Password
An application password is also needed for this user so authentication with an external tool can be done securely, not affecting the user's own password.
For details see: Using the API / Create an application password
Create reports in BI tool
The Reporting API provides a feed that conforms to the OData standard, so you can use it with any tool that can consume OData. We officially support Microsoft tools, so in the following we will give an example how to get data in Microsoft Power BI. Note you can use very similar steps to access the data using Microsoft Excel.
Set up access
- Open Power BI and choose Get data. A pop-up dialog will open.
- Select OData Feed from the list of options and insert the following URL in the URL field:
{URL_of_your_TOPdesk}/services/reporting/v2/odataAfterwards, press OK to continue.
- In the next dialog select Basic on the left-hand side and enter the username of the reporting operator as well as the application password you have created for Power BI.
- Click Connect.
- In the Navigator dialog that opens, you will be shown an overview of available data. Select the tables you would like to use for creating reports from the list. Note that in Power BI you might have to create some relations between tables manually.
- Click Load.
Configure relations
- Power BI will open in Report view. Navigate to the Data view using the menu on the left-hand side.
- To make changes to the dataset navigate to the Home tab in the menu at the top of your window and click on Transform data.
- In the newly opened Power Query Editor window, click on the Incidents table located under the Queries header, find the Branch column, then click on the icon on the right side. Select the name option from the list that appears. This will replace the branch IDs with branch names in the table.
- By using the Refresh option under the Home tab, you can run the query again to receive up-to-date data.