This document shows an example of what needs to be done in TOPdesk to make it integration-ready with the endpoint in your ONEiO. Note also, that the number of fields used in integrations might vary.
In case you have questions related to setting up the integration, send a mail to email@example.com.
You can sign up for a free trial of ONEiO from the following link: ONEiO Free Trial
ONEiO will communicate with TOPdesk by the means of its REST API. For this reason, we shall need to have an operator user with access to TOPdesk and a compatible permission set allowing us to create and edit things in TOPdesk. Our recommendation is to either create a new permission group or use the "IT-Support" permission group with an additional allow of "Use application passwords" permission:
To work with the API it expects an application password, not the password used to login to the web interface. To create an Application password, being logged as an integration user, go to the user settings via the Operator menu in the top right of TOPdesk -> My Settings Choose 'Add' in the Application passwords block.
A "Create a new application password" popup should open. In the popup, fill in the application name or purpose this application keyword will be used. This name is only used to tell application passwords apart. It is recommended to use different passwords for different applications that will use the API
In addition to a name an expiry date can be set for the password. After this date, the password can no longer be used to access the API and a new one must be generated. The default expiry date is one year into the future.
Once all is done please note and save the values for the TOPdesk login and password of the integration user we have just created in the corresponding fields of the TOPdesk endpoint in the ONEiO application. For more information please follow this endpoint configuration guide.
To send information from TOPdesk to ONEiO we shall need to create at least two events and an action sequence. Let's start with an action sequence in the Modules > Action Management > Action Sequence.
To speed up the process we are attaching a template (ONEiO_action_sequence.json) you can import.
Most of the fields are already populated and we just need to:
- Set it as active
- Check the option "Apply in the Operator Section"
- Modify the variables
- ONEiOURL remains the same unless you are connecting to the ONEiO productive environment. In that case, simply remove the "-test" part from the URI
- username is your username in ONEiO, available from the endpoint configuration
- token is your ONEiO password, generated in the endpoint configuration at ONEiO
Now the action sequence can be saved.
Let's continue with a new event in Modules > Action Management > New Event. As a "Service" let's select any from the appropriate to your integration "Incident Management" option.
- First, let's give the event an appropriate name, set it as active, and choose a type. For the integration to function normally we shall aim to have at least two types per service "New card" and "Edit card".
- Secondly, let's link an action (action sequence ONEiO) we created in the previous step.
- To finish things up we should also add at least one condition to restrict event activity from firing when the changer of a card is the integration user (the one we created earlier).
*NOTE* Feel free to finetune the conditional logic later once the initial communication between tools has been established.
Now the event is ready to be saved, and the same steps can be repeated for the "Edit Card" event type.
Once you are successful in creating an integration user, action sequence and events the configuration in TOPdesk is complete and is ready to be tested.