OTRS Trouble Ticket Integration

From OpenNMS
Jump to: navigation, search

Integration of OpenNMS and OTRS allows one to create and manage OTRS tickets from OpenNMS alarms.

OpenNMS should support all OTRS versions that provide "webservices" interfaces of some kind. Prior to OTRS 3.1.x, it was necessary to load custom module into OTRS to supported a real Document-Literal SOAP interface. Since OTRS 3.1, OTRS has supported a more standard SOAP interface and it is no longer necessary to use this custom OTRS module. Because of this change in the SOAP interface a different OpenNMS ticketer plugin (and slightly different configuration) is required between OTRS versions up to and including 3.0.x and OTRS versions from 3.1 onwards.

The following information regarding the OpenNMS interface to OTRS is common for all OTRS versions.

When integration is enabled, 3 new buttons get displayed on the "alarm details" pages ("Create ticket", "Update ticket", "Close ticket"), and the alarm 'state is synchronized with the corresponding ticket 'state in OTRS (ie: ticket can be closed either from OTRS or openNMS, its state will be reflected on the other side). Also, buttons are activated/deactivated accordingly.

Examples

Alarm without corresponding ticket

Alarm2ticket NoTicketYet.png

Alarm with an opened ticket

Alarm2ticket ticketStateIsOpen.png

Alarm with an closed ticket

Alarm2ticket ticketStateIsClosed.png


OTRS Versions prior to 3.1

These instructions are for OTRS versions prior to 3.1. You really should not be using an OTRS version this old!

Install the OpenNMS package in OTRS

  1. Ensure you have the correct prerequisite Perl modules installed on your OTRS host.
    • Version 1.0.0 and 1.1.0 of the OpenNMS package for OTRS require SOAP::Lite, and SOAP::DateTime Perl modules.
    • Version 1.2.0 of the package requires SOAP::Lite and Date::Manip (it no longer requires SOAP::DateTime).
  2. To get the installation package for this module either:
    • Visit the OpenNMS SourceForge page: http://sourceforge.net/projects/opennms/files/ and download a copy of the package to your OTRS server, or
    • Go straight to step 3 below and install directly from the OTRS master repository (only works for version 1.1.0). You will need internet access from your OTRS host for this.
  3. Add the package to otrs
    • At the webUI for OTRS, go to Admin->Package Manager.
    • Add the OpenNMS package, either the copy that you previously downloaded or direct from the OTRS master repository.
  4. Add the SOAP user to OTRS
    • At the webUI for OTRS, go to Admin->SysConfig.
    • Show the Group for "Framework".
    • Select Core::SOAP
    • Set the SOAP::User and SOAP::Password (the sample java code expects opennms/opennms but you should use a "proper" password for production). The opennms package uses the same authentication technique as the existing SOAP handle.
  5. Check the path to the perl binary in $OTRS_HOME/bin/cgi-bin/opennms.pl. The package does not check for the location of your perl binary, and assumes it's /usr/bin/perl. If this is not the case then you will have to modify the cgi by hand.

OTRS OpenNMS package information

Note that the most recent version of OTRS supported by OpenNMS is 3.0.x. OpenNMS does not currently support OTRS 3.1.x. Support for OTRS 3.1.x is currently under development.

OTRS changed between version 2.3 and 2.4, and again between 3.0 and 3.1. You will need to choose the correct OTRS OpenNMS package for your OTRS installation.

  • Version 1.0.0 has been tested with OTRS versions up to 2.3. It does not work with OTRS 2.4. Version 1.0.0 is only available from the OpenNMS SourceForge page.
  • Version 1.1.0 has been tested with OTRS version 2.4. Version 1.1.0 is available from the OpenNMS SourceForge page _and_ the OTRS master repository
  • Version 1.2.0 has been tested with OTRS version 2.4. Version 1.2.0 is available from the OpenNMS SourceForge page. It has not yet been published in the OTRS master repository.
  • Version 1.3.0 has been tested with OTRS version 3.0. Version 1.3.0 is available from the OpenNMS SourceForge page (https://sourceforge.net/projects/opennms/files/OpenNMS%20OTRS%20Integration/1.3.0/)

Version 1.3.0 or the OTRS OpenNMS package is recommended for OTRS version 2.4 or later.

Prerequisite information

  • A change in version 0.712 of SOAP::Lite means that it will not work with mod_perl which is used by OTRS. Version 0.714 fixes this issue and should be installed through CPAN if your distribution does not have it pre-packaged.
  • The OpenNMS-1.3.0 package now works with OTRS 3.0.x. If you still have issues with the 1.3.0 version, please follow the instructions below to hack the 1.2.0 version for OTRS 3.0.x.

Hacking the OpenNMS OTRS package (when all else fails)

  • Note that this will not work for OTRS > 3.0.x.
  • To get the OpenNMS-1.2.0 package to work with version 3.0.x of OTRS, the .sopm file of the OpenNMS-1.2.0 source package needs to be amended with this addition and the package built. There is a 1.3.0 version of the package in the works, but it's not yet available. There are no code changes, OTRS will simply fail to install it because there the framework version doesn't match one of the versions listed in the package spec. You can fix this by editing the OpenNMS.sopm file in the package.
     .
     .
     <otrs_package version="1.1">
     <Name>OpenNMS</Name>
-    <Version>1.2.0</Version>
+    <Version>1.3.0</Version>
     <Vendor>The OpenNMS Project</Vendor>
     <URL>http://www.opennms.org/</URL>
     <License>GNU GENERAL PUBLIC LICENSE Version 2, June 1991</License>
     <Description Lang="en">OpenNMS Integration Module.</Description>
+    <Framework>3.0.x</Framework>
     <Framework>2.4.x</Framework>
     <Framework>2.3.x</Framework>
     <Framework>2.2.x</Framework>

     .
     .

You can check out the source into a local git repo with:

git clone git://github.com/OpenNMS/otrs-opennms.git

and build following instructions at http://doc.otrs.org/developer/3.0/en/html/how-to-publish.html

All that needs to be done is that the package spec needs to be edited as per the above and the package rebuilt.

The specific incantation of the package manager script you will need to rebuild the package is:

$OTRS_HOME/bin/otrs.PackageManager.pl -a build -p <package file> \
-d <package contents directory>

e.g.:

/opt/otrs/bin/otrs.PackageManager.pl -a build \
-p /home/jonathan/dev-jam/git/otrs-opennms/otrs/OpenNMS.sopm \
-d /home/jonathan/dev-jam/git/otrs-opennms/otrs/

Install OTRS Trouble Ticket Plugin in OpenNMS

The implementation of the OTRS plugin is as simple as the following steps:

  • Edit the $OPENNMS_HOME/etc/opennms.properties file and change this:
opennms.ticketer.plugin=org.opennms.netmgt.ticketd.NullTicketerPlugin

to something like this:

opennms.ticketer.plugin=org.opennms.netmgt.ticketer.otrs.OtrsTicketerPlugin
opennms.alarmTroubleTicketEnabled = true
opennms.alarmTroubleTicketLinkTemplate = <a href="http://localhost/otrs/index.pl?Action=AgentTicketZoom&TicketNumber=${id}">${id}</a>

(obviously you will want to specify the hostname of your otrs server, rather than "localhost")

  • Edit the $OPENNMS_HOME/etc/otrs.properties file and change the following according to your installation:
otrs.endpoint=http://localhost/otrs/opennms.pl
otrs.username=opennms
otrs.password=opennms
otrs.state=new
otrs.priority=3 normal
otrs.lock=unlock
otrs.queue=Raw
otrs.articletype=note-external
otrs.defaultuser=root@localhost
otrs.articlefrom=jonathan@opennms.org
otrs.articlesendertype=agent
otrs.articlecontenttype=text/plain; charset=ISO-8859-15
otrs.articlehistorycomment=update by OpenNMS
otrs.articlehistorytype=OwnerUpdate
otrs.ownerid=1
otrs.validopenstateid=1, 4, 6, 7, 8
otrs.validclosedstateid=2, 3, 9
otrs.validcancelledstateid=5
otrs.openstateid=1
otrs.closedstateid=2
otrs.cancelledstateid=5
otrs.ticketopenedmessage=Ticket opened by OpenNMS
otrs.ticketclosedmessage=Ticket closed by OpenNMS
otrs.ticketcancelledmessage=Ticket cancelled by OpenNMS
otrs.ticketupdatedmessage=Ticket updated by OpenNMS
otrs.articleupdatesubject=Ticket update from OpenNMS

Key fields that you will need to update are:

  • otrs.endpoint - you will need to substitute the domain name for your OTRS server here.
  • otrs.username=opennms - this will need to be the SOAP user you configured in the OTRS framework.
  • otrs.password=opennms - this will need to be the SOAP password that you configured in the OTRS framework.
  • otrs.articlefrom - This will be the eMail that the ticket appears from - you probably don't want to use my eMail address ;-).
  • otrs.ticketopenedmessage etc. - This allows you to localize the OTRS article body when the state of a ticket is changed via OpenNMS.
  • otrs.articleupdatesubject - This allows you to localize the OTRS article subject the state of a ticket is changed via OpenNMS.

If you are running OTRS 2.4, you can optionally change:

otrs.articlecontenttype=text/plain; charset=ISO-8859-15

to

otrs.articlecontenttype=text/html; charset=ISO-8859-15

This will allow OTRS to render the HTML from Alarms correctly (thanks Patrick).

OTRS versions after 3.1

OTRS configuration

Note that there is no need to install the OpenNMS package in OTRS. You will need to enable the GenericTicketConnector in OTRS, however. You can do this by creating a new webservice called "GenericTicketConnector" from the Admin pages in OTRS using the following YAML:

---
Debugger:
  DebugThreshold: debug
  TestMode: 0
Description: Ticket Connector Sample
FrameworkVersion: 3.1.x CVS
Provider:
  Operation:
    SessionCreate:
      Description: Creates a Session
      MappingInbound: {}
      MappingOutbound: {}
      Type: Session::SessionCreate
    TicketCreate:
      Description: Creates a Ticket
      MappingInbound: {}
      MappingOutbound: {}
      Type: Ticket::TicketCreate
    TicketUpdate:
      Description: Updates a Ticket
      MappingInbound: {}
      MappingOutbound: {}
      Type: Ticket::TicketUpdate
    TicketGet:
      Description: Retrieve Ticket data
      MappingInbound: {}
      MappingOutbound: {}
      Type: Ticket::TicketGet
    TicketSearch:
      Description: Search for Tickets
      MappingInbound: {}
      MappingOutbound: {}
      Type: Ticket::TicketSearch
  Transport:
    Config:
      MaxLength: 100000000
      NameSpace: http://www.otrs.org/TicketConnector/
    Type: HTTP::SOAP
RemoteSystem: ''
Requester:
  Transport:
    Type: ''

You can find the most up-to-date version of ths service configuration YAML file in $OTRS_HOME/scripts/test/Console/Command/Admin/WebService/GenericTicketConnectorSOAP.yml.


You will also need to have appropriate users and queues established. You will need an agent user to create the tickets and also a valid customer user tickets to be from.

OTRS Free 5.0

Specific note for OTRS Free 5.0 prior to 5.0.12

OTRS free 5.0 prior to 5.0.12 seems to have a bug, documented in http://bugs.otrs.org/show_bug.cgi?id=12196 and http://bugs.otrs.org/show_bug.cgi?id=12213 that breaks the ticketer integration. You can fix this by editing {$OTRS_HOME}/Kernel/GenericInterface/Transport/HTTP/SOAP.pm around line 158 and changing:

( $SOAPAction, $NameSpaceFromHeader, $OperationFromHeader ) = $SOAP_ACTION =~ m{
             \A
            ["']{0,1} # optional enclosing single or double quotes
            (
                ( .+? )      # namespace
                [#/]
                ( [^#/]+? )  # operation
            )
            ["']{0,1} # optional enclosing single or double quotes
            \z
        }xms;


to:

( $SOAPAction, $NameSpaceFromHeader, $OperationFromHeader ) = $SOAP_ACTION =~ m{
             \A
            ["']{0,1} # optional enclosing single or double quotes
            (
                ( .+?/ )     # namespace
                ( [^#/]+? )  # operation
            )
            ["']{0,1} # optional enclosing single or double quotes
            \z
        }xms;

This is not an "OTRS approved" change however and YMMV.

OTRS Free 5.0.12 and above

Version 5.0.12 has a fix for this bug and will work with the Otrs31TicketerPlugin with no modifications to the OTRS code (though you will still obviously need to configure the webservice and appropriate users as described above).

opennms.properties configuration

Enable the OTRS 3.1 trouble ticketer plugin in opennms.properties

opennms.ticketer.plugin=org.opennms.netmgt.ticketer.otrs31.Otrs31TicketerPlugin
opennms.alarmTroubleTicketLinkTemplate = <a href="http://localhost/otrs/index.pl?Action=AgentTicketZoom&TicketNumber=${id}">${id}</a>
opennms.alarmTroubleTicketEnabled = true

otrs.properties configuration

# 
# This is the configuration or the OpenNMS ticketer plugin for OTRS.
#
# This configuration file can be used for all versions of the plugin.
# Some configuration directives may need modification according to 
# the plugin version used.
#
# General Notes:
#
# All tickets will use the OpenNMS ticket summary for the OTRS ticket
# title and initial Article subject
#
# The OpenNMS ticket details are used for the OTRS article body.
#
# All subsequent articles (updates from OpenNMS to OTRS) will have
# article subject and body set according to the defaults in this file.
# 
# There are two versions of the OTRS ticketer plugin class:
# 
# Users of OTRS 3.0.x and below should use the original plugin
# 
#   org.opennms.netmgt.ticketer.otrs.OtrsTicketerPlugin
# 
# Users of OTRS 3.1.x and above should use the original plugin
# 
#   org.opennms.netmgt.ticketer.otrs31.Otrs31TicketerPlugin
#
# The plugin must be enabled via opennms.properties by setting the 
# following properties:
#
#   opennms.ticketer.plugin
#   opennms.alarmTroubleTicketEnabled
#   opennms.alarmTroubleTicketLinkTemplate
#
# See that file for examples.


#####################################################################
#
# This is the SOAP endpoint address that OpenNMS will communicate with
# Used for all versions of the plugin
#
# This configuration required by all versions
#
#####################################################################

# Typical OTRS v 3.0.x and below endpoint
otrs.endpoint=http://localhost/otrs/opennms.pl

# Typical OTRS v 3.1.x and above endpoint
#otrs.endpoint=http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnector

#####################################################################
#
# User configuration
#
# For OTRS version 3.0.x and below, this is a specific "soap" user
# and password set via admin->sysconfig:
#
#   At the webUI for OTRS, go to Admin->SysConfig.
#   Show the Group for "Framework".
#   Select Core::SOAP
#   Set the SOAP::User and SOAP::Password 
#
# For OTRS 3.1.x and above, this is a regular OTRS user
# with appropriate permissions on the queue set by otrs.queue (below)
#
# This configuration required by all versions
#
#####################################################################

otrs.username=opennms
otrs.password=opennms

#####################################################################
#
# General Ticket and article configuration
#
# paramters used to set the initial state of a ticket
#
# This configuration common to all versions
#
#####################################################################

# This field was intended to be the OTRSstate for new tickets
# Numeric state ID was used instead. Unused in all version of the 
# plugin

otrs.state=new

# This field is used to set ticket priority
# Used when ticket initially created only

otrs.priority=3 normal


# This field used to set the queue for new tickets.
# Used when ticket initially created only

otrs.queue=Raw

# The user that the ticket will appear from in OTRS
# For OTRS 3.1.x and above this needs to be a valid OTRS customer user
# eg. customer@localhost or similar.

otrs.defaultuser=root@localhost

#####################################################################
#
# Specific 3.0.x and below configuration
#
# Not used for 3.1.x and above
#
#####################################################################

# OTRS ownerid. Used when creating new OTRS tickets only
# Unlikely to need changing

otrs.ownerid=1

# This field used to ensure that new tickets are created unlocked.
# Unlikely to need changing

otrs.lock=unlock

# The user that articles will appear from in OTRS
# Typically the same as the default user
# You will need to customise this for your installation

otrs.articlefrom=root@localhost


#####################################################################
#
# Article Type fields
#
# Only change these if you know what you're doing
#
# This configuration common to all versions
#
#####################################################################


otrs.articletype=note-external

otrs.articlesendertype=agent

otrs.articlecontenttype=text/plain; charset=ISO-8859-15

otrs.articlehistorycomment=update by OpenNMS

otrs.articlehistorytype=OwnerUpdate

#####################################################################
#
# OpenNMS to OTRS ticket state conversion
#
# Don't change these unless you have modified the default OTRS
# State ids.
#
# This configuration common to all versions
#
#####################################################################

# OTRS state IDs considered as equivalent to OpenNMS "open" state
# when converting from OTRS ticket state to OpenNMS ticket state

otrs.validopenstateid=1, 4, 6, 7, 8

# OTRS state IDs considered as equivalent to OpenNMS "closed" state
# when converting from OTRS ticket state to OpenNMS ticket state

otrs.validclosedstateid=2, 3, 9

# OTRS state IDs considered as equivalent to OpenNMS "cancelled" state
# when converting from OTRS ticket state to OpenNMS ticket state

otrs.validcancelledstateid=5

# OTRS state IDs considered as equivalent to OpenNMS "open" state
# when converting from OpenNMS ticket state to OTRS ticket state

otrs.openstateid=1

# OTRS state IDs considered as equivalent to OpenNMS "closed" state
# when converting from OpenNMS ticket state to OTRS ticket state

otrs.closedstateid=2

# OTRS state IDs considered as equivalent to OpenNMS "cancelled" state
# when converting from OpenNMS ticket state to OTRS ticket state

otrs.cancelledstateid=5

#####################################################################
#
# Text used for OTRS article subject and body
#
# Set these as per your local requirements
#
# This configuration common to all versions
#
#####################################################################

# Text used for OTRS article subject when updating a ticket from OpenNMS

otrs.articleupdatesubject=Ticket update from OpenNMS

# Text used for OTRS article body when reopening a ticket from OpenNMS

otrs.ticketopenedmessage=Ticket opened by OpenNMS

# Text used for OTRS article body when closing a ticket from OpenNMS

otrs.ticketclosedmessage=Ticket closed by OpenNMS

# Text used for OTRS article body when cancelling a ticket from OpenNMS

otrs.ticketcancelledmessage=Ticket cancelled by OpenNMS

# Default Text used for OTRS article body when OpenNMS ticket state
# Cannot be retrieved 

otrs.ticketupdatedmessage=Ticket updated by OpenNMS