Extension Point : ITicketChangeListener

Interface	ITicketChangeListener	Since	0.10
Module	trac.ticket.api	Source	api.py​

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

Purpose

The 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 ITicketManipulator instead.)

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course 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 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:

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 TicketButcherTicketGnomeAchievementsPlugin.py in the environment plugins directory and restart TracStandalone or your web server. See TracPlugins for more information.

Available Implementations

• ​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

• ​epydoc
• ​API Reference
• See trac.ticket.api.ITicketManipulator
• See trac.ticket.api.IMilestoneChangeListener, trac.versioncontrol.api.IRepositoryChangeListener, trac.attachment.IAttachmentChangeListener, trac.wiki.api.IWikiChangeListener
• 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