History: History and Changes: - 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(); } to 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"); to 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 so. 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 AS A RESULT OF THE THIS THE USER FOR CREATING THE TOPDESK ENTRIES MUST EXIST FOR BOTH INTERFACES WITH THE SAME RIGHTS ETC. 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 (not officially released but stable) - 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 (not officially released but stable) - Bugfix: --severity was not working due to a typo. -t was working. Fixed - 08 Mar 2012 Version 1.6.7 (not officially released but stable) - 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. Usage/How it works: ------------------- Read comments within the code. There is a lot of comments. And these comments won't extend the runtime but extend your understanding :-)). = = = = = = = = = = = = = = = = = = = = = = = = = = = = = Perl modules needed: Getopt::Long; LWP::Simple; LWP::UserAgent; HTTP::Cookies; Time::localtime; Date::Calc qw(:all); Net::Ping; Setup: In this script you only have to setup some variables and hashes to fit your requirements. $TMP_DIR="/tmp"; # Directory to store the UNID and the timestamp temporarily $NAG_PIPE="/var/spool/nagios/nagios.cmd"; # The nagios command pipe $TD_STATUS="2"; # 1 indicates a first line incident, 2 indicates Place your login account(s) here: %TD_USERNAME = ( "tdserver1.mycompany.com" => "Topdesk Account", "tdserver2.mycompany.com" => "Topdesk Account" ); Place your login password(s) here: %TD_PASSWORD = ( "tdserver1.mycompany.com" => "place your password here", "tdserver2.mycompany.com" => "place your password here" ); Place your caller field(s) here: %TD_USER = ( "tdserver1.mycompany.com" => "TD, Monitoring", "tdserver2.mycompany.com" => "TD, Monitoring" ); Place your recovery behaviour here: %TD_RECOVER = ( "tdserver1.mycompany.com" => "CLOSE", "tdserver2.mycompany.com" => "COMPLETE" ); Place here a contact defined in Nagios. This contact is needed for acknowledging. It is the contact which will place the comment with the hyperlink to your Topdesk ticket in Nagios: %NAG_CONTACT = ( "tdserver1.mycompany.com" => "topdesk", "tdserver2.mycompany.com" => "topdesk_test" ); In Nagios you have to - define a notification command # 'notify-by-topdesk-test' command definition define command{ command_name notify-by-topdesk-test command_line handle_TD_incident -U http://tdserver1.mycompany.com -N $NOTIFICATIONTYPE$ -H $HOSTNAME$ -S "$SERVICEDESC$" -C 'Monitoring Tools' -c 'Nagios, Cacti, ...' -s $SERVICESTATE$ -M "$SERVICEOUTPUT$" } - add a contact for the host/service for TOPDesk define contact{ contact_name topdesk_test alias topdesk_test service_notification_period 24x7 host_notification_period 24x7 service_notification_options c,w,u,r host_notification_options d,u,r service_notification_commands notify-by-topdesk-test host_notification_commands host-notify-by-topdesk-test email dummy or address from the caller field } - add the contact to the appopriate contactgroup for notification Synopsis (not complete): handle_TD_incident -U|--url -H|--host -S|--service -N|--notificationtype -n|--notice -b|--briefdescription -M|--message -C|--category -c|--subcategory -k|--caller -e|--entry -s|--state -o|--typeofcall -l|--line <1=1stline call, 2=2ndline call> -V|--tdversion -O|--operator -t|--severity <\"CRITICAL=2 WARNING=3 ...\"> -T|--time