ITRS Opsview Cloud Documentation

Service Desk Connector Module (Optional)

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 is 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 Copied

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.8 | sudo bash -s -- -A boot

Installing Service Desk Connector Copied

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

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 (including Virtual Appliances), run the following command as root after activating Opsview:

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

# setup self monitoring for the Service Desk Connector
./bin/opsview-deploy lib/playbooks/setup-monitoring.yml

In either case, ensure that the optional module is included in your Opsview license.

Service Desks Copied

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 Copied

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

For hosts, the following must be true:

OTRS Copied

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

  1. Download the configuration YAML file from the Opsview AWS.
  2. Log in to OTRS as an administrator, and navigate to Admin > System Administration > Web Services.
  3. Click ‘Add web service’, then ‘Import web service’.
  4. Browse to the downloaded yml file to select.
  5. Click Import.

Service Desk configuration Copied

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

Configuration file within /opt/opsview/servicedeskconnector/etc/config.d:

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:

For hosts, the following must be true:

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 Copied

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:

For hosts, the following must be true:

RequestTracker Copied

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:

For hosts, the following must be true:

Configuring Notification Methods in the UI Copied

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 Copied

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

This change will work, but will not be persistent upon an upgrade. In order to make this persistent you will need to add the below variable with your new retention value to the /opt/opsview/deploy/etc/user_vars.yml file and run the playbook servicedesk-connector-install.yml

After doing this you should see the new value reflected within the notifications.yml file.

opsview_servicedesk_audit_retention_days: <retention value>

cd /opt/opsview/deploy
./bin/opsview-deploy lib/playbooks/servicedesk-connector-install.yml

Testing Copied

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 servicecloud

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 Copied

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.

Troubleshooting Copied

DBI Notification Errors Copied

Upon upgrading to version 6 of Opsview you may encounter the below error:

Broadcast message from systemd-journald@opsview-appliance (Wed 2019-12-11 07:03:53 UTC):
opsview_notifyd[4517]: [PAR::_run_member_from_par:167] [FATAL] DB error: DBIx::Class::Storage::DBI::catch {...} (): DBI Connection failed: DBI connect('database=notifications;host=127.0.0.1;port=13306','notifications',...) failed: Access denied for user 'notifications'@'127.0.0.1' (using password: YES) at /opt/opsview/perl/lib/perl5/DBIx/Class/Storage/DBI.pm line 1483. at script/opsview_notifyd line 137

This indicates that the notifications user does not have the permission to access the necessary notifications database In order to resolve this we must GRANT the user the necessary permissions and this is done by the MySQL console

Please run the following to check that the notification user has been created:

select * from mysql.user where user = "notifications"

If the user is not present, please run the servicedesk-connector-install.yml playbook as instructed earlier in this document

If the user is present, proceed to run the following commands to grant the notifications user the appropriate permissions.

GRANT ALL ON notifications.* TO notifications@'%' WITH GRANT OPTION;
GRANT ALL ON notifications.* TO notifications@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Following this you should no longer have the DBI errors in the logging /var/log/opsview/opsview.log.

You may test the connectivity by obtaining the servicedesk-connector password and running the mysql command below, or restarting the servicedesk-connector component:

grep -i servicedesk /opt/opsview/deploy/etc/user_secrets.yml
opsview_servicedesk_database_password: <PASSWORD WILL DISPLaY HERE>

# mysql -h 127.0.0.1 -u notifications -p -D notifications -P 13306
Enter Password:

Or:

/opt/opsview/watchdog/bin/opsview-monit restart opsview-servicedeskconnector

If you still receive an Access Denied error or Broadcast error message, please ensure that the opsview_servicedesk_database_password setting is not referenced or set anywhere else apart from the file /opt/opsview/deploy/etc/user_secrets.yml, so check within the file system structure /opt/opsview/deploy/etc/* and then re-run the associated playbook.

After this, please test the access once more.

grep -iR servicedesk /opt/opsview/deploy/etc/

or / and

cd /opt/opsview/deploy
./bin/opsview-deploy lib/playbooks/servicedesk-connector-install.yml
["Opsview On-premises"] ["User Guide"]

Was this topic helpful?