1. synetics
  2. i-doit
  3. otrs-opm-referenceidoitobjects

Overview

HTTPS SSH

% OTRS Module ReferenceIDoitObjects % Benjamin Heisig, synetics GmbH, bheisig@i-doit.org

About

Create a ticket in relation to one or more i-doit objects

This module gives you the opportunity to combine an issue tracker like OTRS with an IT documentation tool / CMDB like i-doit. It uses i-doit's API to relate a ticket with one or more CIs / objects managed by i-doit. On i-doit's side you are able to view all tickets related to an object. This module also supports i-doit's multi-tenant functionality.

i-doit ("I document IT") is a Web-based tool to document complex IT infrastructures. It provides several modules like a ITIL compliant Configuration Management Database (CMDB). Its core is Free and Open Source Software. Visit i-doit.com for commercial support and additional services.

Download

Download the latest stable release from the OTRS Package Archive (OPAR).

To get the latest code contributions please visit the project website on BitBucket. For example, checkout the master branch via Git:

git clone \
https://bitbucket.org/synetics/otrs-opm-referenceidoitobjects.git

Installation

Please follow this step by step instruction to install the module properly.

System Requirements

This module requires OTRS Help Desk 3.3.x and a running installation of i-doit 1.4.x or higher.

Install via Web GUI

There are two ways to install the module. This is the easiest way done via the OTRS Web GUI. You need administration rights to proceed. Go to Admin => Package Manager, select the OPM file and click on the button Install Package.

Note: If you see a warning that this module is not verified by the OTRS Group just click the button to continue installation.

Install via CLI

Alternatively, install the module via the command line interface (CLI). Every OTRS installation includes a script called "Package Manager" mostly located under /opt/otrs/bin/otrs.PackageManager.pl. Copy the OPM file to the host where OTRS is deployed and run this script as the OTRS user:

sudo -u otrs /opt/otrs/bin/otrs.PackageManager.pl \
-a install -p ReferenceIDoitObjects-0.9.opm

Note: The OTRS user, the installation path, and the path to the OPM file may differ.

Run the Web Service

Futhermore, you need a running Web service. i-doit corresponds with OTRS over the GenericInterface and its SOAP server. You can use the example configuration from the OTRS admin manual, section "Web Service Configuration". This example is also available in project repository under scripts/GenericTicketConnector.yml. Import this file in OTRS under Admin => Web Services.

Note: It may be necessary to set the proper rights to access the tickets for each queue via the Web service.

_GenericInterface Web Service Management_

Add Needed Dynamic Fields

After that you need two dynamic fields named IDoitTenant and IDoitObjects for tickets (not articles). To get in touch with dynamic fields read more about it at OTRS admin documentation.

_Dynamic Fields Management - Overview_

IDoitTenant

  • Name: IDoitTenant
  • Description: i-doit tenant
  • Field type: dropdown
  • Validity: valid
  • Object type: ticket
  • Possible keys and values: all i-doit tenants you want to include
    • Keys matches the tenant API keys.
    • Values matches the tenant names.
  • Standard value: your default tenant
  • Add empty value: no
  • Translatable values: no

_Dynamic Fields - Ticket: Change Text Field_

IDoitObjects

  • Name: IDoitObjects
  • Description: i-doit objects
  • Field type: text
  • Validity: valid
  • Object type: ticket

_Dynamic Fields - Ticket: Change Text Field_

Configuration

Configuration is done via SysConfig which is reachable via the Web GUI.

ReferenceIDoitObjects

In the left dropdown there is a configuration group called ReferenceIDoitObjects. Under the sub group Ticket you find several configuration settings.

_SysConfig_

_Edit Config Settings in ReferenceIDoitObjects -> Ticket_

ReferenceIDoitObjects::URL

It's highly recommended to establish an encrypted connection between OTRS and i-doit over a network, e. g. TLS over HTTP (HTTPS).

ReferenceIDoitObjects::API

Please be aware of browsers' Same Origin Policy! This module uses AJAX requests access i-doit's API. If OTRS and i-doit are not available under the same domain name (or IP address), AJAX calls will fail.

To avoid this "problem" (actually this policy is very useful) you can setup an AJAX proxy. This module already provides such a proxy located in the project repository under scripts/i-doit_api_proxy.php. It's written in PHP, so you have to install PHP 5.4 or higher and the PHP extension curl on the same machine where OTRS is installed. Make this little script available through your Web server and edit the script by setting $l_url to the URL of i-doit's API, e. g.

http://example.org/i-doit/index.php?api=jsonrpc

In OTRS' site configuration ReferenceIDoitObjects::API has to be set to this script, e. g.

http://otrs.example.org/path/to/i-doit_api_proxy.php

Note: You may test the proxy by simple calling it via your Web browser. It should display an error describing this is not a proper API call.

ReferenceIDoitObjects::DefaultView

When creating or editing a ticket, this module adds a so-called "object browser" to the Web interface. The browser gives you several views on objects:

objects

Select objects provided by the API and filter them by type.

workplaces

Select users' workplaces and their related sub objects. Each user will be taken by the email address provided by OTRS' field To Customer if these users are documented in i-doit.

i-doit gives you the possiblity to create relations between users, their workplaces and all equipment related to these workplaces.

Tip: You may synchronize user information between OTRS and i-doit via LDAP.

devices

Select assigned devices for current user. Those devices are objects in i-doit which have this user as an assigend person.

selected

View and remove all selected objects.

ReferenceIDoitObjects::InstalledSoftware

Defines which type of objects will be shown for the installed software. There are two options: objects or `relations".

objects

Shows software objects which are assigned to the currently selected object.

relations

Shows the software relation between the object and the assigned software.

Ticket Frontend

Activate the dynamic fields in the so called Ticket Zoom Screen: In the SysConfig go to configuration group Ticket (in the left dropdown), then to the sub-group Frontend::Agent::Ticket::ViewZoom. Enable the dynamic fields in the setting Ticket::Frontend::AgentTicketZoom###DynamicField by using their names as keys and 1 as content.

_Ticket::Frontend::AgentTicketZoom###DynamicField_

To enable i-doit's feature to create a new ticket within the category All Tickets you have to add the dynamic fields to the formular of ticket creation. In the SysConfig go to configuration group Ticket (in the left dropdown), then to the sub-group Frontend::Agent::Ticket::ViewPhoneNew or Frontend::Agent::Ticket::ViewEmailNew. Activate the setting Ticket::Frontend::AgentTicketPhone###DynamicField or Ticket::Frontend::AgentTicketEmail###DynamicField, add both dynamic fields, and enable them: Set the dynamic field names (IDoitTenant and IDoitObjects) as keys and 1 as content.

_Ticket::Frontend::AgentTicketEmail###DynamicField_

Usage

Whenever you view an existing ticket you are able to reference this ticket with one or more objects in i-doit. There is an additional link in the navigation menu for this. After clicking on the link a popup will shown up with the so-called "object browser". Just select the objects you need or unselect the objects you don't need.

Ticket navigation bar

Popup with "object browser"

Authors

Bugs

Please report any bugs or feature requests to the authors.

Copyright and License

Copyright 2012-14 synetics GmbH

This software comes with ABSOLUTELY NO WARRANTY. For details, see COPYING for license information (AGPLv3).

Open-source Ticket Request System (OTRS) is Copyright OTRS AG.

Frequently Asked Questions (FAQ)

How do i-doit and OTRS Help Desk communicate with each other?

On the one hand the module uses your Web browser to access the i-doit API. All is done via AJAX calls. The OTRS server doesn't communicate with the i-doit server.

On the other hand i-doit uses its backend server to communicate with the OTRS server directly.

There is no object browser displayed in the popup windows.

Please verify your settings and check whether you need the AJAX proxy. If the problem still exists debug the communication between OTRS and i-doit with your Web browser: Modern browsers includes web developer tools. Look for HTTP POST requests (especially the corresponding responses) and JavaScript errors.

Please verify your TTS settings and check whether all system requirements are met. Additionally, check whether the configured OTRS user has enough rights to read all tickets and queues. If the problem still exists debug the communication between i-doit and OTRS and look for errors in the server logs.

After updating the module the object browser don't show up.

Sometimes OTRS doesn't update every setting. Please verify the config settings in ReferenceIDoitObjects => AgentFrontendModuleRegistration.

_Edit Config Settings in ReferenceIDoitObjects -> AgentFrontendModuleRegistration_

Changelog

Version 0.9 (tba)

  • Fixed creating new logbook entries
  • Cleaned up tables and improved their styling
  • Updated dataTables plugin
  • Re-named "mandator" to "tenant"
  • Re-factored code
  • Improved code documentation
  • Enhanced user documentation

Version 0.8 (2014-08-15)

  • Improved selecting object type
  • Fixed fetching API key for selected tenant
  • Removed unused setting for default tenant
  • Fixed storing object selection to database
  • Fixed broken AJAX call to fetch devices related to current customer
  • Fixed error with special chars in ticket subject
  • Fixed error message while loading browser
  • Fixed unselectable workplace components
  • Fixed fetching right object type when selecting an object
  • Fixed (un)selecting all object items in a table
  • Fixed selecting objects in all tables at the same time
  • Avoid syntax error when there are no assigned devices
  • Fixed missing translations
  • Updated dataTables plugin
  • Re-factored code
  • Improved code documentation

Version 0.7 (2014-05-07)

  • Added view for assigned devices
  • Make extension compatible to OTRS Help Desk 3.3.x
  • Use i-doit's API key instead of username/password
  • Share code with Request Tracker extension

Version 0.6 (2013-04-05)

  • Tested compatibility with OTRS Help Desk 3.2.x

Version 0.5 (2012-09-07)

  • Removed deprecated Switch.pm
  • Improved installation section "Ticket Frontend" in README file

Version 0.4 (2012-08-14)

  • Fixed error message
  • Fixed un-selecting objects in object view
  • Improved configuration section in README file

Version 0.3 (2012-08-08)

  • Added checkbox to select/unselect all objects from object view
  • Added link to remove all selected objects from list
  • Show message if no requestor is selected

Version 0.2 (2012-05-29)

  • Added proxy script to distribution tarball

Version 0.1 (2012-05-14)

  • Initial release

See Also