Opsview Knowledge Center

Service Desk Connector

Learn how to install Opsview Monitor Service Desk Connector module

In this section, we offer step-by-step instructions providing you with specific guidance to successfully install the Opsview Monitor Service Desk Connector software module, which is designed to work with a range of help desk, service desk and support ticketing systems, such as ServiceCloud, ServiceNow, Jira and OTRS. It’s important that you have reviewed section Prerequisites to ensure that any software and hardware dependencies, along with any limitations are fully understood prior to installation.

Package Installation

The Service Desk Connector module requires no repository changes since the software resides in the same repository as Opsview Monitor. Furthermore, you will need a valid Opsview Monitor subscription that includes the Service Desk Connector feature before access is provided to the packages. If you have no valid subscription, then you will receive an ‘Access Denied’ error when attempting to install the module.

Automated Installation

You can choose to install Opsview Monitor modules individually or together by using the 'm flag in the command line, as shown in the example below. You will be prompted to install each module individually, if you have a subscription for them.

curl -l http://install.opsview.com | sudo bash -s -- -m

Debian/Ubuntu

In the example below, we show you the commands used to install the Service Desk Connector module for both a Debian and Ubuntu distribution. You need to run these commands as root:

apt-get update
apt-get install opsview-servicedesk-connector

RHEL/CentOS

In the example below, we show you the command used to install the Service Desk Connector module for both a RedHat and CentOS distribution. You need to run these commands as root:

yum makecache
yum install opsview-servicedesk-connector

Pre-usage Configuration

In this section, we describe the steps needed to set up and configure your Opsview Service Desk Connector module ' you must run any commands as the nagios user, as shown in the example below:

su - nagios

Manually Setting up the Database

By default, the database will randomly generate an encrypted password and will retain the credentials in the /etc/opt/opsview/notifications/notifications.yml file (the 'changeme' password will be ignored if encrypted_password exists).

  • If you wish to re-create the database*, then follow these remaining steps.

To create the database on a remote server, run the command as shown in the example below. Ensure you provide your MySQL root user and password:

/opt/opsview/notifications/bin/db_notifications db_install --force --user=<MySQL_ROOT_USER> --password=<MySQL_ROOT_PASSWORD> --host=<MySQL_REMOTE_HOST> --port=<MySQL_PORT> # port defaults to 3306

Now, restart the daemon:

/etc/init.d/opsview-notifyd restart

Changing the Database Password

You will need to set the variables appropriately, such as password, location of service desk, API tokens and so on, in /etc/opt/opsview/notifications/notifications.yml and make your password 'random'. So, change the database password in mysql, as shown below:

mysql -u root -p notifications
mysql> GRANT USAGE ON *.* to notifications@'%' IDENTIFIED BY <PASSWORD>;

You should now test your changes, as shown below, and then restart opsview-notifyd. Finally, check the /var/opt/opsview/notifications/log/opsview-notifications.log file for any connection errors.

mysql -u notifications -p<PASSWORD> notifications

Service Desks

Located in /etc/opt/opsview/notifications/config.d there are a number of example configuration files for some types of Service Desk software. You should copy the appropriate file, removing the .example suffix and amend the file with appropriate configuration information.

Note: You will need to restart the notifications daemon when you have added or changed any configuration files:

/etc/init.d/opsview-notifyd restart

JIRA

In this section we describe the configuration for JIRA. This file is located within /etc/opt/opsview/notifications/config.d, and tells Opsview Monitor how to raise tickets automatically within JIRA.

jira:
    connection:
        url: https://jira.example.com
        user: jira-admin-user
        password: password
        use_rest_api: 0
        disable_ssl_verify_hostname: 0
    issue_defaults:
        project: TEST
        type: Task
        assignee: a_user_name

If you have encrypted your JIRA password with bin/opsview_crypt, then replace the encrypted_password with the encrypted string, as shown in the example below:

jira:
    connection:
        url: https://jira.example.com
        user: jira-admin
        encrypted_password: 0d71f9bf2ed7b18ac433452297fed2b6f5c7db26d395f21d390d682e3c4be945
        use_rest_api: 0
        disable_ssl_verify_hostname: 0
    issue_defaults:
        project: TEST
        type: Task
        assignee: a_user_name

The project, type and assignee can also be changed with the assignee defaulting to the connection user. Default settings and parameters are created, but you can include additional parameters, if needed. To make use of a 'multi-value' selection in the same way as the user interface, the .yaml file should be updated accordingly. For example, to set a component using the full name or, alternatively, the component Identifier (ID) number, use the following configuration, as shown in the example below:

issue_defaults:
    project: TEST
    type: Task
    assignee: tvoon
    components:
        - name: Component 1
        - name: Component 3

When the JIRA record is added, an acknowledgement will be sent to the Host or Service Check with the ID of the JIRA record. However, if you use custom fields, then these can be included within new tickets by amending the .yaml file, as shown below:

issue_defaults:
    project: TEST
    type: Task
    custom_fields:
         customfield_10020: DEFAULT VALUE

where:

<customfield_10020> is the JIRA internal field ID (unique to your system).

The customfield_10020 is not the text string identifier, although this can be obtained from the notifications log file or by examining the URLs within the 'View Field Configuration' page in JIRA.

Once you have completed updating the configuration file, you will need to restart the notifications daemon, as shown in the example below, and check the log file for any errors.

/etc/init.d/opsview-notifyd restart

REST API

Both SOAP and XML-RPC were removed from JIRA Cloud (July 2015) and in JIRA 7.0 Server. If you can only use the REST API, amend your configuration file to include the following as per the above examples:

use_rest_api: 1

Notification Types

Only PROBLEMS are actioned by the Jira Service Desk Connector. Any ACKNOWLEDGEMENTS or FLAPPING notifications will be ignored.

For services, the following need to be true:

  • The state must be WARNING, CRITICAL or UNKNOWN
  • This must be either the first notification (NOTIFICATIONNUMBER is 1) or the last hard state change was to CRITICAL

For hosts, the following must be true:

  • The state must be DOWN
  • This must be the first notification (NOTIFICATIONNUMBER is 1)

OTRS

Pre-requisite Changes to OTRS

The OTRS API requires configuration to allow the creation and updating of tickets. This requires at least OTRS 3.1.

Service Desk Configuration

otrs:
  connection:
    server: otrs.example.com
    user: otrs-agent
    password: password
    enable_ssl: 0
    AcknowledgeOnError500: 0
  issue_defaults:
    customer: otrs-customer
    queue: ticket-queue
    state: new

If you encrypt your password using bin/opsview_crypt replace the password string with encrypted_password string so the above becomes as below:

The customer and queue entries must be changed to match your OTRS environment. These reflect the default ticket parameters when creating the OTRS notification. Once the configuration file has been edited to your requirements please restart the notifications daemon:

/etc/init.d/opsview-notifyd restart

When the OTRS record is added an acknowledgement will created for the Host or Service Check with the ID of the OTRS ticket created. If 'AcknowledgeOnError500' is set to 1, an acknowledgement will be created for the Host or Service Check, even if the server returns an HTTP 500 error - this was seen on OTRS 3.1 and OTRS 3.2 when OTRS was set with mod_perl enabled.

Notification Types

Only PROBLEMS are actioned by the OTRS Service Desk Connector. Any ACKNOWLEDGEMENTS or FLAPPING notifications will be ignored.

For services, the following need to be true:

  • The state must be WARNING, CRITICAL or UNKNOWN
  • This must be either the first notification (NOTIFICATIONNUMBER is 1) or the last state change was to CRITICAL

For hosts, the following must be true:

  • The state must be DOWN
  • This must be the first notification (NOTIFICATIONNUMBER is 1)

Troubleshooting

Check the log files for errors returned by OTRS.

If you receive:

    ErrorCode    => "TicketCreate.AuthFail",
    ErrorMessage => "TicketCreate: User could not be authenticated!",
  },

This means that the credentials specified in the otrs.yml file are incorrect. Check the credentials in the web UI for OTRS.
If you receive:

  Error => {
    ErrorCode    => "TicketCreate.InvalidParameter",
    ErrorMessage => "TicketCreate: Ticket->CustomerUser parameter is invalid!",
  },

This means the customer name is not found in OTRS. Either change the otrs.yml file or add the user to OTRS.

If you receive:

  Error => {
    ErrorCode    => "TicketCreate.InvalidParameter",
    ErrorMessage => "TicketCreate: Ticket->QueueID or Ticket->Queue parameter is invalid!",
  },

This means the queue does not exist in OTRS. Either change the otrs.yml file or add the queue to OTRS.

Salesforce Service Cloud

In this section, we describe the configuration for the Service Cloud. This file is located within /etc/opt/opsview/notifications/config.d, and tells Opsview Monitor how to raise tickets automatically within Service Cloud.

Configuation file within /etc/opt/opsview/notifications/config.d

servicecloud:
  connection:
    server: test.salesforce.com
    user: salesforce-user
    password: password
    token: salesforce-user-token
    clientid: salesforce-clientid
    clientsecret: salesforce-clientsecret
  issue_defaults:
    Status: New
    Origin: Opsview
    #OwnerId: case-owner
    #ContactId: case-contact
  priorities:
    default: P3 - Minor Issues
    serviceunknown: P2 - Limited Capabilities
    #servicewarning: P2 - Limited Capabilities
    #servicecritical: P1 - Severely Impacted
    #hostunreachable: P2 - Limited Capabilities
    #hostdown: P1 - Severely Impacted

If you have encrypted your Service Cloud password and clientsecret with bin/opsview_crypt, then replace encrypted_password and encrypted_clientsecret with their respective encrypted strings, as shown in the below example:.

servicecloud:
  connection:
    server: test.salesforce.com
    user: salesforce-user
    encrypted_password: 0d71f9bf2ed7b18ac433452297fed2b6f5c7db26d395f21d390d682e3c4be945
    token: salesforce-user-token
    clientid: salesforce-clientid
    encrypted_clientsecret: 7cb204f05fff247dd98befee1cb4dbef80efafac05f78d1cff5d5aea9e22bea1c5879927ed8fb309c32fcab8313e443f
  issue_defaults:
    Status: New
    Origin: Opsview
    #OwnerId: case-owner
    #ContactId: case-contact
  priorities:
    default: P3 - Minor Issues
    serviceunknown: P2 - Limited Capabilities
    #servicewarning: P2 - Limited Capabilities
    #servicecritical: P1 - Severely Impacted
    #hostunreachable: P2 - Limited Capabilities
    #hostdown: P1 - Severely Impacted

Looking back at the above example, the issue_defaults section reflects the default ticket parameters when the Service Cloud notification was created. You can, of course, comment out or remove these parameters, so long as the connected Service Cloud instance does not require them. The OwnerID and ContactID can be changed, otherwise these parameters will default to the connection user; these must be specified as their Service Cloud ID.

The priorities section can also be modified for each type of notification event. Again, parameters here can be commented out or removed, so long as the default priority is defined. When adding the Service Cloud case, an acknowledgement will be sent to the host or service with the ID of the service cloud case that was created. Once you have completed updating the configuration file, you will need to restart the notifications daemon, as shown below:

/etc/init.d/opsview-notifyd restart

Notification Types

Only PROBLEMS are actioned by the Service Cloud Service Desk Connector. Any ACKNOWLEDGEMENTS or FLAPPING notifications will be ignored.

For services, the following need to be true:

  • The state must be WARNING, CRITICAL or UNKNOWN
  • This must be either the first notification (NOTIFICATIONNUMBER is 1) or the last state change was to CRITICAL

For hosts, the following must be true:

  • The state must be DOWN
  • This must be the first notification (NOTIFICATIONNUMBER is 1)

RequestTracker

In this section, we describe the configuration for Request Tracker (RT). This file is located within /etc/opt/opsview/notifications/config.d, and tells Opsview Monitor how to raise tickets automatically within RT.

rt:
  connection:
    url:  http://rt.example.com/rt
    timeout: 30
    user: root
    password: password
  ticket_defaults:
    queue: General

If you have encrypted your RT password with bin/opsview_crypt, then replace encrypted_password with the encrypted string, as shown in the example below:

rt:
  connection:
    url:http://rt.example.com/rt
    timeout: 30
    user: root
    encrypted_password: 0d71f9bf2ed7b18ac433452297fed2b6f5c7db26d395f21d390d682e3c4be945
  ticket_defaults:
    queue: General

The queue can be changed where the default settings have been set when the RT notification was created, although you can include additional parameters. When an RT record is added, an acknowledgement will be sent to the Host or Service with the ID of the RT ticket that was created. Once you have completed updating the configuration file, you will need to restart the notifications daemon, as shown in the example below:

/etc/init.d/opsview-notifyd restart

Notification Types

Only PROBLEMS are actioned by the RT Service Desk Connector. Any ACKNOWLEDGEMENTS or FLAPPING notifications will be ignored.

For services, the following need to be true:

  • The state must be WARNING, CRITICAL or UNKNOWN
  • This must be either the first notification (NOTIFICATIONNUMBER is 1) or the last state change was to CRITICAL

For hosts, the following must be true:

  • The state must be DOWN
  • This must be the first notification (NOTIFICATIONNUMBER is 1)

ServiceNow

In this section, we describe the configuration for Service Now. This file is located within /etc/opt/opsview/notifications/config.d, and tells Opsview Monitor how to raise tickets automatically within JIRA.

Configuration file within /etc/opt/opsview/notifications/config.d.

servicenow:
  username: itil
  password: itil
  instance: https://demo.service-now.com/demo

If you have encrypted your Service Now password with bin/opsview_crypt, then replace encrypted_password with the encrypted string, as shown in the example below:

servicenow:
  username: itil
  encrypted_password: 0d71f9bf2ed7b18ac433452297fed2b6f5c7db26d395f21d390d682e3c4be945
  instance: https://demo.service-now.com/demo

Once you have completed updating the configuration file, you will need to restart the notifications daemon, as shown in the below example:

/etc/init.d/opsview-notifyd restart

You can now send a test notification.

Notifications will be sent to the Service Now's External Communication Channel (ECC) queue, which you can view by simply logging in to Service Now using the ECC application as an administrator. You will, of course, need to undertake customization of Service Now to map fields used to create an incident; see Service Now Product Documentation for more information.

The initial configuration or customization process is somewhat different to a 'normal' operation. Initially, a request is submitted via the Simple Object Access Protocol (SOAP) to the Service Now's ECC queue and a failure is returned as there are no business rules to evaluate the request. With the request submitted, the business rules can be created.

For 'normal' operation, a request is submitted via a SOAP request to the Service Now's ECC queue and business rules evaluate it. A ticket is raised and the details are returned to Opsview Monitor for raising an acknowledgement. If an incident record is not created then an error is reported by Service Now. For example, no authority to create a ticket or an internal error will return a failure core to the Opsview Monitor server.

Notification Types

Only PROBLEMS are actioned by the Service Now Service Desk Connector. Any ACKNOWLEDGEMENTS or FLAPPING notifications will be ignored.

For services, the following need to be true:

  • The state must be WARNING, CRITICAL or UNKNOWN
  • This must be either the first notification (NOTIFICATIONNUMBER is 1) or the last state change was to CRITICAL

For hosts, the following must be true:

  • The state must be DOWN
  • This must be the first notification (NOTIFICATIONNUMBER is 1)

Configuring Opsview Monitor

You can configure the service desk notification by including a new notification method, as we describe in the following steps.

Create a new notification method (change the name and command, accordingly):

Name: jira
Run On: Master (This option is not visible in a single server system)
Command: notify_via_nagios opsview_notifications jira

Your configuration should look similar to the screenshot below:

Now create a link as shown below:

su - nagios ln -s /opt/opsview/notifications/bin/opsview_notifications /usr/local/nagios/libexec/notifications/opsview_notifications

Using a specific User, create or update a notification profile to use this new method:

Now reload Opsview Monitor to make this notification method active.

Finally, you should test both the Host and Service Checks raise tickets correctly.

You should be aware that if multiple Users use this Notification for the same Host or Service Check, then you will receive multiple notifications by the service desk system. We recommend that you use a single User where a notification will not be sent more than once for the same Host or Service.

Auditing

The Service Desk Connector will store historical notifications in the spool_history table. The default retention period is 365 days and to change the number of days, you need to edit the configuration file at /etc/opt/opsview/notifications/notifications.yml, as shown below:

audit:
  retention: 365

Testing

In this section, we describe how we emulate a Nagios(R) Core host notification for checking Service Desk tickets.

Details for the Notification test are read from shell environment variables. By changing the variables set you can change how you run the test.

For example, to test a Host notification via JIRA, use the following:

/usr/local/nagios/utils/test_notifications hostproblem /opt/opsview/notifications/bin/opsview_notifications jira

Alternatively, you can use the following to have more control over the test:

su - nagios 
NAGIOS_LASTHOSTCHECK=1234567891 \
NAGIOS_LASTHOSTUP=1234567890  \
NAGIOS_HOSTOUTPUT="Test failure" \
NAGIOS_HOSTADDRESS=10.11.12.13  \
NAGIOS_LONGDATETIME="Dec 1 2009" \
NAGIOS_HOSTALIAS="temp host 1"  \
NAGIOS_LASTHOSTDOWN=0 \
NAGIOS_LASTHOSTSTATECHANGE=0  \
NAGIOS_NOTIFICATIONTYPE=PROBLEM \
NAGIOS_HOSTSTATE=DOWN  \
NAGIOS_HOSTNAME=host1  \
NAGIOS_NOTIFICATIONNUMBER=1  \
/opt/opsview/notifications/bin/opsview_notifications jira

When viewing the /var/opt/opsview/notifications/log/opsview-notifications.log file, you should see the output similar to the example below and a ticket should be raised in your Service Desk system:

[2015/09/05 15:36:42] [opsview_notifyd] [INFO] Processing message id 1
[2015/09/05 15:36:43] [opsview_notifyd] [INFO] Processed message id 1

Service Desk Connector

Learn how to install Opsview Monitor Service Desk Connector module