Changes between Version 14 and Version 15 of WorkflowNotificationPlugin


Ignore:
Timestamp:
Mar 11, 2015, 2:52:05 PM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes, tagged as external

Legend:

Unmodified
Added
Removed
Modified

  • WorkflowNotificationPlugin

    v14 v15  
    11[[PageOutline(2-5,Contents,pullout)]]
    22
    3 = WorkflowNotificationPlugin =
    4 
    5 == Description ==
    6 
    7 WorkflowNotificationPlugin enables flexible configuration of email
    8 notifications tied to ticket workflow changes.
    9 
    10 Administrators can configure any number of distinct email
    11 notifications to be sent out when a workflow operation occurs on a
    12 ticket. Each email notification is specifically attached to one or
    13 more workflow operations, so (for example) separate emails can be sent
    14 out when a ticket is accepted, reassigned, resolved, reopened, or
    15 marked "in QA".
    16 
    17 Each email notification's subject, body, and recipients are fully
    18 configurable by administrators, as Genshi templates which have access
    19 to the ticket's data, the comment (if any) that was left on the
    20 ticket, and the author of the change. Therefore notifications can be
    21 very flexible: some notifications can be sent to the ticket's
    22 reporter, others to its owner or CC list, others to the current
    23 updater, and others to hard-coded lists of users.
    24 
    25 The notification emails sent by this plugin respect trac's ALWAYS_CC
    26 and ALWAYS_BCC settings.
    27 
    28 The notification emails sent by this plugin are orthogonal to trac's
    29 ALWAYS_NOTIFY_UPDATER, ALWAYS_NOTIFY_OWNER, and ALWAYS_NOTIFY_REPORTER
    30 settings; Trac's built-in email notifications will be sent according
    31 to those settings, independent of this plugin's emails.
    32 
    33 == Installation ==
     3= WorkflowNotificationPlugin
     4
     5== Description
     6
     7WorkflowNotificationPlugin enables flexible configuration of email notifications tied to ticket workflow changes.
     8
     9Administrators can configure any number of distinct email notifications to be sent out when a workflow operation occurs on a ticket. Each email notification is specifically attached to one or more workflow operations, so (for example) separate emails can be sent out when a ticket is accepted, reassigned, resolved, reopened, or marked "in QA".
     10
     11Each email notification's subject, body, and recipients are fully configurable by administrators, as Genshi templates which have access
     12to the ticket's data, the comment (if any) that was left on the ticket, and the author of the change. Therefore notifications can be very flexible: some notifications can be sent to the ticket's reporter, others to its owner or CC list, others to the current updater, and others to hard-coded lists of users.
     13
     14The notification emails sent by this plugin respect trac's ALWAYS_CC and ALWAYS_BCC settings.
     15
     16The notification emails sent by this plugin are orthogonal to Trac's `ALWAYS_NOTIFY_UPDATER`, `ALWAYS_NOTIFY_OWNER` and `ALWAYS_NOTIFY_REPORTER`
     17settings. Trac's built-in email notifications will be sent according to those settings, independent of this plugin's emails.
     18
     19== Bugs/Feature Requests
     20
     21Existing bugs and feature requests for WorkflowNotificationPlugin are
     22[report:9?COMPONENT=WorkflowNotificationPlugin here].
     23
     24If you have any issues, create a
     25[http://trac-hacks.org/newticket?component=WorkflowNotificationPlugin&owner=ejucovy new ticket].
     26
     27== Download
     28
     29Download the zipped source from [http://pypi.python.org/pypi/trac-WorkflowNotificationPlugin PyPI].
     30
     31== Source
     32
     33You can check out WorkflowNotificationPlugin from git://github.com/boldprogressives/trac-WorkflowNotificationPlugin using Git, or [https://github.com/boldprogressives/trac-WorkflowNotificationPlugin browse the source] with Github.
     34
     35== Installation
    3436
    3537Install the plugin's source code:
    3638{{{
    3739#!sh
    38 $ easy_install trac-WorkflowNotificationPlugin
    39 }}}
    40 
    41 Enable its components in trac.ini:
     40easy_install trac-WorkflowNotificationPlugin
     41}}}
     42
     43Enable its components in `trac.ini`:
    4244{{{
    4345#!ini
    … …  
    4648}}}
    4749
    48 Add its component to your list of workflow providers, after all other
    49 workflow providers; for example:
     50Add its component to your list of workflow providers, after all other workflow providers, for example:
    5051{{{
    5152#!ini
    … …  
    5455}}}
    5556
    56 Now you just need to configure some notifications; see below for
    57 details and examples.
    58 
    59 
    60 
    61 == Bugs/Feature Requests ==
    62 
    63 Existing bugs and feature requests for WorkflowNotificationPlugin are
    64 [report:9?COMPONENT=WorkflowNotificationPlugin here].
    65 
    66 If you have any issues, create a
    67 [http://trac-hacks.org/newticket?component=WorkflowNotificationPlugin&owner=ejucovy new ticket].
    68 
    69 == Download ==
    70 
    71 Download the zipped source from [http://pypi.python.org/pypi/trac-WorkflowNotificationPlugin PyPI].
    72 
    73 == Source ==
    74 
    75 You can check out WorkflowNotificationPlugin from git://github.com/boldprogressives/trac-WorkflowNotificationPlugin using Git, or [https://github.com/boldprogressives/trac-WorkflowNotificationPlugin browse the source] with Github.
    76 
    77 == Example ==
    78 
    79 === Configuration ===
    80 
    81 Configure one or more notification emails attached to workflow events
    82 using a `ticket-workflow-notifications` section in `trac.ini`.
    83 
    84 Within this section, each entry is a notification email that may be
    85 sent out for a ticket.  Here is an example:
     57Now you just need to configure some notifications; see below for details and examples.
     58
     59== Example
     60
     61=== Configuration
     62
     63Configure one or more notification emails attached to workflow events using a `ticket-workflow-notifications` section in `trac.ini`.
     64
     65Within this section, each entry is a notification email that may be sent out for a ticket.  Here is an example:
    8666{{{
    8767#!ini
    … …  
    9373}}}
    9474
    95 The first line in this example defines the
    96 `notify_reporter_when_accepted` rule. The value in this line defines
    97 one or more workflow actions that will trigger this notification: in
    98 this case, the notification will be triggered when the "accept" action
    99 occurs for any ticket.  (This action is defined by the default
    100 configuration of Trac's built in ticket workflow engine; however, any
    101 action that is defined by the configuration of your installed
    102 ITicketActionControllers may be used.)
    103 
    104 We could also define a notification to occur on multiple workflow
    105 actions, using a comma separated list of workflow actions:
     75The first line in this example defines the `notify_reporter_when_accepted` rule. The value in this line defines one or more workflow actions that will trigger this notification: in this case, the notification will be triggered when the "accept" action occurs for any ticket. This action is defined by the default configuration of Trac's built in ticket workflow engine; however, any action that is defined by the configuration of your installed ITicketActionControllers may be used.
     76
     77We could also define a notification to occur on multiple workflow actions, using a comma separated list of workflow actions:
    10678{{{
    10779#!ini
    … …  
    10981}}}
    11082
    111 Multiple independent notifications can be configured for the same
    112 workflow action; in the above examples, both the
    113 `notify_owner_changed` and the `notify_reported_when_accepted` rules
    114 will be triggered when the "accept" action occurs.
    115 
    116 The following lines define the email subject, body, and recipients for
    117 a particular notification.  These are all Genshi Text Templates that
    118 will be rendered with a context that includes the ticket (in its
    119 current state AFTER the workflow action has been applied); the author
    120 and comment of the current change, if any; a link to the ticket as
    121 `${link}`; and the project.
    122 
    123 All of these must be defined for each notification; the plugin will
    124 raise errors at runtime if a notification is missing any of the
    125 `.subject`, `.body` or `.recipients` definitions.
    126 
    127 The `.recipients` definition should be a Genshi template that renders
    128 to a comma separated list of email addresses and/or usernames known to
    129 Trac.  In the above example we combine a dynamic variable based on the
    130 ticket's current state, a username known to Trac, and a hard coded
    131 email address:
     83Multiple independent notifications can be configured for the same workflow action; in the above examples, both the `notify_owner_changed` and the `notify_reported_when_accepted` rules will be triggered when the "accept" action occurs.
     84
     85The following lines define the email subject, body, and recipients for a particular notification.  These are all Genshi Text Templates that
     86will be rendered with a context that includes the ticket (in its current state AFTER the workflow action has been applied); the author
     87and comment of the current change, if any; a link to the ticket as `${link}`; and the project.
     88
     89All of these must be defined for each notification; the plugin will raise errors at runtime if a notification is missing any of the `.subject`, `.body` or `.recipients` definitions.
     90
     91The `.recipients` definition should be a Genshi template that renders to a comma separated list of email addresses and/or usernames known to Trac.  In the above example we combine a dynamic variable based on the ticket's current state, a username known to Trac, and a hard coded email address:
    13292{{{
    13393#!ini
    … …  
    13595}}}
    13696
    137 === Conditional Notifications ===
    138 
    139 In addition to the required configuration fields described above, you can
    140 optionally include a `.condition` definition for a notification.  If provided,
    141 this should be a Genshi text template which evaluates to the value True if and
    142 only if the notification should be sent.  If the template evaluates to any value
    143 other than True, the notification will be skipped. 
    144 
    145 If no `.condition` is provided, then the notification will be sent unconditionally
    146 when it is triggered.
     97=== Conditional Notifications
     98
     99In addition to the required configuration fields described above, you can optionally include a `.condition` definition for a notification. If provided, this should be a Genshi text template which evaluates to the value True if and only if the notification should be sent. If the template evaluates to any value other than True, the notification will be skipped. 
     100
     101If no `.condition` is provided, then the notification will be sent unconditionally when it is triggered.
    147102
    148103One use for this would be sending a notification when a ticket is resolved 'fixed':
    … …  
    170125}}}
    171126
    172 === Notifications for new tickets ===
    173 
    174 Most notifications are configured to refer to one or more workflow actions,
    175 like accept, leave, reassign, resolve, etc.
    176 
    177 You can also configure notifications to be triggered when a ticket is
    178 newly created. To do this, use the special workflow action `@created`
    179 like so:
     127=== Notifications for new tickets
     128
     129Most notifications are configured to refer to one or more workflow actions, like accept, leave, reassign, resolve, etc.
     130
     131You can also configure notifications to be triggered when a ticket is newly created. To do this, use the special workflow action `@created` like so:
    180132
    181133{{{
    … …  
    188140}}}
    189141
    190 === Notifications for all actions ===
    191 
    192 You can also set the special value `*` for a notification, which means
    193 it will be triggered on every workflow action.  However it will not be
    194 triggered by ticket creation:
     142=== Notifications for all actions
     143
     144You can also set the special value `*` for a notification, which means it will be triggered on every workflow action. However it will not be triggered by ticket creation:
    195145
    196146{{{
    … …  
    203153}}}
    204154
    205 To trigger a notification for every workflow action as well as ticket
    206 creation, just specify both:
     155To trigger a notification for every workflow action as well as ticket creation, just specify both:
    207156{{{
    208157#!ini
    … …  
    211160}}}
    212161
    213 === Notifications when no action has occurred ===
    214 
    215 A workflow action always occurs when a ticket is changed, even if the user
    216 doesn't explicitly select a workflow action!  In the standard Trac configuration,
    217 the default action is "leave".  So you could set up a notification like so:
     162=== Notifications when no action has occurred
     163
     164A workflow action always occurs when a ticket is changed, even if the user doesn't explicitly select a workflow action!  In the standard Trac configuration, the default action is "leave".  So you could set up a notification like so:
    218165
    219166{{{
    … …  
    225172}}}
    226173
    227 === Accessing old ticket values ===
    228 
    229 The ticket's old values are available in the notification templates.
    230 These values are provided in a Python dict named `old_values`.  The
    231 values provided are from before any changes were made to the ticket,
    232 whether by workflow operations or by direct user action.
    233 
    234 You can use this dictionary to set up a notification similar to Trac's
    235 built in ticket change email; for example:
     174=== Accessing old ticket values
     175
     176The ticket's old values are available in the notification templates. These values are provided in a Python dict named `old_values`. The
     177values provided are from before any changes were made to the ticket, whether by workflow operations or by direct user action.
     178
     179You can use this dictionary to set up a notification similar to Trac's built in ticket change email, for example:
    236180{{{
    237181#!ini
    … …  
    243187}}}
    244188
    245 === Using Blank Lines in the Announcement Emails ===
    246 
    247 As the examples above show, you can add blank lines by typing "\n" in your email template.  The plugin's code will parse these "\n" strings into actual newline characters.  So, for example, a configuration like
    248 
    249 {{{
    250     notice.body = Notification for ticket ${ticket.id}: ${link}\n\n\n\nThis is a notification.
    251 }}}
    252 
    253 should result in an email body with four blank lines between the two sentences.
    254 
    255 This seems to work more reliably than using the .ini file's own multi-line syntax which apparently collapses whitespace.
    256 
    257 Meanwhile, if there are any newlines whatsoever in your `.subject` configuration, the plugin will replace them with spaces.  This ensures that your email will have a valid subject (email subjects cannot contain newlines).
    258 
    259 == Recent Changes ==
     189=== Using Blank Lines in the Announcement Emails
     190
     191As the examples above show, you can add blank lines by typing "\n" in your email template. The plugin's code will parse these "\n" strings into actual newline characters. So, for example, this configuration should result in an email body with four blank lines between the two sentences:
     192
     193{{{
     194notice.body = Notification for ticket ${ticket.id}: ${link}\n\n\n\nThis is a notification.
     195}}}
     196
     197This seems to work more reliably than using the `trac.ini` file's own multi-line syntax which apparently collapses whitespace.
     198
     199Meanwhile, if there are any newlines whatsoever in your `.subject` configuration, the plugin will replace them with spaces. This ensures that your email will have a valid subject (email subjects cannot contain newlines).
     200
     201== Recent Changes
    260202
    261203For now please view the project's Github page for recent changes: https://github.com/boldprogressives/trac-WorkflowNotificationPlugin
    262204
    263 == Author/Contributors ==
     205== Author/Contributors
    264206
    265207'''Author:''' [wiki:ejucovy] [[BR]]
    266 '''Maintainer:''' [wiki:ejucovy] [[BR]]
     208'''Maintainer:''' [[Maintainer]] [[BR]]
    267209'''Contributors:'''