Redmine

[[FrGuide]]

h1. Recevoir des courriels

{{>toc}}

Depuis la version 0.8, Redmine peut être configuré pour créer des demandes ou des commentaires directement par courriels.

h2. Mise en oeuvre

Vous pouvez configurer Redmine pour recevoir des courriels avec une des méthodes suivantes :

* Adresser des messages à partir de votre serveur de messagerie

** Distant: Fonctionne avec un serveur de messagerie distant, les courriels sont traitées immédiatement, rapide (pas d'environnement à redémarrer)

** Local: Nécessite quelques configuration sur votre serveur de messagerie local (ex. Postfix sendmail, etc.)

* Récupérer les courriels depuis un serveur IMAP ou POP3 :

** Distant: Facile à mettre en oeuvre, ne nécessite pas de configurer le MTA, fonctionne avec un serveur de messagerie distant

** Local: Le traitement n'est pas réalisé instantanément (un cron doit être ajouter pour lire périodiquement les courriels)  

h3. Adresser des courriels à partir de votre serveur de messagerie

Un script autonome peut être utilisé pour transmettre des courriels entrants à partir de votre serveur de messagerie.

Ce script lit un flux de courriel depuis l'entrée standard et le transmet à Redmine via une requête HTTP.

Le fichier est accessible depuis le répertoire de redmine: @extra/mail_handler/rdm-mailhandler.rb@.

Pour pouvoir l'utiliser, vous devez activer l'API qui reçoit les courriels:

Aller dans > Administration > Configuration > Emails entrants, vérifier que la fonction *Activer le WS pour la réception d'emails* est bien cocher et saisir ou générer une clé secrète

copier le fichier @rdm-mailhandler.rb@ sur votre serveur de messagerie, vérifier qu'il possède les permissions pour s'exécuter et configurer le serveur de messagerie

Usage:

<pre>

rdm-mailhandler [options] --url=<Redmine URL> --key=<API key>

Required:

  -u, --url                      URL of the Redmine server

  -k, --key                      Redmine API key

General options:

  -h, --help                     show this help

  -v, --verbose                  show extra information

  -V, --version                  show version information and exit

Issue attributes control options:

  -p, --project=PROJECT          identifier of the target project

  -t, --tracker=TRACKER          name of the target tracker

      --category=CATEGORY        name of the target category

      --priority=PRIORITY        name of the target priority

  -o, --allow-override=ATTRS     allow email content to override attributes

                                 specified by previous options

                                 ATTRS is a comma separated list of attributes

</pre>

Exemples:

<pre>

  # No project specified. Emails MUST contain the 'Project' keyword:

  rdm-mailhandler --url http://redmine.domain.foo --key secret

  # Fixed project and default tracker specified, but emails can override

  # both tracker and priority attributes:

  rdm-mailhandler --url https://domain.foo/redmine --key secret \\

                  --project foo \\

                  --tracker bug \\

                  --allow-override tracker,priority

</pre>

Ici un exemple pour les aliais Postfix:

<pre>

foo: "|/path/to/rdm-mailhandler.rb --url http://redmine.domain --key secret --project foo"

</pre> 

h3. Récupérer les courriels depuis un serveur IMAP

Une tâche rake (@redmine:email:receive_imap@) peut être utilisée pour récupérer les courriels depuis un serveur IMAP. Quand vous exécutez la commande rake depuis un cron vous pouvez ajouter l'option  @-f /path/to/redmine/appdir/Rakefile@ dans la commande, faute de quoi le fichier rake n'est pas trouvé. Voici un exemple de ligne pour un fichier cron qui récupère les courriels toutes les 30mn.

<code>

*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx 

</code>

Cette ligne peut être ajouté sur une seule dans votre fichier cron. Vous pouvez aussi consulter d'autres exemple à la suite, qui montre les commandes rake sans l'option @-f@ et sans la partie cron 

Il est nécessaire d'avoir configurer le firewall pour laisser sortir les connexion TCP pour le port IMAP 143. 

Options IMAP disponibles:

<pre>

  host=HOST                IMAP server host (default: 127.0.0.1)

  port=PORT                IMAP server port (default: 143)

  ssl=SSL                  Use SSL? (default: false)

  username=USERNAME        IMAP account

  password=PASSWORD        IMAP password

  folder=FOLDER            IMAP folder to read (default: INBOX)

  move_on_success=MAILBOX  move emails that were successfully received

                           to MAILBOX instead of deleting them

  move_on_failure=MAILBOX  move emails that were ignored to MAILBOX

</pre>

Options de contrôles des attributs des demandes:

<pre>

  project=PROJECT          identifier of the target project

  tracker=TRACKER          name of the target tracker

  category=CATEGORY        name of the target category

  priority=PRIORITY        name of the target priority

  allow_override=ATTRS     allow email content to override attributes

                           specified by previous options

                           ATTRS is a comma separated list of attributes

</pre>

Exemples de commandes rake:

<pre>

  # No project specified. Emails MUST contain the 'Project' keyword:

  rake redmine:email:receive_imap RAILS_ENV="production" \\

    host=imap.foo.bar username=redmine@somenet.foo password=xxx

  # Fixed project and default tracker specified, but emails can override

  # both tracker and priority attributes:

  rake redmine:email:receive_imap RAILS_ENV="production" \\

    host=imap.foo.bar username=redmine@somenet.foo password=xxx ssl=1 \\

    project=foo \\

    tracker=bug \\

    allow_override=tracker,priority

  # Move successful emails to the 'read' mailbox and failed emails to

  # the 'failed' mailbox

  rake redmine:email:receive_imap RAILS_ENV="production" \\

    host=imap.foo.bar username=redmine@somenet.foo password=xxx \\

    move_on_success=read move_on_failure=failed

</pre>