Extension:OtrsTicket

OtrsTicket adds a limited ability to do read-only access of attributes from one or more OTRS instances, allowing easy integration with OTRS for the purpose of displaying current state of the tickets. It will enforce policy on access according to LocalSettings.php, and all data made available will be readable for everyone with read access to the generated page. Multiple OTRS-instances can be configured, with different access policy for each one.

Usage
One or more external instances of OTRS, a ticketing system, is queried over the SOAP interface about the set values of a number of attributes. Each value is either reported as a single value or as a composite structure, each with or without additional identifiers. The purpose of the reporting is for embedding the information within a human readable page, still there can be additional markup to make the information machine readable.

The instance must be given and this identifies the OTRS-system. An instance has the necessary log on tokens, the access policy for the individual data fields and possibly filters (regexps) for the query strings. These will be set in LocalSettings.php and can't be overridden. This file also holds the soap-users credentials. There may be several systems defined.

Some requests that is usually not human readable (or human friendly) may be translated to a more friendly form. This may give additional requests to the OTRS-system, and will be cached if possible.

Arguments to the parser functions are typically of three different types


 * Named query parameters that must be recognized as such
 * Anonymous attributes used to identify the reported data values
 * Surplus arguments for the parser functions own purposes

Anonymous attributes not used for filtering the data from the OTRS system will silently be discarded. Identified named parameters that does not validate will generate an error condition. Surplus arguments may define their own error states.

Time to live for a client is usually for the duration of a single page. Due to preprocessing of a page a very lightly loaded system can have pages with connections that times out. If a function fails in one of the first access functions or during connect it will retry for a set number of times before it reports the error state. Usually this will be sufficient to maintain a stable interaction. If $wgShowExceptionDetails is set a stack trace will be reported when the connection fails, if unset a system message will be reported.

Identified single ticket
Basic usage is to access a ticket through the ticket number, optionally querying one or more attributes

Search for multiple tickets
Basic usage is to search for multiple tickets by adding one or more search parameters, optionally querying one or more attributes

Note: Lists will be made for some of the query parameters, and such query parameters will be split on a broken pipe character.

Both TicketGet and TicketSearch uses the same attribute reporting mechanism.

Listing queues
Basic usage is to list all queues, optionally querying one or more attributes

Presentation
A number of arguments can be given to the parser functions that changes the presentation. Defaults are system messages that are overridden by named parameters. If the format is for complex presentation, it will not use the dataseparator and the attribute names will be included. If the format is for simple presentation, it will only use the dataseparator and no attribute names.

A standardized form is used in the message namespace; MediaWiki:otrs-function-parameter. Available parameters are


 * format – A comma-separated string of six items; the head of the containing list, the head of the ticket, the head of the attribute, the tail of the attribute, the tail of the ticket and the tail of the containing list. Defaults to definitions to make a table of tickets listed vertically, and attributes listed horizontally.
 * header – A comma-separated string of four items; the head of the containing list, the head of the attribute, the tail of the attribute and the tail of the containing list. Defaults to definitions to make a table row of table head elements listed horizontally in a table row.

Installation
First you need an up and running OTRS installation. Then you must enable the SOAP interface, and set up the SOAP user and password


 * 1) Login into your existing OTRS Installation as Admin
 * 2) In the Menu Admin→Sysconfig set Group to Framework and click show
 * 3) In the list of subgroups click Core::SOAP
 * 4) Check the boxes for SOAP::User and SOAP::Password and enter the values you like
 * 5) Click update

The usual: Copy OtrsTicket.php and OtrsTicket.i18n.php to a subfolder OtrsTicket in the extensions folder, then add the following to LocalSettings.php require_once( "$IP/extensions/OtrsTicket/OtrsTicket.php");

Additionally there should be defined access to the OTRS-systems in the LocalSettins.php -file. Add the following, with adaptions $wgOtrsSites['identifier']['url'] = 'http://example.com'; $wgOtrsSites['identifier']['user'] = 'username'; $wgOtrsSites['identifier']['pass'] = 'password';

This is the minimum to make a workable interface. Usually you will set the user name to soap or something similar, this should be similar to point 4 above. Use the assigned password. The url is usually somewhat different, depending on rewrite rules and domain name. It should contain the url down to and including the script rpc.pl as this is the accesspoint for the SOAP interface.

There are some optional additions. First there is the identifier for the user the SOAP interface queries. This defaults to the root user, that is user number one (1). Because we go to great length to limit the possible interaction with the OTRS system it should not be a to big risk, yet you may want to change this to something different. The choosen user must have sufficient rights to display the actual data. $wgOtrsSites['identifier']['userid'] = 1234;

The second option that is usually necessary is to turn of caching. It is very difficult, if not impossible, to estimate when the external OTRS system changes states. Turn of caching for the pages where you use the parser functions. $wgOtrsSites['identifier']['nocache'] = true;

Usually the OTRS system uses character encoding from the isolatin-sets, typically ISO-8859-15 or similar. Mediawiki usually uses Unicode, typically UTF-8. Set the encoding for the OTRS-system, encoding of Mediawiki itself is readilly available from the code itself. $wgOtrsSites['demo']['encoding'] = 'ISO-8859-15';

Note that any additional access policy not turned on by default must be explicitly turned on to be made available $wgOtrsSites['identifier']['foobar'] = true;

Functions
GetTicket

Security issues
Greate care should be given to define the defaults, and where defaults are set to limit access you should be very careful to override those. Especially if the OTRS-system has limited access and the wiki is open, there will be possible to leak information from the OTRS-system and out to the public through the wiki.

Only functions that has a limited read only access in the system should be implemented. The interface to those functions should be implemented in such a way as to carefully clean the parameters before they are passed on, usually by cleaning them through use of regexps. This is a Best Practices when it comes to cleaning user entered data in such systems.

Bugs/Todo

 * Some code should be refactored