handle_TD_incident – TOPdesk Incident Management Integration

General ------- Because there is a real API in Topdesk (according to my informations since version 5.x) over 50 % of the code had to be replaced. This addon was tested with Topdesk 7.11 and 8.01 Changes for version 2 (mainly same as in history.txt) ----------------------------------------------------- - 21 Mar 2018 Version 2.0.0 - Complete rework for Topdesk 7.11 because 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. - Some perl modules not needed anymore: - LWP::Simple - LWP::UserAgent - HTTP::Cookies Installation - Prerequisites -------------------------------------------------- Perl modules needed - - - - - - - - - - Getopt::Long; Time::localtime; Date::Calc qw(:all); Net::Ping; REST::Client; MIME::Base64; Config::IniFiles; E-Mail - - - - Ensure that your system is able to send emails. Otherwise no notification will be sent out in case an incident can't be opened. Installation & Configuration ---------------------------- Copy the perl program to a directory of your choice. I strongly recommend not to merge own or additional plugins with plugins deliverd with your your monitor systems. So default for plugins delivered by Nagios is on many systems /usr/lib64/nagios/plugins. So I would have for example /usr/lib64/nagios/own_plugins -> self developed plugins /usr/lib64/nagios/icingaexchange -> plugins I got via Icinga exchange /usr/lib64/nagios/misc -> misc plugins got frome whereever etc. You can have as many directories as you want. I also recommend not to have macros like $USER1$ to store the directory names for command definitions. Use the full path in command definitions. So you can see where the plugin is located. Opposite to prior versions there is not so much to configure in the program itself. Most of the configuration was moved to configuration files (ini file syntax). What to change in program: - $config_dir_def="/etc/nagios/plugin.conf.d/handle_TD_incident" - can be overwritten with --config_dir - $mailer="/usr/sbin/sendmail -t" - should normally fit. - $nag_pipe="/var/spool/nagios/nagios.cmd" - location of your Nagios command pipe The rest of the configuration is done within the .cfg files. For Topdesk configuration see https://developers.topdesk.com/tutorial.html . The mentioned "application password" (from Topdesk 7.11 on) is currently not supported. It didn't work. So the Login password of the Nagios user is used as in the past. "Configure Chrome" is only needed for testing and not for running the addon. Configuration files =================== The name of the file will be generated automatically from the host name part of your topdesl URL. So for a https://myfault.duck.net/tas/secure the config file will be myfault.duck.net.cfg For the Topdesk API see https://developers.topdesk.com/ . A lot of values can be called by name. But a lot of values is called by reference and you need the (UN)ID of the field. This ID is uniq to each topdesk instance except you have copied a system. How to get the IDs? - Ask your Topdesk administrator (easy) - Get it from the API (more work but works) Sample .cfg file: = = = = = = = = = # The following section will store add the appropriate user, password etc. # for login. [Login] # User you use for login from nagios. Same as in old versions username = Login_toMonitor userpass = blablabla # Default caller will be the caller from the default line. # For accessing the UNID spaces will be mapped to underscores # in the program because strings without spaces are easier to handle. [Caller] default = Nagios_Monitor Nagios_Monitor = F13B7D61-7825-59EA-8F43-319D28E7B548 # For accessing the UNIDs all spaces in durations, OperatorGroups etc. # must be mapped to underscore because strings without spaces # are easier to handle in program code [durations] Severity_1 = A9E02E00-C0C4-5E2E-85A8-9797E6C97AA0 Severity_2 = 13E54C17-3FCF-5142-9412-929A0E4DD0FD Severity_3 = 10BAA84A-DB02-5F4F-BEE2-BBC7A78BBA15 Severity_4 = 776AC094-3E5F-5C14-BC05-BF1F0A1F9C1C [entryType] default = Alert Alert = C8B4C4F0-CD0A-5A08-9E88-340FF3B6904C E-mail = BCA2B312-572A-51FE-B1A7-6E81E1EBC6FF Fast = 771D39B0-933C-5BB3-BB7D-00F43E6E4A2A Letter = 579CBD9F-77ED-5DE3-AF21-E2A10D3903C5 Phone = DD8157E1-955C-54C8-B746-A6FABC8ACBE0 Satellite = 11CBF529-1EC5-5B9B-B926-DFF97E821247 Verbal = 074D8FCF-5CFD-5529-8A86-0D26D84B93CA WEB = 226270A5-4866-535A-883C-9860E52BF296 [OperatorGroups] ICS_ERP = D214FAD0-4058-54DF-B311-A53FFD879C75 Mail-Exchange_PPP = A1F3C91D-62B2-59AD-8D4E-9159893E49B6 Monitoring_Nagios_PPP = 84984738-6345-55B4-AD1E-9DA7E6DBB843 Network_PPP = 59312CE6-7EEB-56C7-ADD7-405559BDCBEE Oracle_PPP = 5982DD8A-B6DC-5106-8F1B-D402F41FB78A SAP_Basis_PPP = 19AB2C69-AD69-5FB0-BEFC-8DB711C873AB Storage_PPP = D1F5C384-B788-5067-9966-F4B9ED3B2FDB Unix_Server_PPP = C65E2AF7-A1F9-5E79-82D8-5C690E7A6FE5 Windows_Server_PPP = F1F0D65C-A49E-5313-8AF8-1161390E47DF [ProcessingStatus] Active = E30D6E4D-736D-587D-8366-0766CDA7E0FF Registered = E560B923-92A4-5232-98A4-5A0C57401714 Rejected = 64614B93-468E-5832-9C7C-38769A938DB8 Request_for_Info = EB8B0243-40A5-56DC-98E1-752AB6360BB6 Solved = 95BDD613-1824-56FA-BF77-BF7990FF095A Wait = B23F56D3-046C-59D7-A912-4051F2169FD3 [Close] # Value for close can be closed or completed. This action # must be allowed by yout Topdesk administration close = completed [Misc] # For adding an acknowledgement we need a contact in Nagios nag_contact = topdesk # Timestamp offset. Server time is normally UTC. Therefore we # have to set an offset to have the right time stamp. So for # examle Berlin is 1 hour timestamp_offset = 3600 Gettin the ID by API = = = = = = = = = = = - Install a REST plugin in your browser (See Configure Chrome https://developers.topdesk.com/tutorial.html#show-collapse-config-chrome) Not necessary to use the mentioned plugin. I used chromium and Rest Web Service Client https://chrome.google.com/webstore/detail/rest-web-service-client/ecjfcmddigpdlehfhdnnnhfgihkmejin Create an incident via WebGui. Call the incident via API - See https://developers.topdesk.com/documentation/index.html -> Get incident by number. - Search in the result for the name from the .cfg file (for example ProcessingStatus Active) - add the value to the .cfg file. - Edit the incident in WebGui and change the value you are looking for (For example Active to (Registered) - Store it and reread in the browser plugin. You got the next ID. - Repeat this until you have all the values you need. But believe me - asking your admin is easier. Configuring your monitor ------------------------ Define a notification command: - - - - - - - - - - - - - - - define command{ command_name TDtest-incident-notify command_line /usr/lib64/nagios/my_plugins/handle_TD_incident.2.0.0 -U https://incidents.foo.net -N $NOTIFICATIONTYPE$ -H $HOSTNAME$ -e Alert -S "$SERVICEDESC$" -b 'Nagios: notification-test / Test System' -C 'ERP-System' -c 'SAP' -O "IT ERP" -s $SERVICESTATE$ -M "$SERVICEOUTPUT$" --processing-status="Solved" -W 30 -m "$CONTACTEMAIL$" } Add a contact in Nagios able to submit something (nag_contact in .cfg file): - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - define contact{ contact_name topdesk alias Topdesk Linux Unix service_notification_period 24x7 host_notification_period 24x7 service_notification_options n host_notification_options n service_notification_commands notify-by-email host_notification_commands host-notify-by-email email foo@foo.net } Add a contact for the every notification command defined 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 TDtest-incident-notify host_notification_commands host-TDtest-incident-notify email dummy (for test) or real address from call desk or so } The email address is needed for real alerts to notify call desk or administrators in case an incident can't be open (Topdesk not reachable or such things) Add the contact to the appopriate contactgroup for notifications: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - define contactgroup{ contactgroup_name TDtest_function_windows alias Topdesk Test Windows members topdesk members topdesk_test } After you have configured the correct commands, contacts and groups you add the groups to the corresponding servie / hosts checks. Usage output: ------------- ./handle_TD_incident.2.0.0 Usage: handle_TD_incident -U|--url [--config_dir= -H|--host -S|--service -N|--notificationtype [-b|--briefdescription ] -M|--message -C|--category -c|--subcategory [-k|--caller ] [-e|--entry ] -s|--state [-l|--line <1=1stline call, 2=2ndline call>] [--linemap=<"s1=l1 s2=l1 s3=l2"> [--sevmapfirst]] [--processing-status] [-O|--operator ] [-t|--severity <"CRITICAL=2 WARNING=3 ...">] [-W|--wait [-w|--retry [-m|--mail ]]] [--optmailmsg=][--close] or Usage: handle_TD_incident -h for help. Help output: ------------ ./handle_TD_incident.2.0.0 -help Copyright (c) 2009,2010,2011,2012,2013,2014,2015,2018 Martin Fuerstenau Usage: handle_TD_incident -U|--url [--config_dir= -H|--host -S|--service -N|--notificationtype [-b|--briefdescription ] -M|--message -C|--category -c|--subcategory [-k|--caller ] [-e|--entry ] -s|--state [-l|--line <1=1stline call, 2=2ndline call>] [--linemap=<"s1=l1 s2=l1 s3=l2"> [--sevmapfirst]] [--processing-status] [-O|--operator ] [-t|--severity <"CRITICAL=2 WARNING=3 ...">] [-W|--wait [-w|--retry [-m|--mail ]]] [--optmailmsg=][--close] or Usage: handle_TD_incident -h for help. -U, --url TOPdesk base URL like https://calldesk.oce.net (mandatory) --config_dir= Configuration file directory. (Optional) Default is: /etc/nagios/plugin.conf.d/handle_TD_incident -u, --user Topdesk user to open a ticket if other than the default user. -p, --password Password for Topdeskif other than the default password. -H, --host Host causing the incident from Nagios (mandatory) -S, --service Service causing the incident from Nagios (mandatory if a service) -N, --notificationtype Notificationtype from from Nagios (mandatory) -b, --briefdescription It fills out the brief description field (optional) -M, --message Message from Nagios (mandatory) -C, --category Main category in TOPdesk (mandatory) -c, --subcategory Subcategory in TOPdesk (mandatory) -k, --caller Pass the caller to TOPdesk If not passed the default caller from the script will be used. (optional) -e, --entry Entry field in TOPdesk (optional) -s, --state=state State from Nagios (mandatory) UP = Host up - used for closing an incident DOWN = Host down Normally mapped to severity 1 UNREACHABLE = Host unreachable Normally mapped to severity 3 OK = Service ok - used for closing an incident WARNING = Service Warning Normally mapped to severity 2 CRITICAL = Service critical Normally mapped to severity 1 UNKNOWN = Service unknown Normally mapped to severity 3 -l, --line 1 indicates a first line incident, 2 indicates a second line incident. If the default will take place. (optional). --linemap="s1=l1 s2=l1 s3=l2" Map severity to line (1st line, 2nd line etc.).(optional) Severity mapping (see below) is interpreted first!! --sevmapfirst Priority for linemapping . 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. (Optional) -O, --operator= Sets the operator group in the operator --processing-status="text string" Contains the processing-status in case of a recovery. See your Topdesk system at "Processing" for possible values. -t, --severity="CRITICAL=2 WARNING=3 ..." Severity for Topdesk (1,2,3 or 4)(optional) With this switch you can overrite the default mapping. The alternative mapping should be entered as a string in the form "CRITICAL=1 WARNING=3...." etc. Lowercase letters will be converted to uppercase ones You have only to add mappings, which should be different from standard mapping Mapping should be handled over as a string so don't omit the quotes -W, --wait=time in minutes Time in minutes for waiting if the Topdesk server is not responding. -m must be set also.(optional) -w, --retry=time in seconds Time in seconds for retry interval. Must be used in conjunction with -W. (optional) -m, --mail='email address' Email address for notification if the Topdesk server is not responding. Must be used with -W and -w (optional) If a ticket is not older than given timeframe it will be closed or completed. The decision to complete or close a ticket is based on the policy used on the given server and therfore it depends on the server name. --optmailmsg='message' This opens the option to handle an optional mail message in case Topdesk is not reachable. This can be text like "Call 911" or something else. --ping='protocol' Protocol to ping the Topdesk server. icmp is default but need root privileges. Allowed protocols are icmp,tcp and udp. --close Always complete or close an incident (optional). The behaviour will be defined in the .cfg file in the [Close] section. -h, --help Short help message (mandatory)

You must be logged in to submit a review.

Your review has been submitted and is pending approval.

Your recommendation has been sent.

Project Overview Project Files Project Photos Project Notes Reviews