| 36 | |
| 37 | === How to write e task === |
| 38 | |
| 39 | You have to write python class that inherit of ICronTask which code is below: |
| 40 | {{{ |
| 41 | #!python |
| 42 | class ICronTask(Interface): |
| 43 | """ |
| 44 | Interface for component task |
| 45 | """ |
| 46 | |
| 47 | def wake_up(self): |
| 48 | """ |
| 49 | Call by the scheduler when the task need to be executed |
| 50 | """ |
| 51 | raise NotImplementedError |
| 52 | |
| 53 | def getId(self): |
| 54 | """ |
| 55 | Return the key to use in trac.ini to cinfigure this task |
| 56 | """ |
| 57 | raise NotImplementedError |
| 58 | |
| 59 | def getDescription(self): |
| 60 | """ |
| 61 | Return the description of this task to be used in the admin panel. |
| 62 | """ |
| 63 | raise NotImplementedError |
| 64 | }}} |
| 65 | |
| 66 | Let's take a look at the heartbeat task packed with TracCronPlugin: |
| 67 | |
| 68 | {{{ |
| 69 | #!python |
| 70 | class HeartBeatTask(Component,ICronTask): |
| 71 | """ |
| 72 | This is a simple task for testing purpose. |
| 73 | It only write a trace in log a debug level |
| 74 | """ |
| 75 | |
| 76 | implements(ICronTask) |
| 77 | |
| 78 | def wake_up(self): |
| 79 | self.env.log.debug("Heart beat: boom boom !!!") |
| 80 | |
| 81 | def getId(self): |
| 82 | return "heart_beat" |
| 83 | |
| 84 | def getDescription(self): |
| 85 | return self.__doc__ |
| 86 | }}} |
| 87 | |
| 88 | You need to implements the interface and to put the definition of the task inside the '''wake_up''' method |
| 89 | |
| 90 | === How to install the task === |
| 91 | |
| 92 | Since task are component you just have to put the class definition of your task in a python module in plugins directory. |
| 93 | 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. |
| 94 | |
| 95 | TracCronPlugin will show up the task in it administration panel. Enjoy ! |
| 96 | |
| 97 | == Configuration == |
| 98 | |
| 99 | The plugin can entirely be configured both witn trac.ini or administration panel. |
| 100 | The section name of TracCronPlugin is traccron, here is a full sample |
| 101 | |
| 102 | {{{ |
| 103 | #!ini |
| 104 | [traccron] |
| 105 | ticker_enabled = True |
| 106 | ticker_interval = 1 |
| 107 | heart_beat.daily = 21h19, 21h20 |
| 108 | heart_beat.daily.enabled = True |
| 109 | heart_beat.enabled = True |
| 110 | heart_beat.hourly = 17, 18 |
| 111 | heart_beat.hourly.enabled = False |
| 112 | heart_beat.monthly = 15@21h15, 15@21h16 |
| 113 | heart_beat.monthly.enabled = False |
| 114 | heart_beat.weekly = 4@21h28, 4@21h29 |
| 115 | heart_beat.weekly.enabled = False |
| 116 | |
| 117 | }}} |
| 118 | |
| 119 | === Global setting === |
| 120 | |
| 121 | {{{ |
| 122 | #!ini |
| 123 | ticker_enabled = True |
| 124 | }}} |
| 125 | |
| 126 | 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 task. Default value is '''True'''. |
| 127 | |
| 128 | {{{ |
| 129 | #!ini |
| 130 | ticker_interval = 1 |
| 131 | }}} |
| 132 | |
| 133 | This key control the interval between each wake up of the ticker. The ticket thread periodically wake up to see if there is task to execute. Then the ticket 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'''. |
| 134 | |
| 135 | |
| 136 | === Task setting === |
| 137 | |
| 138 | For each task loaded by Trac Component manager, Trac Cron Plugin have those parameters. Let's look at hear beat task: |
| 139 | |
| 140 | |
| 141 | {{{ |
| 142 | #!ini |
| 143 | heart_beat.enabled = True |
| 144 | }}} |
| 145 | |
| 146 | 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, wathever schedule the task have, no one will be trigged, 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'''. |
| 147 | |
| 148 | {{{ |
| 149 | #!ini |
| 150 | heart_beat.daily = 21h19, 21h20 |
| 151 | }}} |
| 152 | |
| 153 | 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. |
| 154 | |
| 155 | {{{ |
| 156 | #!ini |
| 157 | heart_beat.daily.enabled = True |
| 158 | }}} |
| 159 | |
| 160 | This enable or disable the daily trigger. If False, the scheduler will not trigger the task. Default is '''True'''. |
| 161 | |
| 162 | {{{ |
| 163 | #!ini |
| 164 | heart_beat.hourly = 17, 18 |
| 165 | }}} |
| 166 | |
| 167 | The goal of this scheduler is to trigger task every hours. You provode minute when you want the task to be executed. Accept comma sparated list of values. Default is no value. |
| 168 | |
| 169 | {{{ |
| 170 | #!ini |
| 171 | heart_beat.hourly.enabled = False |
| 172 | }}} |
| 173 | |
| 174 | This enable or disable the daily trigger. If False, the scheduler will not trigger the task. Default is '''True'''. |
| 175 | |
| 176 | {{{ |
| 177 | #!ini |
| 178 | heart_beat.monthly = 15@21h15, 15@21h16 |
| 179 | }}} |
| 180 | |
| 181 | This sceduler 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 |
| 182 | |
| 183 | {{{ |
| 184 | #!ini |
| 185 | heart_beat.monthly.enabled = False |
| 186 | }}} |
| 187 | |
| 188 | This enable or disable the daily trigger. If False, the scheduler will not trigger the task. Default is '''True'''. |
| 189 | |
| 190 | {{{ |
| 191 | #!ini |
| 192 | heart_beat.weekly = 4@21h28, 4@21h29 |
| 193 | }}} |
| 194 | |
| 195 | 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 |
| 196 | |
| 197 | {{{ |
| 198 | #!ini |
| 199 | heart_beat.weekly.enabled = False |
| 200 | }}} |
| 201 | |
| 202 | This enable or disable the daily trigger. If False, the scheduler will not trigger the task. Default is '''True'''. |