NMIS Connectwise Integration

Owned by Josune Cordoba (Unlicensed)
Last updated: Dec 22, 2020
3 min read

This connector is a Notification Extension for NMIS8 and is able to open and close tickets in ConnectWise in synchronization with the events reported by NMIS.

Summary

The connector runs on every NMIS Collect, the frequency depends on the NMIS Collect configuration. The connector open a ticket on ConnectWise only if it is a stateful event and saves the ConnectWise Ticket ID along with the event details on a JSON file to keep track of it. On a NMIS "Closing" Event, the connector will match the event and retrieve the ConnectWise Ticket ID to close the ticket in ConnectWise, once the confirmation of the closed ticket is received, the event details are completely removed from the JSON file.

Config Items

There are few new items that should be added to the NMIS Config file. Usually located at: 

/usr/local/nmis8/conf/Config.nmis

  • 'auth_cw_server': The connectWsise server.
  • 'auth_cw_company_id': Company ID
  • 'auth_cw_public_key': Public Key
  • 'auth_cw_private_key': Private Key
  • 'auth_cw_clientId': ClientID created for the integration.
  • 'cw_ticket_companyId': The Company ID associated to the tickets that are been created.
  • 'connector_file_storage': Filename location where the data of the created tickets will be stored.

These items have to be added to their respective section:

'authentication' => {
'auth_cw_server' => '',
'auth_cw_company_id' => "",
'auth_cw_public_key' => "",
'auth_cw_private_key' => "",
'auth_cw_clientId' => "",
'cw_ticket_companyId' => ""
}

'files' => {
'connector_file_storage' => '<nmis_var>/connector_storage.json'
}


Deployment (Install)

As a custom notification method, the "connectiwise_connector.pm" should be saved at:

/usr/local/nmis8/lib/Notify/

The configuration of the escalation method should be updated. This file is found at: /usr/local/nmis8/conf/Escalations.nmis

As a preference it should be configured under the section 'default_default_default_default__', on Level 0 and with the option "UpNotify" set to "true" (This option is important, otherwise, the connector will not be able to close ticket in the ConnectWise).

Sample Escalations.nmis configuration:

'default_default_default_default__' => {
'Event' => 'default',
'Event_Element' => '',
'Event_Node' => '',
'Group' => 'default',
'Level0' => 'syslog:localhost,connectwise_connector:Contact1',
'Level1' => 'syslog:localhost',
'Level2' => 'syslog:localhost',
'Level3' => 'syslog:localhost',
'Level4' => 'syslog:localhost',
'Level5' => 'syslog:localhost',
'Level6' => 'syslog:localhost',
'Level7' => 'syslog:localhost',
'Level8' => 'syslog:localhost',
'Level9' => 'syslog:localhost',
'Level10' => 'syslog:localhost',
'Role' => 'default',
'Type' => 'default',
'UpNotify' => 'true'
}


It is also important to notice that the escalation method has a "contact" associated to it, this contact is listed in the config file /usr/local/nmis8/conf/Contacts.nmis and is used to restrict the days and times that a notification can be sent out. Usually is used to don't disturb people out of their duty hours. In this case, we create a "contact" for the ConnectWise Platform, this contact must be available 24/7 and receive all event levels.

Sample Contacts.nmis configuration:

'contact1' => {
'Contact' => 'Contact1',
'Phone' => '',
'DutyTime' => '00:24:MonTueWedThuFriSatSun', 
'Level' => '(Fatal|Critical|Major|Minor|Warning|Normal)',
'TimeZone' => '0',
'Pager' => '',
'Mobile' => '5555551234',
'Location' => 'default',
'Email' => 'nobody@localhost.com'
}


From this sample config it is important to highlight that the "DutyTime" is set to 00:24 which indicates from 00 Hours to 24 Hours and also indicates the 7 days of the week. The items "Mobile" and "Email" are also important and must have a valid format as these are send to ConnectWise as data to open the ticket, connectWise validates these items and reject the ticket opening request if it finds a wrong format or missing details.

Note: It is preferable to maintain the filename in order to avoid errors with NMIS while loading the extension. If a rename is need, the package name should be updated to reflect this change, it may also need to change the name used on /usr/local/nmis8/conf/Escalations.nmis.

Testing the Connector

The connector can be tested using the test script:

/usr/local/nmis8/admin/testconnectwise.pl debug=9


Additional Info

Currently the connector is limited to use and send the following items to connectWise for a ticket creation:

  • "summary"
  • "recordType"
  • "status"
  • "contact"
  • "company"
  • "contactName"
  • "contactPhoneNumber"
  • "contactEmailAddress"
  • "priority"
  • "severity": "Low",
  • "impact": "Low",
  • "allowAllClientsPortalView": true
  • "initialDescription"
  • "processNotifications": true
  • "skipCallback": true
  • "predecessorType"

For more details: https://developer.connectwise.com/Products/Manage/REST#/Tickets/postServiceTickets

NMIS Version

Will be published in NMIS 8.7.2 and NMIS 9.1.2.