Running javascript on any OTRS Agent or Customer site

Customizing your OTRS setup with javascript is pretty easy. All you need is two files and a new folder. No need to create your own theme.

Before you go on, please do not try this on a production system, use a test system.
If you don’t have one, build one or use the OTRS Appliance.

I am using OTRS 3.3 any other version might differ from what I’m doing, so please use caution.

I’m assuming the default setup to /opt/otrs if you have modified your install path you have to adopt my paths accordingly.

First we have to create a javascript file with our custom code.
Connect to your OTRS server (via putty or so)
Create a folder called Customization (or anything you’d like) in
/opt/otrs/var/httpd/htdocs/js/thirdparty/

mkdir /opt/otrs/var/httpd/htdocs/js/thirdparty/Customization

then open your favorite text editor (I’m using vi) to create a javascript file called CustomJS.js (or whatever you want) in /opt/otrs/var/httpd/htdocs/js/thirdparty/Customization/

vi /opt/otrs/var/httpd/htdocs/js/thirdparty/Customization/CustomJS.js

To keep things simple we will just add one alert that fires when the document is fully loaded (using jquery here. otrs 3.3 comes with jquery-1.10.0, otrs 4 with jquery-1.11.1)

$( document ).ready(function() {
    alert( "ready!" );
});

Now that we have our javascript file we need to make OTRS load it, so it will execute.
Therefore we create an additional Config XML File in /opt/otrs/Kernel/Config/Files and make sure that the file has no blank lines before the opening xml tag.

vi /opt/otrs/Kernel/Config/Files/Customization.xml
<?xml version="1.0" encoding="utf-8" ?>
<otrs_config version="1.0" init="Framework">
<ConfigItem Name="Loader::Agent::CommonJS###110-Customization" Required="1" Valid="1">
    <Description Translatable="1">List of JS files for package "Customization".</Description>
    <Group>Framework</Group>
    <SubGroup>Core::Web</SubGroup>
    <Setting>
        <Array>
            <Item>thirdparty/Customization/CustomJS.js</Item>
        </Array>
    </Setting>
</ConfigItem>
<ConfigItem Name="Loader::Customer::CommonJS###110-Customization" Required="1" Valid="1">
    <Description Translatable="1">List of JS files for package "Customization".</Description>
    <Group>Framework</Group>
    <SubGroup>Core::Web</SubGroup>
    <Setting>
        <Array>
            <Item>thirdparty/Customization/CustomJS.js</Item>
        </Array>
    </Setting>
</ConfigItem>
</otrs_config>

If you choose other names for the folder or your javascript file make sure to modify the XML file!

There is a detailed description of the XML Config Options in the OTRS Developer Manual

XML Config Options: V3.3 V4
Developer Manual: V3.3 V4

Just so much, the first ConfigItem in the XML file will load the javascript for the Agent interface, the second ConfigItem will load the javascript for the Customer Interface. You could also create separate files for Agent and Customer interface depending on your use case but i will show you how to limit your javascript to certain areas in a later post.

If you move to your OTRS Agent interface now, most likely nothing will have changed.
Worst case you get an “Fatal Error”.
First you have to rebuild your Config for the new XML file to take effect.

/opt/otrs/bin/otrs.RebuildConfig.pl

Next you have to set the permissions on all files because all newly created files and folders belong to root or whatever user you were working with:

new_file_permissions

That’s not as bad as it sounds, you just have to run /opt/otrs/bin/otrs.SetPermissions.pl with the right switches depending on your setup. On mine, which is on CentOS 6.6 and follows all the recommendations in the install guide, it is:

/opt/otrs/bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=apache --otrs-group=apache --web-group=apache /opt/otrs

But please consult the manual before running my version.
Here’s it for 3.3 it has changed for OTRS 4.

bin/otrs.SetPermissions.pl - set OTRS file permissions
Copyright (C) 2001-2014 OTRS AG, http://otrs.com/
Usage: otrs.SetPermissions.pl
    [--otrs-user=]
    [--web-user=]
    [--otrs-group=]
    [--web-group=]
    [--admin-user=]
    [--admin-group=]
    [--admin-group-writable]
    [--secure]  (paranoid mode: all files readonly, does not work with PackageManager)
    [--not-root]
    
with the permissions needed for your system setup. For example:

- Web server which runs as the OTRS user:
        shell> bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=otrs /opt/otrs

- Webserver with wwwrun user (e. g. SUSE):
        shell> bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=wwwrun /opt/otrs

- Webserver with apache user (e. g. Red Hat, CentOS):
        shell> bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=apache --otrs-group=apache --web-group=apache /opt/otrs

- Webserver with www-data user (e. g. Debian, Ubuntu):
        shell> bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=www-data --otrs-group=www-data --web-group=www-data /opt/otr

Now you can go and check for the alert, it should pop up on every site of your OTRS system.

1 thought on “Running javascript on any OTRS Agent or Customer site

  1. Pingback: Targeting custom javascript to specific areas of the OTRS Agent or Customer Interface | stephan14x

Comments are closed.