Changes between Version 42 and Version 43 of TracCronPlugin


Ignore:
Timestamp:
Mar 4, 2015, 7:12:04 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • TracCronPlugin

    v42 v43  
    11[[PageOutline(2-5,Contents,pullout)]]
    22
    3 = Trac Cron Plugin =
    4 
    5 == Description ==
    6 
    7 This plugin adds a scheduler inside the Trac process that can handle any sort
    8 of task written in the python language. Main features are:
     3= Trac Cron Plugin
     4
     5== Description
     6
     7This plugin adds a scheduler inside the Trac process that can handle any sort of task written in the Python language. Main features are:
    98
    109 * Task are plugin
    … …  
    1615 * Task execution history '''new''' ''rss feed is available''
    1716
    18 The plugin provides an administration panel to help scheduling.
     17So if you have any function for entry point of a Trac related process and you want to add it as a job, Trac Cron Plugin is for you.
     18
     19The plugin provides an administration panel to help with scheduling:
    1920
    2021[[Image(tcp_admin_panel.png, 80%)]]
    2122
    22 == Bugs/Feature Requests ==
    23 
    24 Existing bugs and feature requests for TracCronPlugin are
    25 [report:9?COMPONENT=TracCronPlugin here].
    26 
    27 If you have any issues, create a
    28 [http://trac-hacks.org/newticket?component=TracCronPlugin&owner=t2y new ticket].
    29 
    30 == Download ==
    31 
    32 === Lastest release ===
    33 
    34 Current stable release is '''0.3.1'''
    35 You can use easy_install or pip to download the latest package into your python environment
     23== Bugs/Feature Requests
     24
     25Existing bugs and feature requests for TracCronPlugin are [report:9?COMPONENT=TracCronPlugin here].
     26
     27If you have any issues, create a [http://trac-hacks.org/newticket?component=TracCronPlugin&owner=t2y new ticket].
     28
     29== Download
     30
     31=== Lastest release
     32
     33Current stable release is '''0.3.1'''.
     34You can use easy_install or pip to download the latest package into your Python environment:
    3635
    3736{{{
    3837#!sh
    39 $ easy_install TracCronPlugin
    40 or
    41 $ pip install TracCronPlugin
    42 }}}
    43 
    44 or download distributions files at [http://pypi.python.org/pypi/TracCronPlugin pypi] (only source distributions)
    45 
    46 == Source ==
     38easy_install TracCronPlugin
     39}}}
     40or:
     41{{{
     42#!sh
     43pip install TracCronPlugin
     44}}}
     45
     46Alternatively, download the distributions files at [http://pypi.python.org/pypi/TracCronPlugin pypi] for source distributions only.
     47
     48== Source
    4749
    4850You can clone TracCronPlugin from [https://bitbucket.org/t2y/trac.plugins.traccron here] using Mercurial, or browse the source.
    49 Originally, TracCronPlugin source is hosted in [http://trac-hacks.org/svn/traccronplugin trac-hacks.org svn]. I won't maintain any longer.
    50 
    51 == Example ==
    52 
    53 My company needed to synchronize trac users with an external account source. The job was done by an ETL but fine tuning of trac user was still done by a our modified version of Trac by clicking on a button on the admin panel that call a well designed API. So instead of manually clicking on the button I searched for a way to automate it. Unfortunately, I did not find any plugin for this and even if I could use a unix cron task or an windows AT command to plane the task, I thought it would be better done inside Trac process.
    54 
    55 So if you have any function for entry point of a process (I mean trac related process) and you want to plane it as a job, Trac Cron Plugin is for you.
    56 
    57 Simply create in a module (.py) a class that implements the ICronTask and put it inside the plugins directory. Then you can either trick the trac.ini either comfortably use the dedicated admin panel.
    58 
    59 === How to write a task ===
    60 
    61 You have to write python class that inherits of ICronTask which code is below:
     51Originally, TracCronPlugin source is hosted in [http://trac-hacks.org/svn/traccronplugin trac-hacks.org svn], but is no longer maintained there.
     52
     53== Example
     54
     55Simply create in a module (.py) a class that implements the ICronTask and put it inside the plugins directory. Then you can either modify the trac.ini or use the Trac cron admin panel.
     56
     57=== Writing a task
     58
     59You have to write a Python class that inherits ICronTask:
    6260{{{
    6361#!python
    … …  
    8684}}}
    8785
    88 Let's take a look at the heartbeat task packed with TracCronPlugin:
     86Let's take a look at the heartbeat task included with TracCronPlugin:
    8987
    9088{{{
    … …  
    112110}}}
    113111
    114 You need to implement the interface and to put the definition of the task inside the '''wake_up''' method
    115 
    116 === How to install the task ===
    117 
    118 Since tasks are components you just have to put the class definition of your task in a python module in the plugins directory.
    119 You can either create a .py file and put it in plugins directory or package the .py file into an eggs you'll leave in plugins directory.
    120 
    121 TracCronPlugin will show up the task in it administration panel. Enjoy !
    122 
    123 == Configuration ==
     112You need to implement the interface and to put the definition of the task inside the '''wake_up''' method.
     113
     114=== Installing a task
     115
     116Since tasks are components you just have to put the class definition of your task in a Python module in the plugins directory.
     117You can either create a .py file and put it in the plugins directory. Alternatively you can package the .py file into an egg and leave it in plugins directory.
     118
     119TracCronPlugin will show up the task in the administration panel.
     120
     121== Configuration
    124122
    125123The plugin can be entirely configured from either trac.ini or the administration panel.
    126 The section name of TracCronPlugin is traccron, here is a full sample
     124The section name of TracCronPlugin is traccron, here is a full sample:
    127125
    128126{{{
    … …  
    144142}}}
    145143
    146 === Global setting ===
     144=== Global settings
    147145
    148146{{{
    … …  
    151149}}}
    152150
    153 This control the object called ticker which is the thread that launch tasks. If False, no ticket (no thread) is created so your Trac is merely like no cron is installed. This is the more global setting you can act on to enable or disable ALL task. Default value is '''True'''.
     151This control the object called ticker which is the thread that launches tasks. If False, no ticket (no thread) is created, so your Trac behaves like there is no cron installed. This is the more global setting you can act on to enable or disable all tasks. Default value is '''True'''.
    154152
    155153{{{
    … …  
    158156}}}
    159157
    160 This key control the interval between each wake up of the ticker. The ticker thread periodically wake up to see if there is task to execute. Then the ticker thread go sleep for the amount of minutes specified by this key. You should not have modify this value except if you have system load issue. Default value is '''1'''.
    161 
    162 
    163 === Task setting ===
    164 
    165 For each task loaded by Trac Component manager, Trac Cron Plugin have those parameters. Let's look at hear beat task:
    166 
    167 ==== Enable/Disable a task ====
    168 
     158This key control the interval between each wake up of the ticker. The ticker thread periodically wakes up to see if there is task to execute. Then the ticker thread go sleep for the amount of minutes specified by this key. You should not have modify this value, except if you have system load issue. Default value is '''1'''.
     159
     160=== Task settings
     161
     162For each task loaded by the Trac Component manager, Trac Cron Plugin have those parameters. Let's look at a heart beat task.
     163
     164==== Enabling and disabling a task
    169165
    170166{{{
    … …  
    173169}}}
    174170
    175 This is the second way to enable or disable a task. Since ''ticker_enabled'' is global and so all task will be affected, this key only affect one task. If False, whatever schedule the task have, no one will be triggered, so this is a way to disable a task while keep all the schedule in place for the time you will enable the task. Default is '''True'''.
    176 
    177 
    178 ==== Task scheduling ====
     171This is the second way to enable or disable a task. Since ''ticker_enabled'' is global and so all tasks will be affected, this key only affects one task. If False, whatever schedule the task has, not one will be triggered, so this is a way to disable a task while keeping the schedule in place for the time you will enable the task. Default is '''True'''.
     172
     173==== Task scheduling
    179174
    180175{{{
    … …  
    183178}}}
    184179
    185 This control the daily scheduler. As this name suggest, it trigger the task every day. You need to provide time you want the task to execute. You can give a comma separated list to trigger the task at multiple time everyday. Default is no value.
    186 
     180This controls the daily scheduler. As the name suggests, it triggers the task every day. Provide the time you want the task to execute. You can give a comma separated list to trigger the task at multiple times everyday. Default is no value.
    187181
    188182{{{
    … …  
    191185}}}
    192186
    193 The goal of this scheduler is to trigger task every hours. You provide minute when you want the task to be executed. Accept comma separated list of values. Default is no value.
    194 
     187The goal of this scheduler is to trigger the task every hour. Provide minute when you want the task to be executed. Accept comma separated list of values. Default is no value.
    195188
    196189{{{
    … …  
    199192}}}
    200193
    201 This scheduler trigger task that need to be executed once a month. You provide the day in month and the hour when the task will be launched. The day is the index of the day starting at 1. Accept comma separated value. Default is no value
    202 
     194This scheduler triggers a task that needs to be executed once a month. Provide the day in month and the hour when the task will be launched. The day is the index of the day starting at 1. Accepts comma separated value. Default is no value
    203195
    204196{{{
    … …  
    207199}}}
    208200
    209 This sceduler trigger task that need to be executed once a week. You provide the day in week and the hour when the task will be launched. The day is the index of the day starting at 0 (Monday is 0). Accept comma separated value. Default is no value
    210 
    211 ==== Enable/Disable a schedule ====
     201This scheduler triggers a task that needs to be executed once a week. Provide the day in week and the hour when the task will be launched. The day is the index of the day starting at 0 (Monday is 0). Accept comma separated value. Default is no value
     202
     203==== Enabling and disabling a schedule
    212204
    213205Each schedule can individually be enabled or disabled. This the configuration for daily scheduler:
    … …  
    220212This enables or disables the trigger. If False, the scheduler will not trigger the task. Default is '''True'''.
    221213
    222 ==== Pass argument to a task ====
    223 
    224 You can pass arguments to the task on a per schedule basis. Here an example for daily schedule:
    225 
    226 {{{
    227 #!ini
    228 hear_beat_daily.arg = Good Morging
    229 }}}
    230 
    231 When the daily schedule triggers the task, the value of the key is passed to the '''wake_up''' call. Parameters can be coma separated multiple value. Default is '''empty'''
    232 
    233 == Bundled Task ==
    234 
    235 Besides the HearBeat task provided for testing purpose, TracCronPlugin comes with the following useful task.
    236 
    237 === sleeping_ticket ===
    238 
    239 This task reminds reporter about orphaned ticket and assigned user about sleeping ticket. An orphaned ticket is a ticket in new status since more than a given amount of day. An email notification is sent to the reporter in such a case. A sleeping ticket is a ticket assigned to an user, but the user either did not accept it or did not touch the ticket(make comment for example) since more than a given amount of day. The assigned user is notified in such a case. The delay is an optional parameter associated with each schedule. Default value is '''3 day'''.
    240 
    241 === unreachable milestone ===
     214==== Pass argument to a task
     215
     216You can pass arguments to the task on a per schedule basis. Here an example for a daily schedule:
     217
     218{{{
     219#!ini
     220hear_beat_daily.arg = Good Morning
     221}}}
     222
     223When the daily schedule triggers the task, the value of the key is passed to the '''wake_up''' call. Parameters can be comma separated values. Default is '''empty'''.
     224
     225== Bundled Task
     226
     227Besides the HeartBeat task provided for testing purposes, TracCronPlugin comes with the following useful tasks.
     228
     229=== sleeping_ticket
     230
     231This task reminds the reporter about orphaned tickets and the assigned user about sleeping ticket. An orphaned ticket is a ticket in new status since more than a given amount of day. An email notification is sent to the reporter in such a case. A sleeping ticket is a ticket assigned to an user, but the user either did not accept it or did not touch the ticket(make comment for example) since more than a given amount of day. The assigned user is notified in such a case. The delay is an optional parameter associated with each schedule. Default value is '''3 day'''.
     232
     233=== unreachable milestone
     234
    242235'''Note''': Since 0.2dev_r9388
    243236
    … …  
    250243The milestone milestone1 is near to be closed. Its due date is 11-30-2010.
    251244
    252 Unfortunately we have detected some still opened ticket.
     245Unfortunately we have detected some open tickets.
    253246Please consider to postpone them or ensure they will meet the milestone due date.
    254247
    255 These ticket are
     248These ticket are:
    256249
    257250testing ticket
    … …  
    270263}}}
    271264
    272 === Auto postpone task ===
    273 
    274 '''note''': since 0.2dev_r9390
    275 
    276 Trac allow the administrator to postpone still opened ticket in a given milestone when he close a this milestone. But this is not mandatory. The auto postpone task will help to not forget opened tickets in closed milestone. The task look for such tickets and postpone them in the more recent still opened milestone (milestone must have a due date)
    277 
    278 === Ticket deadline task ===
    279 
    280 '''note''': since 0.3
    281 
    282 This task notify to ticket's reporter and owner when its ticket is near the deadline as a custom field. You can add date field for ticket using [http://trac-hacks.org/wiki/DateFieldPlugin DateFieldPlugin]. Besides scheduler settings, there are 3 options to configure when DateFieldPlugin is used.
     265=== Auto postpone task
     266
     267'''Note''': since 0.2dev_r9390
     268
     269Trac allow the administrator to postpone still opened ticket in a given milestone when he closes this milestone. But this is not mandatory. The auto postpone task will help to not forget opened tickets in closed milestone. The task look for such tickets and postpone them in the more recent still opened milestone. Milestone must have a due date.
     270
     271=== Ticket deadline task
     272
     273'''Note''': since 0.3
     274
     275This task notify to ticket's reporter and owner when its ticket is near the deadline as a custom field. You can add a date field for ticket using [http://trac-hacks.org/wiki/DateFieldPlugin DateFieldPlugin]. Besides scheduler settings, there are the following options to configure when DateFieldPlugin is used:
    283276
    284277 - days_before: notify days before the deadline
    … …  
    288281[[Image(ticket-with-duedate.png)]]
    289282
    290 Here is a sample configuration for trac.ini.
     283Here is a sample configuration for trac.ini:
    291284
    292285{{{
    … …  
    315308}}}
    316309
    317 == Bundled Scheduler ==
    318 
    319 === Hourly scheduler ===
     310== Bundled Scheduler
     311
     312=== Hourly scheduler
    320313
    321314See task scheduling section.
    322315
    323 === Daily scheduler ===
     316=== Daily scheduler
    324317
    325318See task scheduling section.
    326319
    327 === Weekly scheduler ===
     320=== Weekly scheduler
    328321
    329322See task scheduling section.
    330323
    331 === Monthly scheduler ===
     324=== Monthly scheduler
    332325
    333326See task scheduling section.
    334327
    335 === Cron Scheduler ===
    336 
    337 Since 0.2dev_r9375 there is a cron scheduler. You can use cron syntaxe to define the schedule. Currenlty you can use
     328=== Cron Scheduler
     329
     330Since 0.2dev_r9375 there is a cron scheduler. You can use cron syntax to define the schedule. Currenlty you can use:
    338331
    339332 * single value
    … …  
    341334 * special value *
    342335
    343 example with ''heart_beat'' task
     336Example with ''heart_beat'' task:
    344337{{{
    345338#!ini
    … …  
    347340}}}
    348341
    349 '''warning''' : since TracCronPlugin ticker interval is at least one minute, this means the seconds cannot be specified and so the first item of the cron expression is useless.
    350 
    351 The cron like expression is here. Set either day-of-month or day-of-week and the other one must be '?'.
     342'''Warning''': since TracCronPlugin ticker interval is at least one minute, this means the seconds cannot be specified and so the first item of the cron expression is useless.
     343
     344The cron like expression is here. Set either day-of-month or day-of-week and the other one must be '?':
    352345
    353346{{{
    … …  
    365358Please refer to cron documentation for more details [http://en.wikipedia.org/wiki/CRON_expression cron syntax]
    366359
    367 == Bundled Listener ==
    368 
    369 === Email notification of task event ===
    370 
    371 This listener notify by email about task execution. You can choose the number of event sent by email by setting the value of ''email_task_event.limit''. When the listener has received at least the number of task execution,it will send the mail. Default is '''1'''. The value of ''email_task_event.recipient'' '''must''' be filled otherwise no mail will be sent.
    372 
    373 Here the configuration for this listener
     360== Bundled Listener
     361
     362=== Email notification of task event
     363
     364This listener notify by email about task execution. You can choose the number of event sent by email by setting the value of ''email_task_event.limit''. When the listener has received at least the number of task execution, it will send the mail. Default is '''1'''. The value of ''email_task_event.recipient'' '''must''' be filled, otherwise no mail will be sent.
     365
     366Here is the configuration for this listener:
     367
    374368{{{
    375369#!ini
    … …  
    402396
    403397Since 0.2dev_r9385 you can use ''email_task_event.only_error = True'' to send email only on error.
    404 == Recent Changes ==
     398
     399== Recent Changes
    405400
    406401[[ChangeLog(traccronplugin, 3)]]
    407402
    408 == Author/Contributors ==
     403== Author/Contributors
    409404
    410405'''Author:''' [wiki:tbressure] [[BR]]