Opsview Knowledge Center

Service Desk Connector - optional module

Learn how to install Opsview Monitor Service Desk Connector module

Overview

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, 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

Run the following command to update your OS packages, setup Opsview Monitor repositories on your server and install opsview-deploy package:

curl -sLo- https://deploy.opsview.com/6 | sudo bash -s -- -A boot

Installing Service Desk Connector

To install Service Desk Connector, you need to edit /opt/opsview/deploy/etc/user_config.yml file and add or uncomment the following opsview_module_servicedesk_connector line:

## Uncomment below to activate these optional modules
opsview_module_servicedesk_connector: True

For a Fresh install, follow the instructions in the Advanced Automated Installation page.

If, however, you are installing Service Desk Connector on an existing system, run the following command as root:

# install and configure the Service Desk Connector
cd /opt/opsview/deploy
./bin/opsview-deploy lib/playbooks/servicedesk-connector-install.yml
./bin/opsview-deploy lib/playbooks/setup-infrastructure.yml
./bin/opsview-deploy lib/playbooks/setup-opsview.yml

Service Desks

Located in /opt/opsview/servicedeskconnector/etc/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 servicedesk connector daemon when you have added or changed any configuration files.

JIRA

In this section we describe the configuration for JIRA. This file is located within /opt/opsview/servicedeskconnector/etc/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
    priority: Critical
    components:
        - name: Component 1
        - name: Component 3

Also note, the priority given must match those that are configured within the JIRA project itself. If JIRA does not recognise the priority name given it will default to Blocker.

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 syslog 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 servicedesk connector daemon and check syslog for any errors.

REST API

Both SOAP and XML-RPC were removed from JIRA Cloud (from 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

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.

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.

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 syslog for errors returned by OTRS.
If you receive:

Error => {
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 /opt/opsview/servicedeskconnector/etc/config.d, and tells Opsview Monitor how to raise tickets automatically within Service Cloud.

Configuration file within /opt/opsview/servicedeskconnector/etc/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.

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 /opt/opsview/servicedeskconnector/etc/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.

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)

Configuring Notification methods in the UI

You can configure the service desk notification by including a new notification method, as we describe in the Notification Methods (Out of the Box) page.

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 /opt/opsview/servicedeskconnector/etc/notifications.yml, as shown below:

audit:
  retention: 365

Testing

In this section, we describe how we emulate a 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 ServiceCloud, use the following:

/opt/opsview/coreutils/utils/test_notifications hostproblem /opt/opsview/monitoringscripts/notifications/opsview_notifications servicecould

When viewing syslog, 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

Upgrading from Previous Versions

If you have upgraded opsview-servicedesk-connector from version 2.3.0 or below, then you will need to migrate the following files:

Old file location New file location
/etc/opt/opsview/notifications/notifications.yml /opt/opsview/servicedeskconnector/etc/notifications.yml
/etc/opt/opsview/notifications/config.d/*.yml opt/opsview/servicedeskconnector/etc/config.d/*.yml

Restart the servicedesk connector daemon when changed.

Service Desk Connector - optional module


Learn how to install Opsview Monitor Service Desk Connector module

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.