OTRS Joomla Gateway Installation Instructions

Title OTRS Joomla Gateway Installation InstructionsDocument # VI-401963-PRRevision 3Author Vittal AithalIssue Date 09 May 2011

Revision Author Date Details1 VA 18Oct10 Initial release2 VA 31Jan11 Update to indicate OTRS 3.0.x is now supported3 VA 9May11 Update for release 0.9.1 which supports Joomla 1.6

SummaryThe Joomla OTRS Gateway component is a Joomla component that allows OTRS customer users to access their OTRS tickets through a Joomla front-end. The gateway is aimed at users who what to use OTRS's agent and mail handling functionality while maintaining a consistent public interface, serviced in Joomla.

This document details the requirements and installation/configuration steps needed to use the Joomla OTRS Gateway component.

Contents

1 Requirements .................................................................................................................................................... 1 2 Installation ........................................................................................................................................................ 1

2.1 OTRS Package ............................................................................................................................................ 2 2.2 Joomla Component ................................................................................................................................... 2

3 Configuration .................................................................................................................................................... 2 3.1 Enable OTRS SOAP .................................................................................................................................... 2 3.2 Configuring Joomla ................................................................................................................................... 3

4 Adding Menu Items ........................................................................................................................................... 4 5 Troubleshooting ................................................................................................................................................ 4

1 RequirementsYou must have the following software installed or meet these requirements before you install the component:

Joomla 1.5.x or Joomla 1.6.x OTRS 2.4.x or OTRS 3.0.x PHP 5.x with the JSON extension enabled on the Joomla server The SOAP::Lite perl module installed on the OTRS server Administrative access to OTRS Administrative access to Joomla

2 InstallationIn order to install the Joomla OTRS gateway, you must download two files from the Cognidox website http://www.cognidox.com/opensource/otrs-joomla-gateway/ :

An OTRS .opm package file A Joomla component zip file for either Joomla 1.5 or Joomla 1.6

Cognidox Limited, 2011 Page 1 VI-401963-PR-3

A video walkthrough of this installation process is also available from the website.

2.1 OTRS PackageThe first part of installation is to install an OTRS package via the OTRS Package Manager. The gateway's OTRS package provides an RPC handler script and an OTRS module to handle gateway requests. The package does not affect existing OTRS functionality. To install the package, follow the steps below:

1. Log into the OTRS agent web interface as an administrator2. Click Package Manager in the Admin area3. In the Install section, click the Browse button and select the OTRS-Joomla .opm package file4. Click the Install button5. Verify the confirmation message appears and click Continue

At this point, the OTRS package is installed. Continue on to install the Joomla component itself.

2.2 Joomla ComponentThe second part of the installation process is to install the Joomla component suitable for your Joomla version. Both Joomla 1.5 and 1.6 versions of the component are available, and it is important to use the correct version for your Joomla installation. This component includes the gateway itself and two plugins, one for authenticating customer users to OTRS and one for searching tickets. To install the component, follow the steps below:

1. Log into the Joomla administration site as an administrator2. Select Extensions Install/Uninstall3. In the Upload Package File section, click the Browse button and select the Joomla-OTRS .zip file4. Click Upload File & Install5. Verify the successful component install message is shown

At this point, the gateway component is installed in Joomla and both the OTRS search and authentication plugins are enabled. Continue on to configure the OTRS package and the Joomla component.

Note that a newer version of the Joomla component can be installed over an existing version by repeating the steps above. Existing configuration settings will not be altered.

3 ConfigurationBefore the gateway can be used, authentication credentials must be configured in both OTRS and Joomla. These credentials allow the gateway component to authenticate actions in OTRS.

3.1 Enable OTRS SOAPThe gateway uses OTRS's SOAP interface to exchange messages between Joomla and OTRS. The SOAP interface requires a SOAP specific username and password to be set in OTRS. If the SOAP username and password have already been set, the following steps can be skipped. If the SOAP username and password are not set, follow the steps below:

1. Log into the OTRS agent web interface as an administrator2. Click SysConfig in the Admin area3. In the Search section, type SOAP into the Search for field, and click the Search button4. Once the search is completed, a link labeled Core::SOAP will be show in the Result section. Click the

Core::SOAP link5. Enter values for SOAP::User and SOAP::Password, ensuring that both fields are marked as active

Cognidox Limited, 2011 Page 2 VI-401963-PR-3

6. Click the Update button

The SOAP username and password values are now configured in OTRS. The value must now be replicated in Joomla.

3.2 Configuring JoomlaThe final configuration step is to set the OTRS location and authentication details in Joomla. Follow the steps below to complete the configuration:

1. Log into the Joomla site administration interface as an administrator2. Select Components OTRS Gateway3. Click the Parameters icon4. Set the RPC URL field to the correct URL for the OTRS system. (If the OTRS system is installed on the

same virtual host as Joomla, the default URL should be correct.)5. Set the RPC User and RPC Password values with the SOAP::User and SOAP::Password field values from

the OTRS configuration6. If the OTRS authentication plugin is not to be used, select how Joomla users are to be mapped to

OTRS users by setting the User Mapping field. Mapping by Login means that Joomla users and OTRS customer users must share a login. Mapping by E-mail means that Joomla users and OTRS customer users must share an email address.

7. Click the Save button to complete the configuration8. Reload the OTRS Gateway page and confirm the Gateway Summary reads Connected OK

The OTRS Gateway Joomla components is now ready to be used.

Cognidox Limited, 2011 Page 3 VI-401963-PR-3

Drawing 1: The OTRS SysConfig section showing the SOAP fields active and with values set

Drawing 2: The OTRS Gateway component parameters window

4 Adding Menu ItemsThe OTRS Gateway component provides two Joomla menu layouts that can be used in Joomla menus:

A ticket list layout, used for showing lists of the user's tickets or lists of the user's company's tickets. The menu item's Basic Parameters allow for selection between user and company tickets.

A new ticket submission form layout

5 TroubleshootingThe following list is a set of possible problems that may occur when installing or using the OTRS gateway component:

1. When configuring the OTRS Gateway component, the Gateway Summary reports:

SOAP Fault: (faultcode: soap:Client, faultstring: Application failed during request deserialization: no element found...

This is caused bug #58538 in the perl SOAP::Lite module (https://rt.cpan.org/Public/Bug/Display.html?id=58538). To resolve this, either downgrade the SOAP::Lite module on the OTRS server to version 0.69, or edit the installed SOAP/Transport/HTTP.pm file, changing the sysread call to a read call.

2. Replying to a ticket does not work the reply window does not disappear and the ticket does not get updated.

This is most likely caused by the JSON extension not being installed in PHP on the Joomla server. For versions of PHP prior to 5.2.0, install the JSON module from Pecl http://pecl.php.net/package/json otherwise, use JSON support compiled into PHP.

Cognidox Limited, 2011 Page 4 VI-401963-PR-3

Drawing 3: The OTRS Gateway views shown when adding a new menu item

Company Information

Registered Office : Cognidox LimitedSt Johns Innovation CentreCowley RoadCambridge CB4 0WSUK

Registered in England and Wales No. 06506232

Email opensource@cognidox.com

Telephone +44 (0) 1223 911080

Smart Document ManagementCogniDox helps teams in Engineering, Marketing, Sales, Operations and other departments to capture, share and publish product and design documentation.

This easy-to-use tool helps break down the barriers to find information, share solutions and enjoy a faster, more productive development workflow inside your company. In addition, CogniDox will help you manage and publish documents and other content to licensed customers. It reduces technical support load and accelerates your customers' time to market.

www.cognidox.com

Cognidox Limited, 2011 Page 5 VI-401963-PR-3

1 Requirements2 Installation2.1 OTRS Package2.2 Joomla Component

3 Configuration3.1 Enable OTRS SOAP3.2 Configuring Joomla

4 Adding Menu Items5 Troubleshooting