Prepare TOPdesk KB integration

TOPdesk is an IT Service Management application used for incident, change and problem management; room reservations and more. It also contains functionality for a self-serivce portal (SSP) and a knowledge base (KB). Organizations using the SSP are directing users to the SSP for all kind of questions, with answers in the knowledge base. By integrating SelfGuide with the TOPdesk KB, the best of both products can be used. Users have one place to find answers, requests changes, etc. using the TOPdesk SSP and to gain answers using SelfGuide Instructions.

The TOPdesk KB integration is optional and by default disabled. Using the integration requires preparation in TOPdesk, after these preparations, the integration can be enabled by contacting support@selfguide.com.

Summary:

The required preparations results in an TOPdesk operator with permissions to edit the knowledge base using the REST API.

1. Region and Language configuration
2. Enable TOPdesk KB API
3. Create permission group
4. Create operator account
5. Create application password

The details for the above steps can be found below. Based on the TOPdesk design and configuration, steps might differ from the description below. If there are any questions, contact support@selfguide.com.

1. Region and Language configuration

TOPdesk KB items require a minimum of one translation, more are possible. SelfGuide supports using the English and Dutch translation, verify if at least one of both is available. If not, add the languages so KB items can be created.

1. Open TOPdesk, sign-in with an administrative account
2. Click TOPdesk Menu in the left upper corner to expand the menu and choose Settings
3. Open Functional Settings -> Region and Language -> Language
4. Verify if languages with Windows Country Code Dutch and / or English are avialable

2. Enable TOPdesk KB API

The TOPdesk KB API is required but disabled by default due to being a Labs feature. Enable the API, for more information see Knowledgebase-api | TOPdesk API.

Note: the feature is visible in Labs and can be enabled. It seems enabling the feature does not have any effect till requesting access using this form as described in TOPdesk KI 16035

3. Create permission group

Adding, updating and archiving KB items requires permissions in TOPdesk. Based on a 'least privileges' principle, create a new permission group with the leas required permissions:

1. Open TOPdesk using an account with permissions to manage permission groups
2. Click TOPdesk Menu in the left upper corner to expand the menu and choose Modules
3. Click Supporting Files in the navigator
4. Open Permission Groups under Overview
5. Click New Permission Group
6. Add the permissions like shown in the screenshot below
7. Click Save to create the new permission group

4. Create operator account

To be able to authentication and receive permissions, an operator account is needed. Create a new, dedicated, account for SelfGuide using the steps below:

1. Open TOPdesk using an account with permissions to manage permission groups
2. Click TOPdesk Menu in the left upper corner to expand the menu and choose Modules
3. Click Supporting Files in the navigator
4. Open Technician under Overview
5. Click New Technican
6. Add a descriptive name for the operator, for example SelfGuide
7. Enable login permissions
8. Click Save to create the operator

9. Click on Authorization to open the tab
10. Click Links Wizard to add the pervious created permission group
11. Search for the permission group, for example using the name, select the permission group and click Link

5. Create application password

The operator is created and has permissions to edit KB items. Authentication on the API requires the operator to have an application password. Follow the steps below to create a new application password for the created operator account:

1. Sign-in as operator using the new operator account
2. Open the personal menu in the upper right corner

3. Select My Settings.
4. Application password management can be found in the bottom, click Add.
5. Add a name, choose an end-date and click Create
6. A new modal is opened containing the application password. Copy and save this password, this is the only time the password is visible.

Contact support

Contact support (support@selfguide.com) to enable the TOPdesk KB integration, supply the information below:

• TOPdesk url
• Username of the created operator account
• Application password created in the last step

‍