Administrators can configure any number of distinct emailnotifications to be sent out when a workflow operation occurs on aticket. Each email notification is specifically attached to one ormore workflow operations, so (for example) separate emails can be sentout when a ticket is accepted, reassigned, resolved, reopened, ormarked "in QA".

Each email notification's subject, body, and recipients are fullyconfigurable by administrators, as Genshi templates which have accessto the ticket's data, the comment (if any) that was left on theticket, and the author of the change. Therefore notifications can bevery flexible: some notifications can be sent to the ticket'sreporter, others to its owner or CC list, others to the currentupdater, and others to hard-coded lists of users.

The notification emails sent by this plugin respect trac's ALWAYS_CCand ALWAYS_BCC settings.

The notification emails sent by this plugin are orthogonal to trac'sALWAYS_NOTIFY_UPDATER, ALWAYS_NOTIFY_OWNER, and ALWAYS_NOTIFY_REPORTERsettings; Trac's built-in email notifications will be sent accordingto those settings, independent of this plugin's emails.

Add its component to your list of workflow providers, after all otherworkflow providers; for example:{{{[ticket]workflow = ConfigurableTicketWorkflow, TicketWorkflowNotifier}}}

Now you just need to configure some notifications; see below fordetails and examples.

== Configuration ==

Configure one or more notification emails attached to workflow eventsusing a `ticket-workflow-notifications` section in `trac.ini`.

Within this section, each entry is a notification email that may besent out for a ticket. Here is an example:{{{[ticket-workflow-notifications]notify_reporter_when_accepted = acceptnotify_reporter_when_accepted.body = Hi $ticket.reporter, '$ticket.summary' has been accepted by $change.author. Its status is now $ticket.status.\n\n{% if change.comment %}$change.author said:\n\n$change.comment{% end %}-----\nTicket URL: $link\n$project.name <${project.url or abs_href()}>\n$project.descrnotify_reporter_when_accepted.recipients = $ticket.reporter, trac-admin@hostname.com, trac_usernotify_reporter_when_accepted.subject = '$ticket.summary' is now accepted}}}

The first line in this example defines the`notify_reporter_when_accepted` rule. The value in this line definesone or more workflow actions that will trigger this notification: inthis case, the notification will be triggered when the "accept" actionoccurs for any ticket. (This action is defined by the defaultconfiguration of Trac's built in ticket workflow engine; however, anyaction that is defined by the configuration of your installedITicketActionControllers may be used.)

We could also define a notification to occur on multiple workflowactions, using a comma separated list of workflow actions:{{{notify_owner_changed = accept, reassign}}}

Multiple independent notifications can be configured for the sameworkflow action; in the above examples, both the`notify_owner_changed` and the `notify_reported_when_accepted` ruleswill be triggered when the "accept" action occurs.

The following lines define the email subject, body, and recipients fora particular notification. These are all Genshi Text Templates thatwill be rendered with a context that includes the ticket in itscurrent state AFTER the workflow action has been applied; the ticket'svalues before any changes were made, as an `old_ticket` dictionary; theauthor and comment of the current change, if any; a link to the ticket as`$link`; and the project.

All of these must be defined for each notification; the plugin willraise errors at runtime if a notification is missing any of the`.subject`, `.body` or `.recipients` definitions.

The `.recipients` definition should be a Genshi template that rendersto a comma separated list of email addresses and/or usernames known toTrac. In the above example we combine a dynamic variable based on theticket's current state, a username known to Trac, and a hard codedemail address:{{{notify_reporter_when_accepted.recipients = $ticket.reporter, trac-admin@hostname.com, trac_user}}}

=== Conditional Notifications ===

In 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 andonly if the notification should be sent. If the template evaluates to any valueother than True, the notification will be skipped.

If no `.condition` is provided, then the notification will be sent unconditionallywhen it is triggered.

One use for this would be sending a notification when a ticket is resolved 'fixed':

To trigger a notification for every workflow action as well as ticket creation, just specify both:{{{[ticket-workflow-notifications]ticket_changed = *, @created}}}

==== Accessing old ticket values =====

The ticket's old values are available in the notification templates.These values are provided in a Python dict named `old_values`. Thevalues provided are from before any changes were made to the ticket,whether by workflow operations or by direct user action.

You can use this dictionary to set up a notification similar to Trac'sbuilt in ticket change email; for example:{{{[ticket-workflow-notifications]ticket_changed = *ticket_changed.body = Ticket changed by $change.author: $change.comment {% for field in old_ticket %}{% if old_ticket[field] != ticket[field] %} $field changed: ${old_ticket[field]} => ${ticket[field]}{% end %}{% end %}ticket_changed.recipients = $ticket.reporterticket_changed.subject = Ticket $ticket.id has changed!}}}0.5 (2013-11-21)----------------

* Notifications can now be configured through Trac's web admin system.