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)