an interface to TOPdesk incident management

Open Incidents in Topdesk

Release 1.7.1 latest

  • 22 Jan 2009 Version 1

    • First released version
  • 06 Feb 2009 Version 1a

    • Minor - Helpfunction output updated. -T was not documented corrcetly
  • 25 Feb 2009 Version 1.1

    • New commandline switch -o or --typeofcall With this switch the default behavior of "Type of Call". Default is Incident. Every type available through the type of call pulldown menu from Topdesk is valid here.
    • Timestamp in the Request and Action field. Conversion is based on the Perl sprintf function. See "Make the topdesk time stamp" below and change it to your needs
    • Caller ($TD_USER) handled over the the Request and Action field. So now you will see who has placed the line in your Topdesk
    • Some codeblocks moved for better reading
  • 24 Mar 2009 Version 1.2

    • Minor additions
    • Before trying to open an incident the Topdesk Server is pinged. No answer - no incident
    • If login is disabled the problem will be acknowledged in Nagios but only a warning message is posted as a comment instead of the ticket ID.
  • 02 Apr 2009 Version 1.3

    • set_acknowledge() splitted in set_comment() and set_acknowledge(). So in case of trouble reaching Topdesk only a comment is added to the problem in Nagios instead of acknowledging the problem.
    • New option -k or --caller. The caller can be passed via commandline. Otherwise the default will be used.
    • New options -W, -w and -m. These options must be used together -W Time to retry to open a ticket in minutes if Topdesk is not available. -w Timeinterval for retrying in seconds. If not set default will take place. -m Email address to send a mail if retries fail. Contains all informations from Nagios together with a additional warning.

    For example:

    • W 60 means that the script should retry 1 hour. If $TD_WAIT_RETRY is set to 60 it means retry for one hour every minute.

    This is only if the server is not available (ping). In all other cases only a comment in Nagios is added.

    • New option -e. Type of call entry can be passed via commandline. Otherwise the default will be used.
    • New option -l. 1 for 1st- or 2 for 2nd line call type can be passed via commandline. Otherwise the default (2, 2ndline) will be used.
  • 23 Apr 2009 Version 1.4

    • Portnumber different from default (for example :81) now supported. Minor Codechanges.
    • Variable $TD_PROTOCOL obsolete
    • New Variable $TD_SERVER
  • 28 Apr 2009 Version 1.4 Bugfix

    • Changed %TD_USER to %TD_USER_DEF. Was a typo in the published
  • 25 May 2009 Version 1.5

    • Daylight saving time now supported
    • New variable $TD_TIMESTAMP_OFFSET and hash %TD_TIMESTAMP_OFFSET. The hash contains the offset in seconds between you local timezone and GMT(UTC). This value MUST be negative if you are located westwards the Greenwich meridian.
    • The block with the date calculation has moved downwards, because it has to be behind the declaration of the hash.
  • 09 Nov 2009 Version 1.5 Bugfix

    • Removed the following block because it caused a bug in DST:

    if ($DST == 0) { $TD_TIMESTAMP = $TD_TIMESTAMP - 3600; }

  • 12 Feb 2010 Version 1.5.1

    • Added one line in shit_happens():

    $NAG_CONTACTEMAIL =~ s/ /,/isog;

    So you can have now multiple mailadresses in a contact on Nagios seperated by blanks.

  • 12 Feb 2010 Version 1.5.1

    • Added one line in shit_happens():

    $NAG_CONTACTEMAIL =~ s/ /,/isog;

    So you can have now multiple mailadresses in a contact on Nagios seperated by blanks.

  • 18 Mar 2010 Version 1.5.2

    • Around line 850 changed

    if ( $TD_INCIDENT_ID eq "ERROR") { set_comment(); }


    if ( $TD_INCIDENT_ID eq "ERROR") { set_comment(); shit_happens(); }

    This was necessary due to the fact that otherwise no mail would be send that a ticket could not be opened

    • Changed shit_happens from

      sub shit_happens { open(MAIL, "|$MAILER");


      sub shit_happens { if ($NAG_CONTACTEMAIL) { open(MAIL, "|$MAILER");

      This ensures that shit_happens will only be executed with a mail address handled over

  • 29 May 2010 Version 1.5.3

    • Added modifying operator group ($TD_GROUP)
    • Removed relevat line from create_incident()
    • New subroutine set_operator_incident() based on modify incident;
    • After creation of the incident the incident is reopened for editing like in modify_incident(). The operator group will be replaced. This was necessary due to the fact that a predefined operator(group) can not be replaced while creation.
  • 22 July 2010 Version 1.6

    • General: Due to the fact that Topdesk rom version 4.2 on uses the Mango interface as operator interface it is no longer possible to derive either the incident id or the unid (unified identifier from the code ot the page. On one hand the manual for working with URLs is much more better than the old one - on the other hand they always mention the unid or the incident it, but there is no way to get as a return code or sohandle_TD_incident.1.7.2. Seems like they have forgotten such a thing.

    Topdesk Germany told me to use the self service interface because it is not Mango based. But there were 2 main problems:

    • only a subset of the fiels needed was available using the selfservice interface
    • the selfservice interface used session cookies.

    So a lot of code rewriting had to be done because the code should cover all current versions of Topdesk. And it does.

    the create_incident function was split in 2 parts

    • create_incident using the selfservice interface
    • complete_create_incident using the operator interface


    We have a new option -V to determine wether we have a 4.2 version or below (see below).

    • Changed get_incident_id(). Instead of deriving the incident id (card in Topdesk) from the webpage it is derived from the HTML title tag. On the loginpage it contains only the string TOPdesk. This works well for Topdesk version 4.2 too
    • Changed subroutine get_unid_tmp_file() to get_incident_id_tmp_file()
    • Changed filehandle TMP_UNID to TMP_INCIDENTID
    • Used $TD_INCIDENT_ID instead of $TD_UNID
    • Modified all URL buildings to use lookup=naam&lookupValue=$TD_INCIDENT_ID instaed of unid=$TD_UNID
    • Removed definition of $TD_UNID
    • Removed get_unid()
    • New operator -V - contains the Topdesk version. This is optional. Default is any version below 4.2.
    • New variable $COOKIE_JAR because we need to store oa cookie for 1st line incidents. We have to deal around with LWP::UserAgent instead of only using LWP:Simple.
    • Subroutine set_operator_incident() introduced with 1.5.3 is removed. set_operator_incident() was nesseccary because it is not possible to change the default operator while dreating the incident. So the incident had first to be created and as a second step the operator group had to be changed. From 1.5.4 on creating the incident is done in two steps which made set_operator_incident obsolete.
    • In the past $TD_NOTICE was unused. It is enabled now with -n | --notice=''. It fills out the notes field on the notes card
    • $TD_GROUP was replaced by $TD_OPERATOR, because in fact the field contains the operator which can be also a group From version 4.2 on:
    • If the name entered is an operator group the same entry is displayed in the fields "Operator" and "Operator group".
    • If the name entered is an operator name the corresponding group entry is displayed in the field and "Operator group".
    • Variable $TD_CREATE no longer used
  • 23 Sept 2010 Version 1.6.1

    • Bugfix: Category and subcatecory MUST be assigned during creation of the ticket instead of doing it in the modifying section. Otherwise mails regarding the incomplete incident will be sent to your calldesk and automatic operator group assignment will not work.
  • 23 Nov 2010 Version 1.6.2

    • Bugfix: Message now inserted during creation phase instead of using the operator interface. It could happen, that an incident was created while the operator interface was not available. This caused an empty incident in topdesk.
  • 11 Jan 2011 Version 1.6.3

    • Bugfix/Enhancement: New variable $HTTP_RET_CODE. We need it now in case we have a problem to connect to topdesk while the host reachable but the URL is not working. It was necessary due to the switch form LWP::Simple to LWP::UserAgent caused be Topdesk 4.2 and the use of cookies from the selfservice interface.

    Affected subroutines:

    • set_comment()
    • shit_happens()
    • get_incident_id()
  • 12 Sep 2011 Version 1.6.4

    • Bugfix/Enhancement: Enhanced shit_happens(). Added some more information in the mail (category and subcategory) to make it easier to add the incident by hand.
  • 03 Nov 2011 Version 1.6.5

    • Bugfix/Enhancement: Enhanced ping(). Because icmp needs root priviledge it is now possible to submit an alternative protocol (udp or tcp) via commandline. Default is icmp.

    • Change: Mail format modified (in case Topdesk is not reachable). The informations for adding the incident by after the recovery of Topdesk is better fromatted now.

  • 09 Dec 2011 Version 1.6.6

    • Bugfix: --severity was not working due to a typo. -t was working. Fixed
  • 08 Mar 2012 Version 1.6.7

    • Enhancement: There are 4 boolean fields vrijelogisch1 - vrijelogisch4 in Topdesk which can be used for individual purpose. Setting one of this can be done by using --freelogic=1, --freelogic=2, --freelogic=3 or --freelogic=4. What it does depends on the definiton your Topdesk admin has done.
  • 10 Sep 2012 Version 1.6.8

    • Enhancement:
    • Added a linemapping (--linemap= "s1=l1 s2=l1"). So you can have different lines depending on the severity.
    • Priority for linemapping (--sevmapfirst). This is used in conjunction with severity mapping and line mapping. If (for example) a CRITICAL is mapped to sev2 instead of a sev1 a line mapping like "s1=l1 s2=l1" is nonsense because you will never have a sev1. So under "normal" conditions the the line mapping must be done before the severity is mapped
  • 30 Nov 2012 Version 1.6.9

    • Enhancement:
    • To be able to use "&" in categories and subcategories "&" has to be replace by "%26" which is the ASCII code of "&"
  • 29 Jul 2013 Version 1.7.0

    • Enhancement:
    • User and password for topdesk can now be handed over via parameters -u and -p. This is necessary if you have more than one user opening a ticket in one Topdesk system.
    • The caller is now listed in the email sent if Topdesk is not available.
  • 13 Aug 2013 Version 1.7.1

    • Enhancement:
    • Commandline switch --optmailmsg (variable $OPT_MAIL_MESSAGE). This open the option to handle an optional mail mail message over to shit_happens() in case Topdesk is not reachable.
  • 16 Dec 2014 Version 1.7.2 (not published)

    • Bugfix:
    • Fixed typo in --password
    • Enhancement:
    • Encoding URL reserved characters when part of a string because it can cause problems when used in an URL
  • 27 Feb 2015 Version 1.7.3 (not published)

    • New commandline switches -R or --recover-status="text string". Contains the value to be set from table afhandelingstatus in case of a recovery.
  • 18 Jul 2017 Version 1.7.4 (not published)

    • Workaround - Moved setting of subcategory from create_incident to complete_create_incident. Operator group must be handed over via command line option.


Latest version of the addon
68.98 KiB text/x-perl 2014-09-08 Download


As it says - read it
23.75 KiB text/plain 2014-09-08 Download

Release 2.x.x

  • 21 Mar 2018 Version 2.0.0

    • Complete rework for Topdesk 7.11 API instead of using URLs
    • Removed --version ($TD_version) option
    • New routines for Login/Logout
    • Rewriten create_incident() and modify_incident()
    • Removed complete_create_incident()
    • Removed -n because the notes field doesn't exist anymore
    • Removed configuration object ($TD_object). Not needed
    • Removed soortmeldingid - Incident Type - because we do create only incidents
    • Change variable $TD_input to $TD_entryType for better readability
    • In the past a clear userfriendly entry could be used for the caller. But because the user is normally a registered user in Topdesk the user can't be called by "caller" (and clear name). It can only be called by callerLookup which need the UNID (ID in datababase). The UNID is in API calls named as ID and a long alphanumerical not self explaining string. Because this can't be stored easily in hashes etc. the definition has been outsourced to .ini files.

    The name of the .ini file will be always in the format topdeskhost.domain.ini

    Because some other definitions will also be referenced by UNID these mappings are also defined in the .ini file.

    These definitions are:

    • caller
    • Entry type (Alert, WEB, Phone etc.)
    • Duration (severity)
    • Operator Groups

    To have all user defineable values in one place all definitions stored in hashes in the old program will be stored in the .ini files now.

    • New option --config_dir if the config is stored in a non default location.
    • Rewritten time stamp offset. Now acceptiing negative values for timezones west of Greenwich
    • Removed free logic field support. This is much more complex in new Topdesk versions and can be used for various content. So a general solution is not possible here.
    • Replaced -R or --recover-status="text string" by --processing-status because it is the status field from the Prosessing section.
    • Option -r|--ready was changed to --close. The values for complete or close has to be stored in your config file and it must be allowed by Topdesk administration to do so.
    • Changed $TD_incident_id to $TD_incident_number. It's more correct.
    • Removed "Always complete or close the incident". This part was nonsense ;-)
    • Removed -T|--time for automatically close/complete an incident after a given time. Doesn't fit compliance requirement and doesn't make sense anymore.


latest release using API
61.53 KiB text/x-perl 2018-05-08 Download


Sample config file
2.42 KiB text/plain 2018-05-08 Download


19.90 KiB text/plain 2018-05-08 Download