Import OTRS documentation
[doc-infra.git] / doc / otrs.rst
CommitLineData
258e5acc
NI
1OTRS
2====
3
4OTRS est le système utilisé pour gérer les mails envoyés à notre équipe de support.
5
6Installation
7------------
8
9On commence en installant le paquet debian ``otrs2``. Ensuite, il faudra probablement copier la base de données pour ne pas perdre l'historique des tickets traités.
10
11Ensuite, on s'amuse :
12
13Configuration
14Il y a deux fichiers fondamentaux :
15
16* ``/usr/share/otrs/Kernel/Config.pm``
17* ``/usr/share/otrs/.procmailrc``
18
19Le premier sert à faire toute la configuration du service, dès les mots de passes aux adresses mail, passant par l'encodage des données.
20
21Le deuxième nous sert pour filtrer les mails à destination d'OTRS selon leur provenance, ce qui permet de les placer dans des queues de support différentes selon qu'ils ont été envoyés à ``contact@``, ``support@`` ou ``tresorier@``.
22
23Vérifier que le site est en mode sécurisé
24~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
25
26Théoriquement, avoir la variable
27::
28
29 $Self->{'SecureMode'} = 1;
30
31dans le fichier ``/etc/otrs/Kernel/Config.pm`` suffit à mettre le site en mode sécurisé (c'est à dire, empêcher l'utilisation de l'installateur web, ce qui risque d'écraser les données pré-existantes).
32
33Pour vérifier que le site est en mode sécurisé, il suffit de regarder la page http://support.polytechnique.org/otrs/installer.pl, et si elle ne donne pas d'erreur, c'est parce que le site n'est pas sécurisé et n'importe qui peut détruire notre BDD...
34
35Mail de sortie avec BCC hotliners
36~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37
38Pour que toute l'équipe soit au courant des mails qu'un membre du support envoie via OTRS, nous effectuons un BCC vers ``hotliners@staff``. Comme il ne faut pas que les autres mails d'OTRS (différentes actions sur des tickets, l'arrivée des tickets qui notifie les abonnés) soient aussi copiés vers hotliners (pour éviter de flooder les support-men), on ne peut pas utiliser la variable ``SendmailBcc`` que propose OTRS.
39
40Pour avoir le comportement désiré il est donc nécessaire de changer le fichier ``/usr/share/otrs/Kernel/System/Ticket/Article.pm``, à la fonction ``ArticleSend()`` n'importe où après que ``$Param{Bcc}`` ait été récupéré, et avant l'envoi du mail (via ``SendmailObject->Send()``::
41
42 1548a1551
43 > if ($Self->{ConfigObject}->{XorgBcc}) {
44 > $Param{Bcc} = "$Self->{ConfigObject}->{XorgBcc}, ".$Param{Bcc};
45 > }
46
47et d'ajouter la nouvelle variable dans ``/etc/otrs/Kernel/Config.pm``::
48
49 $Self->{'XorgBcc'} = 'hotliners@staff.polytechnique.org';
50
51Problème avec le cron ``otrs.cleanup``
52
53Message d'erreur typique dans le cron::
54
55 Sujet: Cron <otrs@svoboda> [ -x $HOME/bin/otrs.cleanup ] && $HOME/bin/otrs.cleanup > /d[..]
56 cat: /usr/share/otrs/var/spool/bounces: Is a directory
57 cat: /usr/share/otrs/var/spool/spam: Is a directory
58
59Pour corriger cela, il suffit de changer ``/usr/share/otrs/bin/otrs.cleanup`` ::
60
61 34c34
62 < for i in $OTRS_SPOOLDIR/* ; do
63 ---
64 > for i in `find $OTRS_SPOOLDIR -type f` ; do
65
66pour que ce script trouve les bons fichiers.
67Cela est dû à notre configuration procmail, peut-être qu'en la changeant vers une mbox et non des maildirs on n'aurait plus ce problème.
68
69OTRS n'arrive pas à lire des mails avec un Content-type mal défini
70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
72Si on regarde ``/usr/share/otrs/var/spool/``, on peut trouver des fois des messages qui n'ont pas été
73délivrées à OTRS lorsque le script ``/usr/share/otrs/bin/otrs.cleanup`` est lancé (par un cron).
74
75Cela se traduit par::
76
77 otrs@svoboda: ~ % bin/otrs.cleanup
78 Checking otrs spool dir...
79 Starting otrs PostMaster... (/usr/share/otrs/var/spool/2) failed.
80
81À une époque, nous laissions ces mails dans le ``[...]/spool`` sans jamais s'en occuper, en supposant qu'il n'y avait que du spam. Cette position a été changée, il faut donc corriger le Content-type mal formé de ces mails (par exemple on avait *Content-type: text/html; charset= iso-8859-1* pour un des mails que posaient un problème) pour retirer une espace superflue qui trouble l'interpréteur d'OTRS. On fait alors ::
82
83 ``/usr/share/otrs/bin/otrs.cleanup``
84 38c38
85 < if cat $i | $OTRS_POSTMASTER >> /dev/null 2>&1; then
86 ---
87 > if sed -e "s/\(Content-type: .*charset=\) \(.*\)/\1\2/" $i | $OTRS_POSTMASTER >> /dev/null 2>&1; then
88
89Récupération après une panne d'OTRS
90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92Pendant une panne d'OTRS, les messages ne sont pas acheminés entre Postfix et OTRS. Plus exactement, procmail peut échouer à exécuter ``/usr/share/otrs/bin/otrs.PostMaster.pl``. Dans ce cas, ``/usr/share/otrs/.procmailrc`` indique de transmettre les messages dans ``$SYS_HOME/var/spool/.``, c'est à dire ``/var/lib/otrs/spool/{1,2,3,...}``. Pour récupérer ces messages, il suffit d'exécuter à la main ``otrs.cleanup`` ou de faire une boucle sur les message en les donnant à ``otrs.PostMaster``.
93
94crons
95~~~~~
96
97TODO : en gros, les crons de récupération mail peuvent être omis puisqu'on utilise procmail.
98
99Enlever le pop-up de confirmation qu'un ticket a été sélectionné pour une action groupée
100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101
102Comme il est très utile de pouvoir utiliser des actions groupées pour fermer les spams, et il est très peu productif de, à chaque fois qu'un ticket est sélectionné pour une action groupée, devoir fermer une boîte que te l'informe, il est essentiel de pouvoir demander à OTRS de ne pas montrer cela.
103
104Pour le faire il, on ajoute à ``/etc/otrs/Kernel/Config.pm``::
105
106 $Self->{'Ticket::Frontend::BulkFeatureJavaScriptAlert'} = 0;
107
108Autres variables de conf
109~~~~~~~~~~~~~~~~~~~~~~~~
110
111Il faut dé-blacklister le domaine "@me", qui est utilisé par beaucoup de monde. Actuellement, il est dans ``~otrs/Kernel/Config/Files/ZZZAuto.pm``. (configuré via l'interface web)
112
113Ajouter un correcteur orthographique en français
114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115TODO
116
117À faire toujours lors d'une mise à jour
118---------------------------------------
119
120Les mises à jour d'OTRS sont plutôt compliquées parce qu'il faudra de toutes façons refaire une partie des changements du code (et le vérifier), et qu'en plus la BDD d'OTRS change souvent d'une version à l'autre. Il est donc très conseillé de se documenter (en cherchant sur Internet) sur ce qui peut se passer...
121
122Mettre à jour les bases de données
123~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124
125Lors des mises à jour de version mineure (a.b vers a.c), il est courant qu'OTRS change un peu les tables de la base de données (le plus souvent pour rajouter des colonnes avec informations supplémentaires).
126
127Un bon commencement est donc de faire un backup de la base de données OTRS, puis d'installer la nouvelle version. Ensuite, on fait tourner les scripts qui font le *DBUpdate*, en général dans ``~otrs/scripts``. Normalement, cela se passe sans problèmes. Et au pire, on a de quoi recommencer (à n'importe quelle étape de ce qui suit) !
128
129Reprendre la partie de l'installation
130~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131Lancer le site et :
132
133* Vérifier la configuration (OTRS accède à la base de données, les tickets sont là, les bulk actions, ...).
134* Vérifier que le site est en mode sécurisé
135
136Ensuite, on passe aux hacks
137
138* Tester le Bcc:hotliners (Normalement, il suffit de remettre le morceau de code dans ``Article.pm`` et vérifier que les Bcc marchent !)
139* Corriger le cron otrs.cleanup
140* Corriger les mauvais charset des Content-type
141
142Et finalement,
143
144* Relire les crons
145* Ajouter un correcteur orthographique en français
146
147
148Quelques notes de la migration 2.0.4 -> 2.2.7
149---------------------------------------------
150
151Dans la suite, on note quelques changements et vérifications que se sont avérées nécessaires lors de la dernière mise à jour d'OTRS (du 31/10/2010, version 2.0.4 -> 2.2.7), qui est venue dans le passage de etch à lenny sur svoboda.
152
153L'encodage de la BDD a changé depuis la dernière version
154~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155
156Dans la version 2.0.4 d'OTRS que nous avions, la BDD sql était UTF-8 double-encoded pour que l'interface affiche correctement les mails. Visiblement, ce "problème" a été résolu avec la nouvelle version d'OTRS, mais les scripts de mise à jour de la BDD n'ont pas corrigé cela.
157
158Pour dé-double-encoder, on a utilisé la méthode décrite dans http://www.blueboxgrp.com/news/2009/07/mysql_encoding et ça a bien marché (même si ça a pris 3h30 à le faire, en vérifiant beaucoup de choses et scriptant les commander à taper, mais les rentrant au fur et à mesure pour vérifier leur bon fonctionnement...).
159
160Erreurs de prise en compte des configurations
161~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162
163On a réussi à faire marcher les bulk actions en changeant cette option via l'interface d'administration d'OTRS (Administrateur -> Configuration Système, recherche de l'option BulkFeatureJavaScriptAlert), ce qui a écrit dans le fichier ``/usr/share/otrs/Kernel/Config/Files/ZZZAuto.pm`` la ligne que nous avions mis dans ``/etc/otrs/Kernel/Config.pm``.
164
165Le site refusait de passer en mode sécurisé, la variable dans ``Config.pm`` n'étant pas suffisante. Pour le mettre en mode sécurisé (pour de vrai !) nous avons aussi changé cette configuration dans les fichiers
166``/usr/share/otrs/Kernel/Config/Files/ZZZAuto.pm``
167``/usr/share/otrs/Kernel/Config/Defaults.pm``
168ce qui est probablement un bug d'OTRS, mais en tout cas voici des endroits où chercher.
169
170Problème avec le cron GenericAgent.pl
171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172
173Message d'erreur dans le cron::
174
175 Sujet: Cron <otrs@svoboda> test -x $HOME/bin/GenericAgent.pl && $HOME/bin/GenericAgent.[..]
176 Need Ticket::ViewableStateType in Kernel/Config.pm!
177
178Apparemment, il s'est corrigé tout seul (on n'a pas vu de message d'erreur à part une fois). Cela dit, on a rajouté la valeur conseillée de cette variable de configuration pour que les scripts de mise à jour vers la version 2.4 marchent. Il peut avoir encore des choses à vérifier...
179
180Quelques notes de la migration 2.2.7 -> 2.4.9
181---------------------------------------------
182
183Changement de la BDD
184~~~~~~~~~~~~~~~~~~~~
185
186Avec une migration OTRS il faut toujours exécuter les scripts de mise à jour de la BDD. Visiblement cela n'est pas automatiquement fait par debian, donc il faut penser de le faire à la main.
187
188Apparition du DashBoard
189~~~~~~~~~~~~~~~~~~~~~~~
190
191Avec la nouvelle version de OTRS un DashBoard a été introduit en regroupant plein d'informations. Cette page est la page par défaut juste après le login. Il est par contre plus intéressant chez nous d'arriver directement à la page pour traiter des tickets. Pour le faire il suffit de changer dans http://support.polytechnique.org/otrs/index.pl?Action=AdminSysConfig&Subaction=Edit&SysConfigSubGroup=Frontend::Agent&SysConfigGroup=Ticket&#|Options de configuration: Ticket → Frontend::Agent la valeur de ``Frontend::CommonParam###Action:`` à ``AgentTicketQueue``.
192
193
194Quelques outils
195---------------
196
197Lors de la migration 1.3 -> 2.0 d'OTRS, une certaine quantité de scripts ont été faits pour traiter la base de données ``otrs``, essentiellement pour nettoyer un peu (``flush*``) et faire la conversion des charsets (lors de 1.3, on était en latin1). Ils se trouvent dans ``svoboda:~bernardofpc/otrs2/``.