4 | | Trac はチケット更新情報をメールで通知出来ます。 (英語版では Notification) |
5 | | |
6 | | メールによる更新通知は、ユーザに関係するチケットについての最新情報を随時に提供したり、専用 ML にチケットの更新情報を配信したりするのに便利な機能です。例えば、 [http://lists.edgewall.com/archive/trac-tickets/ Trac-tickets] を見るとどのようにセットアップされているか見ることができます。 |
7 | | |
8 | | 通知機能はデフォルトでは無効になっています。有効化とコンフィグレーションは [wiki:TracIni trac.ini] で行うことができます。 |
9 | | |
10 | | == 通知メールを受け取る == #ReceivingNotificationMails |
11 | | 新しいチケットを登録したりコメントを追加する際、 ''報告者'' (英語版では ''reporter'')、 ''担当者'' (英語版では ''assigned to/owner'') もしくは ''関係者'' (英語版では ''cc'') フィールドに有効なメールアドレスやユーザ名を入力してください。チケットに更新があると、 Trac が自動的にメールを送信します。 (どのように通知メール機能を設定しているかによります) |
12 | | |
13 | | これは、興味のあるチケットや機能追加に関する最新情報を随時受け取りたい場合に便利な機能です。 |
14 | | |
15 | | === 通知メールで受信するメールアドレスを設定する方法 === #Howtouseyourusernametoreceivenotificationmails |
16 | | |
17 | | 完全なメールアドレスあるいはユーザー名を入力することで、通知メールを受け取ることができます。 単純なユーザ名やログイン名で通知を受け取るには、''ユーザ設定 (Preferences)'' ページで、正しいメールアドレスを入力する必要があります。 |
18 | | |
19 | | TracIni ファイルにデフォルトドメイン名 ('''`smtp_default_domain`''') を指定することでも、単純なユーザ名で通知を受け取ることができるようになります。 (後述する [#ConfigurationOptions コンフィグレーション オプション] を参照してください) 。この場合、ユーザ名にデフォルトドメインが追加されますので、 "イントラネット" 環境で仕様している場合は便利です。 |
20 | | |
21 | | Kerberos / Active Directory 認証に Apache と mod_kerb を使用する際、ユーザ名は ('''`username@EXAMPLE.LOCAL`''') という形式を取ります。これをメールアドレスとして解釈されない様にするためには、 ('''`ignore_domains`''') に Kerberos ドメインを追加します。 |
22 | | |
23 | | == SMTP 通知の設定 == #ConfiguringSMTPNotification |
24 | | |
25 | | '''重要:''' TracNotification を正しく動作させるには、[wiki:TracIni trac.ini] に `[trac] base_url` を設定する必要があります。 |
26 | | |
27 | | === コンフィグレーション オプション === #ConfigurationOptions |
28 | | trac.ini の `[notification]` セクションで設定できるオプションです。[[BR]](訳注: 0.10 以降では `TracIni` マクロを使用することで正確なオプション一覧を取得できます。以下のリストは必要に応じて `[[TracIni(notification)]]` に置き換えて使用してください。) |
29 | | |
30 | | * '''`smtp_enabled`''': メール通知を有効にします |
31 | | * '''`smtp_from`''': 通知メールの ''Sender''-ヘッダに使用するメールアドレス |
32 | | * '''`smtp_from_name`''': 通知メールの ''Sender''-ヘッダに使用する送信者名 |
33 | | * '''`smtp_from_author`''': (''1.0 以降'') 通知メールの'From:'のヘッダのメールアドレスとして更新者(新しいチケットの報告者、もしくはコメントの作成者)を使用。(default: false) もし更新者がメールアドレスを登録していなかったら、`smtp_from` と `smtp_from_name` が代わりに使用されます |
34 | | * '''`smtp_replyto`''': 通知メールの''Reply-To''-ヘッダに使用するメールアドレス |
35 | | * '''`smtp_default_domain`''': (''0.10 以降'') ドメイン名を含んでいないアドレスに特定のドメイン名を追加します。完全修飾されたアドレスは修正されません。ユーザの設定からメールアドレスが分からないときに、デフォルトドメインをすべてのユーザ名 / ログイン名に追加します |
36 | | * '''`smtp_always_cc`''': 常に通知メールを送信するメールアドレスのリスト。 ''主に専用MLにチケット更新を通知するのに使用されます'' |
37 | | * '''`smtp_always_bcc`''': (''0.10 以降'') 常に通知メールを送信するメールアドレスの一覧。ただし、通知メールの他の受信者からメールアドレスが見えません |
38 | | * '''`smtp_subject_prefix`''': (''0.10.1 以降'') e-mail の subject の前に挿入されるテキスト。デフォルトは "!__default!__" |
39 | | * '''`always_notify_reporter`''': 報告者フィールドのすべてのメールアドレスに常に通知メールを送信します (default: false) |
40 | | * '''`always_notify_owner`''': (''0.9 以降'') 担当者フィールドのメールアドレスに常に通知メールを送信します (default: false) |
41 | | * '''`always_notify_updater`''': (''0.10 以降'') チケットの更新者に常に通知メールを送信します (default: false) |
42 | | * '''`use_public_cc`''': (''0.10 以降'') To: (担当者, 報告者) と CC: のアドレスのリストがすべての受信者に見えるかどうかを設定します ( デフォルトは ''Bcc:'' で見えません) |
43 | | * '''`use_short_addr`''': (''0.10 以降'') 通知メールの配信でメールアドレスがドメイン名を含むようにするかどうかを設定します (例 ''@<domain.com>'' で終わらないようにする)。このオプションは SMTP サーバがローカルアドレスをハンドリングでき、ローカルのメールボックスとユーザ名/ログイン名をマップできるような環境、イントラネット内で使用するときに便利です |
44 | | * '''`ignore_domains`''': メールアドレスの一部と見なされるべきでないドメインのカンマ区切りリスト (Kerberos ドメインのユーザ名向け) |
45 | | * '''`mime_encoding`''': (''0.10 以降'') MIME のエンコードのスキームを選択します。サポートする値: |
46 | | * `none`: デフォルト値。テキストがプレーンな ASCII 文字コード、もしくはその他 8 ビットの文字コードであるときに、 7 ビットエンコードを使用します |
47 | | * `base64`: どのような内容が含まれていても動作します。敏感なアンチスパム / アンチウイルスエンジンではいくつかの問題があるかもしれません |
48 | | * `qp` または `quoted-printable`: 8 ビットエンコーディングが使用できない場合、ヨーロッパの言語に対して最適です ( base64 よりもコンパクトです ) |
49 | | * '''`ticket_subject_template`''': (''0.11 以降'') 通知メールの件名 (Subject) に使用する [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi テキストテンプレート] |
50 | | * '''`email_sender`''': (''0.12 以降'') `IEmailSender` インタフェースを実装しているコンポーネント名。通知システムは、ここで設定されたコンポーネントを使用してメールを送信します。現在のところ Trac では以下のコンポーネントが提供されています: |
51 | | * `SmtpEmailSender`: SMTP サーバに接続してメールを送信する (デフォルト) |
52 | | * `SendmailEmailSender`: `sendmail` 互換の実行ファイルを実行してメールを送信する |
53 | | |
54 | | '''`smtp_from`''' か '''`smtp_replyto`''' の一方 (もしくは両方) が ''必ず'' 設定されていなければなりません。設定されていない場合、 Trac は通知メールの送信を拒否します。 |
55 | | |
56 | | 以下のオプションは SMTP でのメッセージ伝送方法を指定するために使用します。 |
57 | | * '''`smtp_server`''': 通知メッセージに使用されるSMTPサーバ |
58 | | * '''`smtp_port`''': (''0.9 以降'') SMTP サーバが使用するポート番号 |
59 | | * '''`smtp_user`''': (''0.9 以降'') SMTP 認証アカウントのユーザID |
60 | | * '''`smtp_password`''': (''0.9 以降'') SMTP 認証アカウントのパスワード |
61 | | * '''`use_tls`''': (''0.10 以降'') SMTP サーバ経由で通知メールを送信するときに、GMail などの [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS] を使用するかどうかを切り替えます |
62 | | |
63 | | 以下のオプションは `sendmail` 互換の実行ファイルを使用する場合のメッセージ伝送方法を指定するために使用します。 |
64 | | * '''`sendmail_path`''': (''0.12 以降'') sendmail の実行ファイルへのパスを設定します。ここで指定する sendmail プログラムは `-i` および `-f` オプションを解釈できなければなりません |
65 | | |
66 | | === コンフィグレーションの例 (SMTP) === #ExampleConfigurationSMTP |
67 | | {{{ |
| 4 | Trac supports notification of ticket changes via email. |
| 5 | |
| 6 | Email notification is useful to keep users up-to-date on tickets of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list. |
| 7 | |
| 8 | Disabled by default, notification can be activated and configured in [TracIni trac.ini]. |
| 9 | |
| 10 | == Receiving Notification Mails |
| 11 | When reporting a new ticket or adding a comment, enter a valid email address or your Trac username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac will automatically send you an email when changes are made to the ticket, depending on how notification is configured. |
| 12 | |
| 13 | === How to use your username to receive notification mails |
| 14 | |
| 15 | To receive notification mails, you can either enter a full email address or your Trac username. To get notified with a simple username or login, you need to specify a valid email address in your [/prefs preferences]. |
| 16 | |
| 17 | Alternatively, a default domain name ('''`smtp_default_domain`''') can be set in the TracIni file, see [#ConfigurationOptions Configuration Options] below. In this case, the default domain will be appended to the username, which can be useful for an "Intranet" kind of installation. |
| 18 | |
| 19 | When using apache and mod_kerb for authentication against Kerberos / Active Directory, usernames take the form ('''`username@EXAMPLE.LOCAL`'''). To avoid this being interpreted as an email address, add the Kerberos domain to ('''`ignore_domains`'''). |
| 20 | |
| 21 | === Ticket attachment notifications |
| 22 | |
| 23 | Since 1.0.3 Trac will send notifications when a ticket attachment is added or deleted. Usually attachment notifications will be enabled in an environment by default. To disable the attachment notifications for an environment the `TicketAttachmentNotifier` component must be disabled: |
| 24 | {{{#!ini |
| 25 | [components] |
| 26 | trac.ticket.notification.TicketAttachmentNotifier = disabled |
| 27 | }}} |
| 28 | |
| 29 | == Configuring SMTP Notification |
| 30 | |
| 31 | '''Important:''' The [[TracIni#trac-base_url-option|[trac] base_url]] option must be configured for links in the notification message to be correctly generated. |
| 32 | |
| 33 | === Configuration Options |
| 34 | These are the available options for the `[notification]` section in trac.ini: |
| 35 | |
| 36 | [[TracIni(section=notification)]] |
| 37 | |
| 38 | === Example Configuration (SMTP) |
| 39 | {{{#!ini |
87 | | === メールの件名をカスタマイズする === #Customizingthee-mailsubject |
88 | | `ticket_subject_template` オプションを使用することでメールの件名をカスタマイズできます。このオプションには [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi テキストテンプレート] を含めることができます。デフォルト値は以下の通りです: |
89 | | {{{ |
90 | | $prefix #$ticket.id: $summary |
91 | | }}} |
92 | | テンプレートでは以下の変数が使用可能です: |
93 | | |
94 | | * `env`: プロジェクトの Environemnt ([http://trac.edgewall.org/browser/trunk/trac/env.py env.py] 参照) |
95 | | * `prefix`: `smtp_subject_prefix` で定義したプレフィックス |
96 | | * `summary`: チケットの概要 (Summary), 概要が変更されている場合は古い値 |
97 | | * `ticket`: ticket model オブジェクト ([http://trac.edgewall.org/browser/trunk/trac/ticket/model.py model.py] 参照)。個別のチケット属性は `$ticket.milestone` のように、ドット (.) で区切って (訳注: 英語での) 属性名を加えることで、参照可能 |
98 | | |
99 | | === メールの内容をカスタマイズする === #Customizingthee-mailcontent |
100 | | |
101 | | 通知メールの内容は `trac/templates` の `ticket_notify_email.txt` を基に生成されます。編集した `ticket_notify_email.txt` を Environment の templates ディレクトリに配置することで、カスタマイズすることができます。デフォルトはこのようになっています: |
102 | | |
103 | | {{{ |
| 59 | === Subscriber Configuration |
| 60 | The default subscriptions are configured in the [TracIni#notification-subscriber-section "[notification-subscriber]"] section. |
| 61 | |
| 62 | [[TracIni(section=notification-subscriber)]] |
| 63 | |
| 64 | Each user can override these defaults in their ''Notifications'' preferences. |
| 65 | |
| 66 | For example to unsubscribe from notifications for one's own changes and comments, the rule "Never notify: I update a ticket" should be added above other subscription rules. |
| 67 | |
| 68 | The subscription rule name on the left side of the `=` can be anything, it has no meaning outside this configuration file. The subscriber name on the right side of the `=` must be one of the subscribers listed in the above table. |
| 69 | |
| 70 | The following attributes of default subscriptions can be configured: |
| 71 | * `.distributor` (Default: `email`) |
| 72 | * Other values require plugins. For example `on-site` requires th:OnSiteNotificationsPlugin. |
| 73 | * `.priority` (Default: `100`) |
| 74 | * Smaller values override larger values. |
| 75 | * If you use `0`, then users will not be able to override this rule. |
| 76 | * `.adverb` (Default: `always`) |
| 77 | * `never` can be used to silence other subscription rules with higher values. |
| 78 | * `.format` (Default: `text/plain`) |
| 79 | * Other values require plugins. For example `text/html` requires th:TracHtmlNotificationPlugin. |
| 80 | |
| 81 | === Example Configuration (default subscriptions) |
| 82 | {{{#!ini |
| 83 | [notification-subscriber] |
| 84 | always_notify_owner = TicketOwnerSubscriber |
| 85 | always_notify_owner.distributor = email |
| 86 | always_notify_owner.priority = 100 |
| 87 | always_notify_owner.adverb = always |
| 88 | always_notify_owner.format = text/plain |
| 89 | |
| 90 | always_notify_previous_updater = TicketPreviousUpdatersSubscriber |
| 91 | |
| 92 | never_notify_updater = TicketUpdaterSubscriber |
| 93 | never_notify_updater.adverb = never |
| 94 | never_notify_updater.priority = 0 |
| 95 | |
| 96 | notify_cc_html = CarbonCopySubscriber |
| 97 | notify_cc_html.format = text/html |
| 98 | }}} |
| 99 | |
| 100 | === Customizing the e-mail subject |
| 101 | The e-mail subject can be customized with the `ticket_subject_template` option, which contains a [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is: |
| 102 | {{{#!genshi |
| 103 | ${prefix} #${ticket.id}: ${summary} |
| 104 | }}} |
| 105 | The following variables are available in the template: |
| 106 | |
| 107 | * `env`: The project environment object (see [trac:source:branches/1.2-stable/trac/env.py env.py]). |
| 108 | * `prefix`: The prefix defined in `smtp_subject_prefix`. |
| 109 | * `summary`: The ticket summary, with the old value if the summary was edited. |
| 110 | * `ticket`: The ticket model object (see [trac:source:branches/1.2-stable/trac/ticket/model.py model.py]). Individual ticket fields can be accessed by appending the field name separated by a dot, eg `${ticket.milestone}`. |
| 111 | |
| 112 | === Customizing the e-mail content |
| 113 | |
| 114 | The notification e-mail content is generated based on `ticket_notify_email.txt` in `trac/ticket/templates`. You can add your own version of this template by adding a `ticket_notify_email.txt` to the templates directory of your environment. The default is: |
| 115 | |
| 116 | {{{#!genshi |
163 | | == MS Outlook 向け E メールカスタマイズ == #Customizinge-mailcontentforMSOutlook |
164 | | |
165 | | 通常何も設定していなければ、 MS Outlook では可変長フォントのプレーンテキストメールを提示します。そのため、チケットプロパティの表は確実にゴチャゴチャしたように見えます。この問題は、 [#Customizingthee-mailcontent メールテンプレート] のカスタマイズにより解決することができます。 |
166 | | |
167 | | |
168 | | テンプレートの2行目を次のように置き換えます: |
169 | | {{{ |
170 | | $ticket_props |
171 | | }}} |
172 | | |
173 | | この代わりに (''Python 2.6 以降が必要''): |
174 | | {{{ |
175 | | -------------------------------------------------------------------------- |
176 | | {% with |
177 | | pv = [(a[0].strip(), a[1].strip()) for a in [b.split(':') for b in |
178 | | [c.strip() for c in |
179 | | ticket_props.replace('|', '\n').splitlines()[1:-1]] if ':' in b]]; |
180 | | sel = ['Reporter', 'Owner', 'Type', 'Status', 'Priority', 'Milestone', |
181 | | 'Component', 'Severity', 'Resolution', 'Keywords'] %}\ |
182 | | ${'\n'.join('%s\t%s' % (format(p[0]+':', ' <12'), p[1]) for p in pv if p[0] in sel)} |
183 | | {% end %}\ |
184 | | -------------------------------------------------------------------------- |
185 | | }}} |
186 | | |
187 | | チケットプロパティの表は、選択するプロパティのリストに置き換えられます。MS Outlook を使用する際に、デフォルトの表よりわかりやすくなるように、タブ文字で名前と値を分離しています。 |
188 | | {{{#!div style="margin: 1em 1.75em; border:1px dotted" |
189 | | {{{#!html |
190 | | #42: testing<br /> |
191 | | --------------------------------------------------------------------------<br /> |
192 | | <table cellpadding=0> |
193 | | <tr><td>Reporter:</td><td>jonas@example.com</td></tr> |
194 | | <tr><td>Owner:</td><td>anonymous</td></tr> |
195 | | <tr><td>Type:</td><td>defect</td></tr> |
196 | | <tr><td>Status:</td><td>assigned</td></tr> |
197 | | <tr><td>Priority:</td><td>lowest</td></tr> |
198 | | <tr><td>Milestone:</td><td>0.9</td></tr> |
199 | | <tr><td>Component:</td><td>report system</td></tr> |
200 | | <tr><td>Severity:</td><td>major</td></tr> |
201 | | <tr><td>Resolution:</td><td> </td></tr> |
202 | | <tr><td>Keywords:</td><td> </td></tr> |
203 | | </table> |
204 | | --------------------------------------------------------------------------<br /> |
205 | | Changes:<br /> |
206 | | <br /> |
207 | | * component: changset view => search system<br /> |
208 | | * priority: low => highest<br /> |
209 | | * owner: jonas => anonymous<br /> |
210 | | * cc: daniel@example.com =><br /> |
211 | | daniel@example.com, jonas@example.com<br /> |
212 | | * status: new => assigned<br /> |
213 | | <br /> |
214 | | Comment:<br /> |
215 | | I'm interested too!<br /> |
216 | | <br /> |
217 | | --<br /> |
218 | | Ticket URL: <http://example.com/trac/ticket/42><br /> |
219 | | My Project <http://myproj.example.com/><br /> |
220 | | }}} |
221 | | }}} |
222 | | |
223 | | **重要**: `sel` にリストされているチケットフィールドのみ HTML メールに含まれます。もし、メールに当然含まなくてはならないカスタムチケットフィールドを定義するのであれば、`sel` に追加しなければなりません。例: |
224 | | {{{ |
225 | | sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2'] |
226 | | }}} |
227 | | |
228 | | しかしながら、 自動的なHTMLフォーマットのメールのように完璧ではありません。それでも、現状のチケットのプロパティをマイクロソフトのアウトルックによって少なくとも読むことは出来ます。。。 |
229 | | |
230 | | |
231 | | == SMTP リレーホストとして GMail を使用する == #UsingGMailastheSMTPrelayhost |
232 | | |
233 | | 以下のような設定を使用します |
234 | | {{{ |
| 179 | == Using GMail as the SMTP relay host |
| 180 | |
| 181 | Use the following configuration snippet: |
| 182 | {{{#!ini |
245 | | ''user'' と ''password'' の箇所は、 GMail のアカウントで置き換えてください。 ''たとえば'' [http://gmail.com] にログインするときに使用しているものです。 |
246 | | |
247 | | 代わりに `smtp_port = 25` を使用することもできます。 (訳注: おそらく `gmail.com` 宛のメールしか届きません)[[br]] |
248 | | しかし `smtp_port = 465` は使用できません。これは動作しないだけでなく、通知メール送信がデッドロックします。ポート番号 465 は SMTPS プロトコル (訳注: SSMTP とも言います) に使用されますが、 Trac はこれをサポートしていません。詳しくは [trac:comment:2:ticket:7107 #7107] を参照してください。 |
249 | | |
250 | | == 自分が変更した通知をフィルタする == #Filteringnotificationsforonesownchanges |
251 | | Gmail では、以下のフィルタを使用できます: |
252 | | |
253 | | {{{ |
254 | | from:(<smtp_from>) (("Reporter: <username>" -Changes) OR "Changes (by <username>)") |
255 | | }}} |
256 | | |
257 | | Trac 0.10 の場合は、下記のフィルタを使用してください: |
258 | | {{{ |
259 | | from:(<smtp_from>) (("Reporter: <username>" -Changes -Comment) OR "Changes (by <username>)" OR "Comment (by <username>)") |
260 | | }}} |
261 | | |
262 | | 通知メールを削除する場合などにも使用できます。 |
263 | | |
264 | | Thunderbird で IMAP を使用している場合は、この方法は使えません |
265 | | (http://kb.mozillazine.org/Filters_(Thunderbird)#Filtering_the_message_body 参照)。 |
266 | | |
267 | | 最良の方法は conf/trac.ini の "always_notify_updater" を false に設定することです。 |
268 | | しかし、この方法では自分が担当者 (owner) になっていたり、報告 (reporter) したチケットへのコメントが取得できなくなります。 |
269 | | |
270 | | プラグインを追加することで解決するかもしれません: |
271 | | http://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin |
272 | | |
273 | | == トラブルシューティング == #Troubleshooting |
274 | | |
275 | | 通知メールの設定がうまくいかないとき、最初にログが出力されるようになっているか確かめて下さい。そしてどういうエラーメッセージが出力されているかを見てください。[trac:TracLogging TracLogging] にログについて書いてあるので見て下さい。 |
276 | | |
277 | | 通知メールのエラーは Web インタフェースで報告されないので、誰かがチケットを更新したり、新規のチケットを登録しても通知メールが届かないことにまったく気づかないでしょう。 Trac の管理者はエラートレースを追い、ログをみる必要があります。 |
278 | | |
279 | | === ''Permission denied'' エラー === #Permissiondeniederror |
280 | | |
281 | | たいていのエラーメッセージ: |
282 | | {{{ |
| 193 | where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [http://gmail.com]. |
| 194 | |
| 195 | Alternatively, you can use `smtp_port = 25`.[[br]] |
| 196 | You should not use `smtp_port = 465`. Doing so may deadlock your ticket submission. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [trac:comment:2:ticket:7107 #7107] for details. |
| 197 | |
| 198 | == Troubleshooting |
| 199 | |
| 200 | If notifications are not working, inspect the [TracLogging log] for error messages. |
| 201 | |
| 202 | Notification errors are not always reported through the web interface, so the user who submits a change or creates a ticket may not get notified about a notification failure. The Trac administrator needs to look at the log to find the error message and traceback. |
| 203 | |
| 204 | === ''Permission denied'' error |
| 205 | |
| 206 | Typical error message: |
| 207 | {{{#!sh |