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

Arguments
The function takes two anonymous arguments. The first one specify the OTRS system to use, and the second one specify the ticket number. There may be a third optional anonymous argument, DEBUG. That argument will make the first external call after sign on tho dump the XML response. Any remaining anonymous parameters will be used as a filter for reported attributes.

In addition to arguments for specification of the query and filtering the output, the function has a few named parameters for adapting the formating.
 * format – 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 of tickets listed vertically, and attributes listed horizontally.

For filter parameters, see the system documentation for the member function TicketGet in Kernel::System::Ticket.

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.

Arguments
The function takes one anonymous arguments. That one specify the OTRS system to use. There may be a second optional anonymous argument, DEBUG. That argument will make the first external call after sign on tho dump the XML response. Any remaining anonymous parameters will be used as a filter for reported attributes.

In addition to arguments for specification of the query and filtering the output, the function has a few named parameters for adapting the formating.
 * 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.

For filter parameters, see the system documentation for the member function TicketGet in Kernel::System::Ticket. For query parameters, see the system documentation for the member function TicketSearch in Kernel::System::Ticket.

Listing queues
Basic usage is to list all queues, optionally querying one or more attributes Note: This function is not available.

For filter parameters, see the system documentation for the member function GetAllQueues in Kernel::System::Queue.

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;

Security issues
Defaults should be defined with greate care, and where defaults are set to limit access you should be very careful to override those. If the OTRS-system has some kind of restricted access and the wiki is open, then there will leak information from the OTRS-system and out to the public through the wiki.

Even if it is possible, and tempting, to implement some kind of read-write functionality, only functions that is limited to read only access should be implemented. A crowdsourcing project has naturally less stringent rules for participation, while a ticket reporting system has a lot more stringent rules. If functions are made that can write to the OTRS system, then 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 how it is done for the read only functions and is a Best Practices when it comes to cleaning user entered data in such systems.

Bugs/Todo

 * Some code should be refactored
 * The parser function GetAllQueues is not implemented yet