Configure TOPdesk Api plugin

Default Setting

  1. In your browser go the UCC SharePoint site.

  2. Click on ‘Settings’.

  3. Add setting ‘UseCRM’ with value 'True'.

  4. Add setting ‘UseStatistics’ with value 'True'.

Note Please note that it could be necessary to restart the UCC service in order for the UCC service to use the new settings.


PluginAttributes List

The pluginattributes are divided in three categories, , ContactSearch, Contact and Case. There is also a distinction made with fieldtype Search for Contact and ContactSearch which we will discuss below.

What is important is that the property in systemname is identical to how it is named in TOPdesk, including any capital letters. This is because the mapping to TOPdesk requires the values to be identical. Person and Incident have also a couple of inner objects. If you wish to access this data they need to be written with the value of the name in the Person or Incident object and then the property they have in that object.

For instance, Person has a Branch object called branch. If we look in the Branch object it has several properties of its own like extraBranchA and name. If we want to see the name of branch we need to set the systemname to

The displayname contains the name that will be shown in the extension window. For contact this value can be decided by the user, for case this needs to be chosen from the predefined case options. The possible values for case are shown in the case paragraph. For the values shown on the extension window the system name is the property name used in the TOPdesk api. These do not use a field type and the category defines whether it is a contact or case. In the TOPdesk api these are known as Person and Incident.

All possible values for Person, Incident and others can be found on:



To give some examples, the user’s lastname is known as surName in TOPdesk. This means that if we want to see this value in the extension window we need to add an attribute with the systemname surName and category Contact and a displayname of your choice, for example Last name.

Person and Incident can have underlying objects which can also be accessed this way. If we for instance want a value from the branch like it’s name, we can do this by first specifying the object and then the value within it, separated via a dot. This become The same keeps applying if you need to go even deeper, for instance to access the street a person lives you first need to go to privatedetails, then address and finally the street, causing the systemname to become privateDetails.address.street.


Additional Person Objects

There are three added objects to person, contract, privateDetails and locationDetails if you wish to access data that is not part of the main person object. These contain the values of the objects retrieved by the following web calls (see the TOPdesk url for the contained objects in this call):

contract: /persons/id{id}/contract

privateDetails: /persons/id{id}/privatedetails

locationDetails: /locations/id{id}


Category Contact

The contact category shows all values under a contact using values from TOPdesk’s Person object. By default the Name of a contact is set to firstName followed by surname. If you wish to use a different value you can do this by using the DisplayName “Name”. All other values are defined as you see fit.

Fieldtype Search

If you give the configurable attribute a fieldtype, it will be used for the create incident url rather than the contact card. This is because the url can uses values that differ from the api parameters, due to it using the names of the database columns of TOPdesk instead.

You are free to configure the url as you see fit under pluginsettings, the setting is called CreateNewCaseUrl. To show you how it works, an example of this url is


ref_dynanaam is not part of the person object, the value it expects here is the dynamicName found in the person object. So to make this mapping we set:

  • the Displayname to dynamicName,

  • the System name to ref_dynanaam,

  • the Category to Contact and

  • the fieldtype to Search. (when it has a fieldtype this is an indicator for the plugin that you wish to use this value for the createnewcaseurl.)


Category ContactSearch

Like the category Contact, ContactSearch uses the person object from TOPdesk. Contactsearch is used to fill the details below a contact when selecting it. The field next to the contact name (by default called zipcode) can be altered by defining it with the fieldtype Search. In this case it will take the first value it can find that has fieldtype and is of type ContactSearch.


Category Case

There are only four values that will be shown for a case. There are called Subject, Description, CreatedDate and Status. There is also UrlLink that contains the value of the plugin setting CaseUrl. By default all these values are already filled with values from TOPdesk’s Incident object:

  • Subject contains caseNumber,

  • Description contains briefdescription,

  • Status contains status and

  • createdDate contains creationDate.

If you wish to have different values in one or more of these you can do this by giving the Displayname the desired value you wish to change, for instance Subject and setting the system name you desire to be retrieved from TOPdesk. It expects this value to be present in the incident object from TOPdesk.


PluginSettings List

The pluginsettings contain the settings used to connect and retrieve data from TOPdesk.

The topdeskurl contains the url to get to the TOPdesk site and will be added to the beginning of all other url settings.

So to make an example


CaseUrl: /tas/secure/incident?action=show&unid={id}&id={id}

The plugin will then combine the two to form:{id}&id={id}

It is important that you always add the / at the beginning of the other urls and do not end the setting topdeskurl on a / or it will cause issues in the plugin.





Name of the url used to connect to the TOPdesk Api


Username used to connect to the TOPdesk Api. This user usually differs from a regular user logging in into TOPdesk


Encrypted password of the user used to log in on the api. Use this if you want to use a token to login rather than an application password. If application password has a value this value will be ignored


Application password of the user. This can be used in newer versions of TOPdesk to connect to the api. If used the regular password is not required


Url used to go to the create new incident page on TOPdesk via contact name


Url used to go to the case you clicked, click on case subject to open it


Url used to go to the contact you clicked. Click on the contact’s name to open it


Maximum amount of characters to check for the phonenumber, starting from the last character. So if the number is +3112345678 and the setting is 5 it will check 45678


Specifies on which TOPdesk properties to search and how you want the search parameter to be named in the extension window when searching for persons in TOPdesk


Specifies on which TOPdesk properties to search and how you want the search parameter to be named in the extension window when searching for incidents in TOPdesk


If set to true, will execute the call /persons/id{id}/privatedetails to retrieve the private details of a person, found in the TOPdesk portal under private


If set to true, will execute the call /persons/id{id}/contract to retrieve the contract of a person


If set to true, will execute the call /branches/id{id} to retrieve detailed data of the branch. While the branch is retrieved by the standard persons call, most data of the branch will not be retrieved by it, such as the address of the branch. If you wish to use this data this call is required


If set to true, will execute the call /branches/id{id} to retrieve detailed data of the branch of the person’s location. This data will most likely be identical to the person’s branch


If set to true, will execute the call /locations/id{id} to retrieve detailed data of the location. Like with branch not all data of the location is initially retrieved by simply retrieving the person. The location details are stored in a different object because it differs from the regular location object (This will be explained later)


Status colors

You can change the color for a status by creating a pluginsetting called StatusColor followed by the status name without whitespaces. For instance the status “In Progress” would become StatusColorInProgress. The setting requires a hex value. For instance the hex of the color red is #ff0000.

So the setting would become

The check is case sensitive, so be sure the use the exact name used in the TOPdesk portal. This will also work with any custom status names you make in your TOPdesk environment. If no setting is defined it will use the default color used for statuses in the Extension Window.

You can enter the name of the color followed by hex directly in google to find the right hex code, for instance “Crimson Red hex”.


Plugin working

When a call enters the user is verified in the api via the phone number or through email when calling with a sip address. If a contact is found it will use the unique id of that contact in TOPdesk to retrieve the incidents for this contact present in TopDesk.

Any values specified in the pluginattributes will be retrieved if they exist in TOPdesk and have an actual value in TOPdesk. So if the property surName needs to be shown but the contact does not have a last name it will not show up on the extension window.

Via the search option you can look for any contact or cases with the search options specified in pluginsettings. In the event an invalid search parameter is defined TOPdesk usually retrieves the first 10 records it can find, so keep this in mind if the search results do not match or are too many.

If properly configured in the pluginsettings you can also go straight to the contact or case in TOPdesk by clicking on the person’s name and the subject of the case. You can also go to create new incident via the create case button.