Unix Server Tech Knowledge Base

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== E-Mail Integration ======

OpenProject can check an e-mail account for specially formatted mail that will perform tasks within the system. This is described in https://docs.openproject.org/installation-and-operations/configuration/incoming-emails/, though some of the stuff is not quite clear, so I'm adding notes here.

First, create an e-mail account someplace. I create two folders on the mail account, one named //Processed// and one named //Failed//.

Now OpenProject to check that account by running a cron job. It was easier for me to just create a bash script to do it since the command is fairly long. It also allows me to test the system easily.

<code bash openProject>
#! /bin/bash

openproject run bundle exec rake --trace redmine:email:receive_imap \
   host='mail.example.org'\
   username='projects@example.org' \
   password='reallyG00D_Password?' \
   port=993 \
   ssl=true \
   allow_override=type,project \
   project=test_project \
   folder=INBOX \
   move_on_success=Processed \
   move_on_failure=Failed
</code>

What this code does is logs into mail.example.org with username projects@example.org and the password, and checks for e-mail. If no project is defined in the e-mail, it assigns the ticket to the project //test_project//.

If the e-mail is successfully parsed, the actions are taken and the e-mail is moved to the //Processed// folder on the mail server. If not, it is put in the //Failed// folder.

Run the script one time to verify you get no errors. You may get a warning that the hook was registered, but that is normal. Note that the script takes several seconds to run, so don't get impatient.

If you get no errors, you can either put it someplace and set up the crontab, or (on Debian based systems), put it in /etc/cron.hourly. I only wanted it to run once an hour, so I did the latter.

The format of the e-mail is very important. One thing that messed me up was the Project: field. It is **not** the name of the project, but is the project ID.

Some special things in the e-mail are used:
  - **From**: The address the e-mail comes from **must** match an existing user in OpenProject. This becomes the creator of the ticket.
  - **Subject**: The subject of the e-mail becomes the title of the ticket
  - **CC**: Anyone CC'd on the e-mail becomes a watcher on the task, assuming they are in the OpenProject instance
  - **Attachments**: If you create or update a work package via e-mail, and it has an attachment, those attachments are attached to the work package.

I'm not going to describe all of the keys (see Format of the emails in the docs link above), just the ones I care about. These will be put in the body of the e-mail,, one to a line, with a colon separating the keyword and the value. Anything not parsed this way becomes the body of the ticket.

^ Keyword ^ Value ^ Notes ^ Example ^
| Project | Project ID | This is NOT the project name. See * | Project: build-something |
| Assignee | email or login | Must be a valid user for the project | Assignee: rod |
| Type     | Type of ticket | See available types for a Work Package * | Type: Bug |
| Start Date | Date it should start | | Start Date: 2015-02-28 |
| Due Date | Date required | | Due Date: 2015-03-01 |
| Done Ratio | an integer | This is the percentage accomplished | Done Ratio: 40 |
| Status | Status | See available statuses | Status: new |
| Priority | Priority | See available priorities | Priority: Normal |

* You can find a project ID by opening a project in OpenProject and looking at the URL. It is the last section of the URL after the word projects, ie https://project.example.com/projects/keyword-here/. You can also see it by going into Project Settings | Information, where it is listed as Identifier.