Introduction

This section describes an example of a direct integration between TOPdesk and Workspace 365 which helps both the caller and the operator to stay up to date on the status of their requests.

Here's an example of a TOPdesk notification:

This is a best effort instruction guide to connect the TOPdesk API to the Workspace 365 Activity Feed API. If you experience any problems during configuration, we can help you come up with solutions. However, we do not own TOPdesk software. This means you may need to consult TOPdesk support for further assistance.

TOPdesk notifications

In order to generate notifications from TOPdesk events and show them in Workspace 365, you will need to understand how the workflow in TOPdesk is setup and for which events you want to trigger a notification.

For the purpose of this manual, we will only focus on Call Management events. By means of example, we will discuss four different event/notification types which are simple but effective and most common for most TOPdesk users.

In this explanation we talk about two personas:

Caller (person reporting an incident or registering a request)
Operator (person working for a service oriented department tasked with following up on incidents and requests).

Operator example notifications

Operator John assigned: Operator update by caller:

Caller example notifications

Caller status changed: Caller update available:

Prerequisites

An account with administrative privileges who is allowed to create permission groups, API user, events and actions in TOPdesk.

Step 1. Generate a Workspace 365 API key

First, we need to generate an API key for the Workspace 365 API, to be able to access the Activity feed API from TOPdesk.

As a Workspace administrator, go to “Settings” by clicking on your profile in the top right corner.
Navigate to the “Integrations” section in the left menu.
Select “API settings”.
Click the “+ New” button at the top left.
1. Provide a name which indicates this key is used for TOPdesk notifications.
2. Select “Activity feed API” as the scope.
Click “Save”.
From the pop-up, copy the API key.
- Note: Make sure you store this key somewhere secure. You will only be able to see and copy the API key once.
Click “Close”

Step 2. Create Permission Group for API user in TOPdesk

In TOPdesk, go to the Supporting files settings and open “Permission groups”.
Create a new “Permission Group” called “Workspace365-API”.
Check for the sub-sections in the main sections you want the API to have access to. For this example we need:
- Section “Call Management” – sub-sections “First line calls” and “second line calls”. Permissions “Read” and “Selections”.
- Section “Supporting files – sub-sections “Persons” and “Operators”. Permissions “Read” and “Selections”.
- Section “API access” – sub-sections “REST API”. Permissions “Read”.
- Section “API access” – sub-section “Use application passwords”. Permissions “Write”.

Step 3. Create an API user

Create a new Operator which will act as the API user. This user should have access to the scope you want to expose on the TOPdesk API to be able to send notifications to Workspace 365. Make sure any filters are disabled or at least checked to make sure the user has the right permissions to access information.

Create a new Operator (or, if you already have a TOPdesk integration, use the existing account).
Link the operator to the previously created permission group “Workspace365-API” via the “Authorization” menu.
Logon with the new Operator account and click on the profile icon in the top right corner. Click “My Settings”.
Scroll down to the “Application passwords” section and click “Add” to generate a new password for use with Workspace 365.
Provide a name and set an expiration date.
- Note: please make sure you set a reminder in your calendar to renew the password as the integration will no longer work after expiration.
Click create to generate the password.
From the pop-up, copy the API key.
- Note: Make sure you store this key somewhere secure. You will only be able to see and copy the API key once.
Save your settings if required.

Step 4. Create TOPdesk event

TOPdesk events can be any event associated with any of the available TOPdesk modules like Call Management, Problem Management, Change Management, etc. For the purpose of this manual, we will only focus on Call Management events, but the concepts we explain are applicable to any of the TOPdesk modules.

Keep in mind that:

Each module contains different data fields which can be used to create events and use in actions. In order to make sure you use the correct ones, please consult the TOPdesk (API) documentation.
Events cannot be reused and will have to be selected or recreated for each module and sub-section like second line or other types of calls. You will then have to repeat the steps.

For our use case we have defined four custom example events you can create yourself:

WS365_Status_Notification
WS365Caller_NewInteractionAdded
WS365Operator_Assigned
WS365Operator_UpdateByCaller

General instructions to create an event:

Open the TOPdesk management application.
Navigate to or search for “Event Explorer”.
1. Select a preconfigured event.
2. Or create a custom event if the event you need is not available in the list.
Click the “Create new event” button in the top right corner.
In the pop-up, select “Call Management - First line call”.
Click the “Create new event” button.
Review one the event examples below. Verify you fill out the fields exactly as shown in the screenshots.
Click “Save” in the top right corner.

Event examples:

Step 5. Create TOPdesk action

TOPdesk Actions are a response on the events we have defined in the previous paragraph. Actions are always associated with a TOPdesk event. For the purpose of this manual, we will only focus on Call Management actions, but the concepts we explain are applicable to any of the TOPdesk modules.

Keep in mind that:

Each module contains different data fields which can be used to create events and actions. In order to make sure you use the correct ones, please consult the TOPdesk (API) documentation or TOPdesk support.
Actions cannot be reused and will have to be selected or recreated for each module and sub-section. For actions, there is an additional option to export custom actions and import them again. This allows you to simply import and rename a custom action without having to recreate the whole flow and associated variables again.

Note: we have created ready made action templates based on the examples below, so you can import and use them as you please. They can be downloaded from our download section.

Our action templates assume that users' email address and UPN are identical. If these are different, you need to make an adjustment to the code from the JSON-files. Look for the following code:

${_variables[\"Workspace365UPN\"]}

Replace this with:

${_responses["getPerson"]["body"]["networkLoginName"]}"

It will look like this in TOPdesk:

For our use case we have defined four custom actions which you can create yourself:

WS365Caller_StatusChanged_Notification
WS365Caller_NewInteractionAdded_Notification
WS365Operator_Assigned_Notification
WS365Operator_UpdateByCaller_Notification

Create an action (WS365Caller_StatusChanged_Notification):

Open the TOPdesk management application.
Navigate to or search for “Action Explorer”.
Click the “Create” button in the top right corner.
Select “Action sequence”.
In the pop-up, select “Call Management - First line call”.
Click “Create new action sequence”.
Click “Import” in the top right corner.
Click “Import” again.
Select the Action template (JSON file) you want to use.
Click “Open” (here's an example template).
You can leave the name as is, or change it to something more identifiable to you.
In the “Linked events” section, click the pencil icon.
Select the event you want to trigger with the action sequence. This should be one of the events you created in the previous paragraph.
Fill out the “Value” fields in the “Variables” section at the top of the action sequence.
1. Workspace365URL = Workspace URL including the tenant name without / at the end.
2. Workspace365Token = Workspace365 [API TOKEN from Workspace 365 API settings]
3. Topdesk_url = URL of your TOPdesk tenant without / at the end.
4. Workspace365UPN = ${aanmelderemail}
5. TOPdeskUser = TOPdesk API user you created in the preparations paragraph (step 3).
6. TOPdeskAppPassword = TOPdesk App password you received during the creation of the API user in the preparations paragraph (step 3).
Scroll down to the body of step 2 and make sure the text in the “Title” segment matches your expectations (WS365 import files are in Dutch).
Check all the boxes in the “Available” section.
Click “Save” in the top right corner.

Repeat the above steps for the remaining actions:

WS365Caller_NewInteractionAdded_Notification
WS365Operator_Assigned_Notification
WS365Operator_UpdateByCaller_Notification

Step 6. Create your own notifications

Of course the possibilities are almost endless which means you can create many more notifications on various events available in TOPdesk. To do so, you can use the provided templates as an example and explore the TOPdesk product and API documentation to find the required variables to extract and present the information you want.

You may need help from TOPdesk support or a TOPdesk consultant to help you define the variables you need in order to present the notification correctly in Workspace 365.

Step 7. Testing the notifications

When you create an action, you can also create a trigger to test the action. You can make this trigger available in the context menu of a card item. For example in the “Processing” section under the “Operator” context menu, as shown in the screenshot below. This means you can manually trigger the action directly from the card without making an actual change to the card. This allows you to safely test a notification before putting it into production.

Open the previously configured actions individually.
Click on the pencil icon next to “Available in context menu”.
This will allow you to select in which context menu you want the trigger to appear on the card item.
- For example “Status” or “Operator”. These will allow you to simulate a status change or operator assignment notification without actually changing the value.