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:
- 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 Copied
The OTRS API requires configuration to allow the creation and updating of tickets. This requires at least OTRS 3.1.
- Download the configuration YAML file from the Opsview AWS.
- Log in to OTRS as an administrator, and navigate to Admin > System Administration > Web Services.
- Click ‘Add web service’, then ‘Import web service’.
- Browse to the downloaded yml file to select.
- 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:
- 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 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:
- 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 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:
- 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 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