Prepare TOPdesk KB integration

This article is from before the rebranding to SelfGuide. Text and images can include the old product name ProductivityPerformer or its abbreviation PP.

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.

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. Create permission group
  3. Create operator account
  4. 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

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
  1. Click on Authorization to open the tab
  2. Click Links Wizard to add the pervious created permission group
  3. 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
  1. Select My Settings.
  2. Application password management can be found in the bottom, click Add.
  3. Add a name, choose an end-date and click Create
  4. 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