RusRedmineReceivingEmails » History » Version 7

Михаил Галац, 2016-11-25 21:56

1 2 Denis Savitskiy
[RusRedmineReceivingEmails[Получение писем]]
2 1 Denis Savitskiy
3 1 Denis Savitskiy
{{>toc}}
4 1 Denis Savitskiy
5 1 Denis Savitskiy
Начиная с версии 0.8.0, Redmine можно настроить на создание и комментирование задач с помощью email.
6 1 Denis Savitskiy
7 1 Denis Savitskiy
h2. Настройка
8 1 Denis Savitskiy
9 1 Denis Savitskiy
Вы можете настроить Redmine для получения электронной почты одним из следующих способов:
10 1 Denis Savitskiy
11 1 Denis Savitskiy
* Пересылка электронных писем с вашего почтового сервера:
12 1 Denis Savitskiy
13 1 Denis Savitskiy
* Плюсы: работает с удаленнми почтовыми серверами, письма обрабатываются мгновенно, быстро (никакой перезагрузки окружения)
14 1 Denis Savitskiy
* Минусы: требует некоторых настроек агента передачи почты (например: Postfix, Sendmail...)
15 1 Denis Savitskiy
16 1 Denis Savitskiy
* Сбор почты с IMAP или POP3-сервера:
17 1 Denis Savitskiy
18 1 Denis Savitskiy
* Плюсы: простота установки, не нужно сконфигурировать MTA, работает с удаленного почтового сервера
19 3 Denis Savitskiy
* Минусы: письма не обрабатываются мгновенно (должны быть добавлены cron-задания для регулярного получения электронной почты)
20 1 Denis Savitskiy
21 3 Denis Savitskiy
* Чтение электронных писем из стандартного потока ввода:
22 1 Denis Savitskiy
23 1 Denis Savitskiy
* Плюсы: удобно для тестирования
24 3 Denis Savitskiy
* Минусы: низкая скорость работы (происходит перезагрузка окружения каждый раз, когда открывается письмо), нуждается в некоторой конфигурации вашего MTA
25 1 Denis Savitskiy
26 1 Denis Savitskiy
h3. Отправление писем с сервера
27 1 Denis Savitskiy
28 1 Denis Savitskiy
Отдельный скрипт можно использовать для переадресации входящих электронных писем с вашего почтового сервера.
29 1 Denis Savitskiy
Этот скрипт читает необработанные письма со стандартного ввода и направляет их в Redmine через HTTP-запрос.
30 3 Denis Savitskiy
Он находится в каталоге redmine: @extra/mail_handler/rdm-mailhandler.rb@.
31 1 Denis Savitskiy
32 3 Denis Savitskiy
Чтобы его использовать, необходимо включить API для получения сообщений электронной почты:
33 3 Denis Savitskiy
Зайдите в _Настройки_ -> _Приём сообщений_, поставьте флажок на *Включить веб-сервис для входящих сообщений* и введите (или сгенерируйте) API ключ.
34 1 Denis Savitskiy
35 3 Denis Savitskiy
Скопируйте @rdm-mailhandler.rb@ на ваш почтовый сервер и убедитесь в том, что он является исполненяемым, затем настройте MTA.
36 1 Denis Savitskiy
37 1 Denis Savitskiy
Использование:
38 1 Denis Savitskiy
39 1 Denis Savitskiy
<pre>
40 1 Denis Savitskiy
rdm-mailhandler [options] --url=<Redmine URL> --key=<API ключ>
41 1 Denis Savitskiy
42 1 Denis Savitskiy
Обязательные:
43 1 Denis Savitskiy
  -u, --url                      URL сервера Redmine
44 1 Denis Savitskiy
  -k, --key                      Redmine API ключ
45 1 Denis Savitskiy
  
46 1 Denis Savitskiy
Общие:
47 1 Denis Savitskiy
  -h, --help                     помощь
48 1 Denis Savitskiy
  -v, --verbose                  экстра информация
49 1 Denis Savitskiy
  -V, --version                  информация о версии
50 1 Denis Savitskiy
51 1 Denis Savitskiy
Опции управления атрибутами задачи:
52 1 Denis Savitskiy
  -p, --project=PROJECT          идентификатор проекта
53 1 Denis Savitskiy
  -t, --tracker=TRACKER          трекер задачи
54 1 Denis Savitskiy
      --category=CATEGORY        категория задачи
55 1 Denis Savitskiy
      --priority=PRIORITY        приоритет задачи
56 1 Denis Savitskiy
  -o, --allow-override=ATTRS     разрешить содержимому письма переопределять
57 1 Denis Savitskiy
                                 атрибуты, определённые ранее,
58 1 Denis Savitskiy
                                 ATTRS - список атрибутов, разделённых запятой
59 1 Denis Savitskiy
</pre>
60 1 Denis Savitskiy
61 1 Denis Savitskiy
Примеры:
62 1 Denis Savitskiy
63 1 Denis Savitskiy
<pre>
64 1 Denis Savitskiy
  # Нет определённого проекта. Письма ДОЛЖНЫ содержать ключ 'Project':
65 1 Denis Savitskiy
  rdm-mailhandler --url http://redmine.domain.foo --key secret
66 1 Denis Savitskiy
  
67 1 Denis Savitskiy
  # Проект и стандартный трекер определены, но письма могут переопределять 
68 1 Denis Savitskiy
  # оба атрибута:
69 1 Denis Savitskiy
  rdm-mailhandler --url https://domain.foo/redmine --key secret \\
70 1 Denis Savitskiy
                  --project foo \\
71 1 Denis Savitskiy
                  --tracker bug \\
72 1 Denis Savitskiy
                  --allow-override tracker,priority
73 1 Denis Savitskiy
</pre>
74 1 Denis Savitskiy
75 2 Denis Savitskiy
Пример Postfix алиаса (обычно задаётся в @/etc/aliases@):
76 1 Denis Savitskiy
77 1 Denis Savitskiy
<pre>
78 1 Denis Savitskiy
foo: "|/путь/к/rdm-mailhandler.rb --url http://redmine.domain --key secret --project foo"
79 2 Denis Savitskiy
</pre>
80 1 Denis Savitskiy
81 1 Denis Savitskiy
Если ваш домен настроен как виртуальный почтовик (то есть вы используете /etc/postfix/virtual_mailbox_maps для распределения в форме @ user@example.com /path/example.com/user@), вам следует:
82 1 Denis Savitskiy
83 1 Denis Savitskiy
* создать маппер в @ /etc/virtual@ как: @ foo@example.org foo@
84 2 Denis Savitskiy
* изменить @/etc/postfix/main.cf@ для использования транспортного файла: @transport_maps = hash:/etc/postfix/transport@
85 2 Denis Savitskiy
* внутри транспорта добавить строчку такого вида: @ foo@example.org local:@
86 1 Denis Savitskiy
87 3 Denis Savitskiy
*Объяснение:* - Когда вы определяете маршруты виртуального почтовика для домена, как стандартные, что значит - указали алиса в @/etc/postfix/virtual@ даст сбой (сославшись на "unknown user"). Чтобы это решить,нужно переписать стандатрный транспорт, определив внутренний траспорт в запросе к письму(?).
88 1 Denis Savitskiy
89 2 Denis Savitskiy
Front-end для rdm-mailhandler.rb был написан чтобы разрешить указание проектов через часть адреса (name+project@example.com). Смотри [[MailhandlerSubAddress]]
90 1 Denis Savitskiy
91 3 Denis Savitskiy
h3. Получение писем с IMAP сервера
92 1 Denis Savitskiy
93 3 Denis Savitskiy
Rake задача (@redmine:email:receive_imap@) используется для получения входящих сообщений с IMAP сервера. Когда вы запускаете rake команду из cron'а, вы должны добавить ключ @-f /путь/к/директории/redmine/Rakefile@ rake команде, иначе она не будет найдена. Вот пример строки cron файла, которая задаёт получение писем каждые 30 минут:
94 1 Denis Savitskiy
95 6 Denis Savitskiy
<pre>
96 1 Denis Savitskiy
*/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 
97 6 Denis Savitskiy
</pre>
98 1 Denis Savitskiy
99 3 Denis Savitskiy
Если ваши установки работают, но вы также получаете вывод cron daemon'a, вы можете удалить вывод из rake команды добавив ключ "--silent". Это предотвратит отправку сообщений cron'ом при каждом запуске команды.
100 1 Denis Savitskiy
101 6 Denis Savitskiy
<pre>
102 1 Denis Savitskiy
*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile --silent redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx 
103 6 Denis Savitskiy
</pre>
104 1 Denis Savitskiy
105 1 Denis Savitskiy
The command has to go on a single line in your cronfile. Also see the other examples below, which only show the rake commands without the @-f@ option and without the cron part. 
106 1 Denis Savitskiy
107 1 Denis Savitskiy
For Windows as server "pycron":http://www.kalab.com/freeware/pycron/pycron.htm can be used to schedule a fetch task.
108 1 Denis Savitskiy
109 1 Denis Savitskiy
It can be necessary that you open the firewall on the machine for outgoing TCP connections to IMAP port 143.
110 1 Denis Savitskiy
111 1 Denis Savitskiy
Available IMAP options:
112 1 Denis Savitskiy
<pre>
113 1 Denis Savitskiy
  host=HOST                IMAP server host (default: 127.0.0.1)
114 1 Denis Savitskiy
  port=PORT                IMAP server port (default: 143)
115 1 Denis Savitskiy
  ssl=SSL                  Use SSL? (default: false)
116 1 Denis Savitskiy
  username=USERNAME        IMAP account
117 1 Denis Savitskiy
  password=PASSWORD        IMAP password
118 1 Denis Savitskiy
  folder=FOLDER            IMAP folder to read (default: INBOX)
119 1 Denis Savitskiy
  move_on_success=MAILBOX  move emails that were successfully received
120 1 Denis Savitskiy
                           to MAILBOX instead of deleting them
121 1 Denis Savitskiy
  move_on_failure=MAILBOX  move emails that were ignored to MAILBOX
122 1 Denis Savitskiy
</pre>
123 1 Denis Savitskiy
124 1 Denis Savitskiy
Issue attributes control options:
125 1 Denis Savitskiy
<pre>
126 1 Denis Savitskiy
  project=PROJECT          identifier of the target project
127 1 Denis Savitskiy
  tracker=TRACKER          name of the target tracker
128 1 Denis Savitskiy
  category=CATEGORY        name of the target category
129 1 Denis Savitskiy
  priority=PRIORITY        name of the target priority
130 1 Denis Savitskiy
  allow_override=ATTRS     allow email content to override attributes
131 1 Denis Savitskiy
                           specified by previous options
132 1 Denis Savitskiy
                           ATTRS is a comma separated list of attributes
133 1 Denis Savitskiy
</pre>
134 1 Denis Savitskiy
135 1 Denis Savitskiy
Примеры для rake команды:
136 1 Denis Savitskiy
137 1 Denis Savitskiy
<pre>
138 1 Denis Savitskiy
  # No project specified. Emails MUST contain the 'Project' keyword:
139 1 Denis Savitskiy
  
140 1 Denis Savitskiy
  rake redmine:email:receive_imap RAILS_ENV="production" \\
141 1 Denis Savitskiy
    host=imap.foo.bar username=redmine@somenet.foo password=xxx
142 1 Denis Savitskiy
143 1 Denis Savitskiy
144 1 Denis Savitskiy
  # Fixed project and default tracker specified, but emails can override
145 1 Denis Savitskiy
  # both tracker and priority attributes:
146 1 Denis Savitskiy
  
147 1 Denis Savitskiy
  rake redmine:email:receive_imap RAILS_ENV="production" \\
148 1 Denis Savitskiy
    host=imap.foo.bar username=redmine@somenet.foo password=xxx ssl=1 \\
149 1 Denis Savitskiy
    project=foo \\
150 1 Denis Savitskiy
    tracker=bug \\
151 1 Denis Savitskiy
    allow_override=tracker,priority
152 1 Denis Savitskiy
153 1 Denis Savitskiy
  # Move successful emails to the 'read' mailbox and failed emails to
154 1 Denis Savitskiy
  # the 'failed' mailbox
155 1 Denis Savitskiy
  
156 1 Denis Savitskiy
  rake redmine:email:receive_imap RAILS_ENV="production" \\
157 1 Denis Savitskiy
    host=imap.foo.bar username=redmine@somenet.foo password=xxx \\
158 1 Denis Savitskiy
    move_on_success=read move_on_failure=failed
159 1 Denis Savitskiy
160 1 Denis Savitskiy
</pre>
161 1 Denis Savitskiy
162 1 Denis Savitskiy
163 1 Denis Savitskiy
Ignored emails are marked as 'Seen' but are not deleted from the IMAP server--these include unknown user, unknown project and emails from the redmine emission account.
164 1 Denis Savitskiy
165 1 Denis Savitskiy
The option _allow_override_ is not only for overriding default values given to rake, but for every attribute in a mail. If you want to override the tracker in your mail you have to add _allow_override=tracker_ as parameter.
166 1 Denis Savitskiy
167 4 Alex Madyarov
h3. Получение писем с POP3 сервера
168 1 Denis Savitskiy
169 1 Denis Savitskiy
_Only available in trunk and future 1.0._
170 1 Denis Savitskiy
171 1 Denis Savitskiy
A rake task (@redmine:email:receive_pop3@) can be used to fetch incoming emails from a POP3 server.
172 1 Denis Savitskiy
173 1 Denis Savitskiy
Доступные опции POP3:
174 1 Denis Savitskiy
<pre>
175 1 Denis Savitskiy
  host=HOST                POP3 server host (default: 127.0.0.1)
176 1 Denis Savitskiy
  port=PORT                POP3 server port (default: 110)
177 1 Denis Savitskiy
  username=USERNAME        POP3 account
178 1 Denis Savitskiy
  password=PASSWORD        POP3 password
179 1 Denis Savitskiy
  apop=1                   use APOP authentication (default: false)
180 1 Denis Savitskiy
  delete_unprocessed=1     delete messages that could not be processed
181 1 Denis Savitskiy
                           successfully from the server (default
182 1 Denis Savitskiy
                           behaviour is to leave them on the server)
183 1 Denis Savitskiy
</pre>
184 1 Denis Savitskiy
185 1 Denis Savitskiy
See the IMAP rake task above for issue attributes control options.
186 1 Denis Savitskiy
187 1 Denis Savitskiy
h3. Чтение писем со стандартного ввода
188 1 Denis Savitskiy
189 1 Denis Savitskiy
A rake task (@redmine:email:receive@) can be used to read a single raw email from the standard input.
190 1 Denis Savitskiy
191 1 Denis Savitskiy
<pre>
192 1 Denis Savitskiy
Issue attributes control options:
193 1 Denis Savitskiy
  project=PROJECT          identifier of the target project
194 1 Denis Savitskiy
  tracker=TRACKER          name of the target tracker
195 1 Denis Savitskiy
  category=CATEGORY        name of the target category
196 1 Denis Savitskiy
  priority=PRIORITY        name of the target priority
197 1 Denis Savitskiy
  allow_override=ATTRS     allow email content to override attributes
198 1 Denis Savitskiy
                           specified by previous options
199 1 Denis Savitskiy
                           ATTRS is a comma separated list of attributes
200 1 Denis Savitskiy
</pre>
201 1 Denis Savitskiy
202 1 Denis Savitskiy
Примеры:
203 1 Denis Savitskiy
204 1 Denis Savitskiy
<pre>
205 1 Denis Savitskiy
  # No project specified. Emails MUST contain the 'Project' keyword:
206 1 Denis Savitskiy
  rake redmine:email:read RAILS_ENV="production" < raw_email
207 1 Denis Savitskiy
208 1 Denis Savitskiy
  # Fixed project and default tracker specified, but emails can override
209 1 Denis Savitskiy
  # both tracker and priority attributes:
210 1 Denis Savitskiy
  rake redmine:email:read RAILS_ENV="production" \\
211 1 Denis Savitskiy
                  project=foo \\
212 1 Denis Savitskiy
                  tracker=bug \\
213 1 Denis Savitskiy
                  allow_override=tracker,priority < raw_email
214 1 Denis Savitskiy
</pre>
215 1 Denis Savitskiy
216 1 Denis Savitskiy
The option _allow_override_ is not only for overriding default values given to rake, but for every attribute in a mail. If you want to override the tracker in your mail you have to add _allow_override=tracker_ as parameter.
217 1 Denis Savitskiy
218 1 Denis Savitskiy
h3. Разрешение анонимным пользоваателям создавать задачи с помощью email
219 1 Denis Savitskiy
220 1 Denis Savitskiy
In order to enable this option, extra parameters have to be included.
221 1 Denis Savitskiy
222 1 Denis Savitskiy
<pre>
223 1 Denis Savitskiy
unknown_user=ACTION     how to handle emails from an unknown user ACTION can be one of the following values:
224 1 Denis Savitskiy
                        ignore: email is ignored (default)
225 1 Denis Savitskiy
                        accept: accept as anonymous user
226 1 Denis Savitskiy
                        create: create a user account
227 1 Denis Savitskiy
228 1 Denis Savitskiy
no_permission_check=1   disable permission checking when receiving the email
229 1 Denis Savitskiy
</pre>
230 1 Denis Savitskiy
231 1 Denis Savitskiy
Since version 0.9 project doesn't have to be public, but authentication required in Administration-> Settings->Authentication tab has to be unchecked.
232 1 Denis Savitskiy
233 1 Denis Savitskiy
h2. Как это работает
234 1 Denis Savitskiy
235 1 Denis Savitskiy
When receiving an email, Redmine uses the From address of the email to find the corresponding user. Emails received from unknown or locked users are ignored.
236 1 Denis Savitskiy
237 1 Denis Savitskiy
If the email subject contains something like "Re: *[xxxxxxx !#123]*", the email is processed as a reply and a note is added to issue !#123. Otherwise, a new issue is created.
238 1 Denis Savitskiy
239 1 Denis Savitskiy
h3. Target project
240 1 Denis Savitskiy
241 1 Denis Savitskiy
The target project can be specified using the @project@ option when receiving emails.  This should be the identifier of the project and *not* the name.  You can easily find the identifier in the url.
242 1 Denis Savitskiy
243 1 Denis Savitskiy
If you don't use this option, users have to specify in the email body which project the issue should be added to. This can be done by inserting a line in the email body like this: @"Project: foo"@.
244 1 Denis Savitskiy
245 1 Denis Savitskiy
Пример (тело письма):
246 1 Denis Savitskiy
247 1 Denis Savitskiy
<pre>
248 1 Denis Savitskiy
This is a new issue that will be added to project foo.
249 1 Denis Savitskiy
Here we have the issue description
250 1 Denis Savitskiy
[...]
251 1 Denis Savitskiy
252 1 Denis Savitskiy
Project: foo
253 1 Denis Savitskiy
</pre>
254 1 Denis Savitskiy
255 1 Denis Savitskiy
You can set a default project using the @project@ option and let users override this default project by using the @allow-override@ option when receiving emails.
256 1 Denis Savitskiy
Example:
257 1 Denis Savitskiy
258 1 Denis Savitskiy
<pre>
259 1 Denis Savitskiy
  # Create issues on project foo by default
260 1 Denis Savitskiy
  rake redmine:email:receive_imap [...] project=foo allow_override=project
261 1 Denis Savitskiy
</pre>
262 1 Denis Savitskiy
263 1 Denis Savitskiy
Of course, user permissions are checked and this email would be ignored if the user who sent this email is not allowed to add issues to project foo.
264 1 Denis Savitskiy
Make sure that the target project doesn't use *required* custom fields with no default value for its issues, otherwise the creation of the issue will fail.
265 1 Denis Savitskiy
266 1 Denis Savitskiy
h3. Параметры задачи
267 1 Denis Savitskiy
268 5 Alex Madyarov
В зависимости от параметров, которые вы указали при получении почты (see @allow-override@ option), пользователи могут переопределять некоторые атрибуты задачи при обновлении.
269 4 Alex Madyarov
Это можно сделать использую следующие ключевые слова в теле письма (just like @Project@): @Tracker@, @Category@, @Priority@, @Status@.
270 1 Denis Savitskiy
271 1 Denis Savitskiy
Пример (тело письма):
272 1 Denis Savitskiy
273 1 Denis Savitskiy
<pre>
274 1 Denis Savitskiy
This is a new issue that overrides a few attributes
275 1 Denis Savitskiy
[...]
276 1 Denis Savitskiy
277 1 Denis Savitskiy
Project: foo
278 1 Denis Savitskiy
Tracker: Bug
279 1 Denis Savitskiy
Priority: Urgent
280 1 Denis Savitskiy
Status: Resolved
281 1 Denis Savitskiy
</pre>
282 4 Alex Madyarov
283 4 Alex Madyarov
Корректные значения атрибутов, которые могут быть использованы в параметре allow_override: project, tracker, status, priority, category, assigned_to, fixed_version (aka. Target version), start_date, due_date, estimated_hours, done_ratio.
284 1 Denis Savitskiy
285 1 Denis Savitskiy
h3. Наблюдатели
286 1 Denis Savitskiy
287 3 Denis Savitskiy
Если пользователь, посылающий сообщение, имеет право на 'Добавление наблюдателей', то пользователи, указанные в полях "Кому" и "Копия" письма, автоматически станут наблюдателями созданной задачи.
288 1 Denis Savitskiy
289 1 Denis Savitskiy
h3. Формат письма и вложения
290 1 Denis Savitskiy
291 3 Denis Savitskiy
Redmine пытается использовать текстовую часть письма, чтобы заполнить описание задачи.
292 3 Denis Savitskiy
Если получено письмо в формате HTML, то HTML тэги удаляются.
293 1 Denis Savitskiy
294 7 Михаил Галац
Вложения автоматически добавляются к задаче, но только если их размер соответствует [[RusRedmineSettings#Максимальный-размер-вложения|максимальному размеру вложения]], который определён в настройках приложения и разрешено расширение файла в настройках. Рекомендуется прописывать разрешенные расширения.