A Simplesat survey can go out in the emails TOPdesk already sends about incidents and changes. Survey code pasted into a TOPdesk email works without connecting TOPdesk.
Connecting TOPdesk lets you add responses to the incidents they came from, write feedback to callers' person cards, and bring incident, change and caller details into Simplesat. You can also import your TOPdesk persons as Simplesat customers.
What the TOPdesk integrations do
The TOPdesk page in Simplesat groups its integrations under Account-wide integrations, Survey integrations and Ticket integrations. You switch each one on separately with Activate integration.
Integration | Listed under | What it does | Where it shows |
Sync contacts | Account-wide integrations | Adds your TOPdesk persons to Simplesat as customers and updates them once a day | Customers, in Simplesat |
Sync feedback to a person's custom fields | Survey integrations | Writes values from the response to fields on the customer's TOPdesk person card | The person card in TOPdesk |
Pull additional details | Ticket integrations | Adds the incident's or change's details, the caller and the operator to the response | The response, in Simplesat |
Display feedback in an incident comment | Ticket integrations | Adds the response to the incident's request | The incident |
Both ticket integrations run only on surveys connected to TOPdesk. A survey counts as connected when it uses External email embed with the TOPdesk Incidents or TOPdesk Changes option. It also counts when it's an Event-based or Web-embed survey with Connected service set to TOPdesk.
Note: If we've changed one of your TOPdesk integrations for you, it may work differently from what's described here. Contact us to check what yours does.
Before you start
The TOPdesk integrations are available on every Simplesat plan.
In Simplesat, you need the Manage integrations permission to connect TOPdesk and switch integrations on. Owner and Admin have it by default.
You connect with a TOPdesk login name and an application token for it. TOPdesk recommends an API account for integrations, but an operator account works too.
The integrations act as that login, so it needs access to the incidents, changes and persons they read and update.
An API account also needs a permission group with REST API → Read and Use application tokens → Write.
A workspace connects to one TOPdesk environment.
To see what a connected tool can read and write, go to Integration security, permissions and data flow.
Connect TOPdesk
Start in TOPdesk by creating an application token:
Add a new token:
For an API account, open its card (Supporting Files → New → API account), go to Application tokens and click Add. You need the Supporting Files → Login data write permission to create tokens there.
For an operator account, open the user menu at the top right, choose My settings, and click Add under Application tokens.
Give the token a name, such as Simplesat, and an expiration date, then click Create.
Copy the token. TOPdesk shows it only once.
Then, in Simplesat:
On the Integrations page, open TOPdesk.
Click Authenticate.
Fill in the fields:
Field | What to enter | Example |
TOPdesk URL | The address you use for TOPdesk, without |
|
Username | The login name |
|
Application password | The application token |
Click Authenticate.
When the page shows Authenticated with TOPdesk, click Activate integration on each integration you want, then fill in its settings.
Before you rely on an integration, run a real incident through it, as described in Testing an integration end to end.
Send surveys in TOPdesk emails
The survey goes out inside a TOPdesk email, so TOPdesk decides when it's sent. For example, you can add it to the email TOPdesk sends when a call is completed.
Create or open the survey and choose External email embed.
Under Choose where to add your survey, choose TOPdesk Incidents or TOPdesk Changes.
On Publish, click Generate embed code.
Choose HTML and click Copy survey.
In TOPdesk, go to Modules → Action Management → Action explorer and open the email template that should carry the survey, for example First line call → Call completed + feedback.
Click Edit message, switch to Source, and paste the HTML where you want the survey to appear.
Switch back from Source, click Apply, then click Save.
To test it, create a call with yourself as the caller, set it to completed, and click a rating in the email.
When TOPdesk sends the email, it fills in the placeholders in the survey code. That ties each response to the right incident or change, caller and operator. The ticket integrations use the ticket ID that [-UNID-] fills in to find the incident or change.
Placeholders only work in the language your TOPdesk is set to. A placeholder in the other language comes through as [UNRESOLVED_FIELDPATH].
Heads up: The code for TOPdesk Incidents comes with English placeholders, and the code for TOPdesk Changes comes with Dutch ones. If your TOPdesk is set to the other language, replace them with the matching placeholders from the tables below.
In incident emails:
What the code carries | English | Dutch |
Ticket ID |
|
|
Ticket subject |
|
|
Incident number, saved as the ticket field |
|
|
Customer email |
|
|
Customer first name |
|
|
Customer last name |
|
|
Company name |
|
|
Team member first name |
|
|
Team member last name |
|
|
In change emails:
What the code carries | English | Dutch |
Ticket ID |
|
|
Ticket subject |
|
|
Change number, saved as the ticket field |
|
|
Customer email |
|
|
Customer first name |
|
|
Customer last name |
|
|
Company name |
|
|
Team member first name |
|
|
Team member last name |
|
|
There's more on placeholders in Placeholders and merge fields. To compare the ways Simplesat can send surveys, see Choosing a survey delivery method.
Feedback in TOPdesk
Simplesat waits at least five minutes after a response arrives before it writes anything to TOPdesk. Writing feedback back, and mapping the fields has the full timing and the Field mapping settings.
Display feedback in an incident comment
The response is added to the incident's request, not as an action. It includes every question and answer, with ratings shown as emoji. Only incidents get it, not changes. If the response changes later, for example when the customer answers another question, it's added again, so the request can show it more than once.
Sync feedback to a person's custom fields
Simplesat looks for the TOPdesk person with the same email as the response's customer. Unlike the ticket integrations, this one runs on responses from every survey, not only surveys connected to TOPdesk. Responses with no customer email, or with an email no TOPdesk person has, are skipped.
To set it up:
In TOPdesk, add fields to the person card to hold the values, for example the rating, the sentiment and the comment.
In Simplesat, click Activate integration on Sync feedback to a person's custom fields.
In its Field mapping, choose the TOPdesk field for each Simplesat value, then click Save.
Incident, change and person details in Simplesat
Pull additional details replaces the details from the placeholders with details from the incident or change itself. To learn how Simplesat links feedback to tickets, customers and team members, read Attribution: linking feedback to tickets, customers and agents.
Pull additional details
The details come in as soon as a response arrives, and they're refreshed whenever the response changes. To tell incidents from changes, the integration reads the response's number ticket field. A number starting with I is an incident, and a number starting with C is a change. Not every TOPdesk uses those letters. Some use others, such as a Dutch-language TOPdesk that numbers changes with W. If the number is missing or starts with anything else, the response stays as it is.
For an incident, it adds:
the brief description, as the ticket subject
the number, impact, category, subcategory, urgency, call type, priority and duration, as ticket fields
the caller, as the customer, with their name, email, TOPdesk ID and branch as the company, and their location as a customer attribute
the operator, as the team member with the role Operator, including their name and TOPdesk ID
For a change, it adds:
the brief description, as the ticket subject
the number, impact, category, subcategory, type and priority, as ticket fields
the requester, as the customer, with their name, email, TOPdesk ID and branch as the company, and their location as a customer attribute
the coordinator, as the team member, including their name and TOPdesk ID
Sync contacts
The daily update runs at the time of day you switched the integration on. The first run imports every person, and each run after that picks up the persons who changed in the past day. Sync contacts only reads from TOPdesk.
Persons with an email come in with their name, email and TOPdesk ID, and their branch becomes the company. For how contact syncs work in general, see Contact sync from a connected tool.
Replace an expired application token
TOPdesk application tokens stop working on their expiration date. After that, TOPdesk refuses every request with a 401 error, even though the TOPdesk page in Simplesat still shows Authenticated with TOPdesk.
In TOPdesk, create a new application token for the same login, as described in Connect TOPdesk.
On the TOPdesk page in Simplesat, note which integrations are on.
Click Revoke access. Then click Authenticate, enter the URL, the login name and the new token, and click Authenticate again.
Click Activate integration on each integration you noted. Reconnecting doesn't switch any of them back on, but their settings are kept.
Heads up: Responses that arrive between Revoke access and turning the integrations back on aren't written to TOPdesk, so do steps 3 and 4 one right after the other.
Survey code in your TOPdesk emails keeps working the whole time.
To connect with a different login or to a different TOPdesk environment, follow the same steps with the new details.
Troubleshooting
My responses show [UNRESOLVED_FIELDPATH]
TOPdesk didn't recognize a placeholder in the survey code. Usually the placeholder is in a different language from your TOPdesk. Replace the placeholders with the ones for your TOPdesk's language from the tables in Send surveys in TOPdesk emails.
My TOPdesk integrations fail with a 401 error
TOPdesk refused the application token. Usually the token reached its expiration date or was removed. Create a new token and reconnect, as described in Replace an expired application token.
Pull additional details doesn't add anything to my responses
It runs only on surveys connected to TOPdesk, and it needs the incident or change number in the response's number ticket field, starting with I or C. If your TOPdesk's incident or change numbers start with another letter, it adds nothing to those responses. Check that the survey code carries [Call_Number] or [Change_Number], or [Meldingnummer] or [Wijzigingsnummer] in a Dutch TOPdesk, and that TOPdesk filled it in. It also needs the ticket ID from [-UNID-].
Feedback doesn't show up on my TOPdesk incidents
Check these:
Display feedback in an incident comment runs only on surveys connected to TOPdesk, and only for incidents, not changes.
It finds the incident from the ticket ID that
[-UNID-]fills in.It writes at least five minutes after the response arrives.
The integration needs to show as active. After Revoke access and Authenticate, you have to click Activate integration again.
If none of these explains it, send us the response's link.
My TOPdesk person fields don't update
Simplesat finds the person from the response's customer email. The response needs a customer email, and a TOPdesk person needs to have the same email. Check the Field mapping too.
FAQ
Can I connect two TOPdesk environments to one workspace?
Currently, a workspace connects to one TOPdesk environment. To survey a second environment, use a second workspace.
Do I need to connect TOPdesk to send surveys?
No. Survey code in a TOPdesk email works without connecting. Connect TOPdesk if you want feedback in TOPdesk, incident and change details in Simplesat, and your persons synced as customers.
Where do I find the feedback on a TOPdesk incident?
In the incident's request. Display feedback in an incident comment adds it there.