== Extension Point : ''ITicketChangeListener'' ==

||'''Interface'''||''ITicketChangeListener''||'''Since'''||0.10||
||'''Module'''||''trac.ticket.api''||'''Source'''||[source:trunk/trac/ticket/api.py#/ITicketChangeListener api.py]||

The ''ITicketChangeListener'' allows components to listen for and to react to ticket events.

== Purpose ==

The [TracTickets Trac ticket system] provides simple but effective tracking of issues and bugs. Plugins can hook into the tickets module to trigger their own actions when tickets are created, deleted, changed etc.

The main purpose for this interface is to allow plugins to stay informed about the existing tickets and trigger appropriate actions elsewhere (e.g. sending notifications, starting indexing services, updating supplementary data structures etc.)

(For ticket validation and manipulation use [../trac.ticket.api.ITicketManipulator ITicketManipulator] instead.)

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].

When a user creates a new ticket the `ticket_created` method is called. Similarly methods are called when a user deletes a ticket (`ticket_deleted`), changes some ticket properties and / or comments on a ticket (`ticket_changed`), edits an existing ticket comment (`ticket_comment_modified`) or deletes / reverts a property change or comment (`ticket_change_deleted`).

The [TracDev/DataModels#Ticket Ticket data] can as always be accessed by indexing (e.g. `ticket['reporter']`, `ticket['milestone']` etc.). In `ticket_changed` the changed properties are also available (e.g. in `old_values['reporter']`).

== Examples ==

The following minimal example ITicketChangeListener implementation arbitrarily defines the criteria as editing five properties at once without (butcher) or with (gnome) a comment:
{{{#!python
from trac.core import Component, implements
from trac.ticket.api import ITicketChangeListener
from trac.wiki.model import WikiPage

class TicketButcherTicketGnomeAchievements(Component):
    implements(ITicketChangeListener)

    def ticket_created(self, ticket):
        pass

    def ticket_changed(self, ticket, comment, author, old_values):
        if len(old_values) >= 5:
            if comment:
                self._unlock_achievement(author, 'TicketGnome')
            else:
                self._unlock_achievement(author, 'TicketButcher')

    def ticket_deleted(self, ticket):
        pass

    def ticket_comment_modified(self, ticket, cdate, author, comment, old_comment):
        pass

    def ticket_change_deleted(self, ticket, cdate, changes):
        pass

    def _unlock_achievement(self, user, name):
        page = WikiPage(self.env, name)
        page.text += ' * %s\n' % (user,)
        page.save(user, 'Achievement unlocked', None)
}}}
Save it as !TicketButcherTicketGnomeAchievements.py in the plugins folder 
and then restart apache 

== Available Implementations ==
* [https://github.com/coderanger/trac-achievements TracAchievements]: Unlocks achievements
* th:TracAdvancedSearchPlugin: Indexes tickets
* th:FullTextSearchPlugin: Indexes tickets
* th:TicketTeamDispatcherPlugin: Notifies teams
* th:WorkflowNotificationPlugin: Notifies on workflow operations
* th:TracHoursPlugin: Updates hour counts
* th:TimingAndEstimationPlugin: Updates hour totals
* th:TracJsGanttPlugin: Updates schedule
* th:ScrumBurndownPlugin: Updates burndown data
* th:ChildTicketsPlugin: Updates ''parent'' / ''child'' relations
* th:MasterTicketsPlugin: Updates ''blocking'' / ''blocked by'' relations
* th:TicketCreationStatusPlugin: Tweaks the initial status of new tickets

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.ticket.api.ITicketChangeListener-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_ticket_api.html#trac.ticket.api.ITicketChangeListener API Reference]
 * See [../trac.ticket.api.ITicketManipulator trac.ticket.api.ITicketManipulator]
 * See [../trac.ticket.api.IMilestoneChangeListener trac.ticket.api.IMilestoneChangeListener], [../trac.versioncontrol.api.IRepositoryChangeListener trac.versioncontrol.api.IRepositoryChangeListener],  [../trac.attachment.IAttachmentChangeListener trac.attachment.IAttachmentChangeListener], [../trac.wiki.api.IWikiChangeListener trac.wiki.api.IWikiChangeListener]
 * [TracDev/DatabaseSchema/TicketSystem Tickets database schema]
 * Related tickets:
   * Generic change listener replacement: #8834, #11148, #6543, Trac-dev:7737
 * Mailing list discussions:
   * Run external script: Trac-ML:33887, Trac-ML:35057
   * Missing `req` parameter: Trac-ML:33193, Trac-dev:7566
   * No reentrancy guarantees: Trac-dev:7390

=== API History
 * 0.10 introduced the interface (changeset:3145, #2176, #3029)
    * Parameter `author` was added to `ticket_changed` (#3520)
 * 1.0.2 added `ticket_comment_modified` and `ticket_change_deleted` methods (#11377)
    * Note: Not available in 1.1.1