BoltWire

Pro Modules

Cron

Many servers have something called "cron" (from the greek chronos, which means time). Cron jobs are a way of scheduling repetitive tasks to be triggered at specific times automatically. To use it requires a small bit of technical know how, and access to a server. You also need to have scripts available to run when cron calls them.

The accelerator platform has its own built in cron emulator you can use to run your tasks at specific times. It works much the same way, but without requiring access to a server. And it uses familiar BoltWire markup to run. Here's how it works:

Using Cron

Unlike a server, BoltWire cannot trigger events on it's own. That's the nature of static websites. But fortunately, there are services you can use to "ping" your site every minute or two to monitor its status. One I recommend is http://www.freshping.io. It costs nothing to setup, and comes with the added bonus of getting weekly reports on your site uptime!

Just set the url to www.mydomain.com/cron and enter your email. Save your account information, and any scheduled cron jobs will start running automatically.

Next, you need to set up your cron jobs. This is done on the cron page itself, which should contain content like the following:


Let's break that done, one step at a time. First, you have a number of different cron jobs: expires, renewals, rss, etc. Then you have their frequency for how often they run. And finally a series of numbers used to control when that cron job fires. More on that in a minute.

Last, you have the actual function that calls cron. Think of this as the cron master which calls all the other cron jobs at the appropriate time.

Now back to the numbers. They schedule when each job is to be done. It tells which exact day of the month, or week, and what hour and minute to run the job. So the expires job above will run each month on the 1st of the month as possible after 10:15 AM. The renewals job runs on each week on Wednesday (day 4) right around 9:30 AM or shortly thereafter. The rss job runs each day at 8:30 AM, and the stats job at 9:40 AM. Donations runs about minute 7, once each hour. And the mailer job runs every single time the cron page is called.

I usually stagger the times and days so as to avoid multiple cron jobs being called at the same time, and the server possible timing out. I'd also recommend you tweak your cron page to pick your own times and frequencies for jobs to avoid all our accelerator partners running jobs at the exact same moment!

The first time you run the cron page (either by you loading it, or waiting for freshping.io to ping it), the jobs will each be given a second set of numbers specifying the current month, day, or hour and minute, representing when that job was last done. But no jobs will actually be run this first time--it's just part of the setup process.

The next time you load the cron page however, the cron script checks to see if the cron job is due by looking at when the "last" job was done. Let's say it is September 10 at 10:00, and you have a monthly job set to run on the 10th of each month at 11:00, and the "last" month is flagged as a 8 (August). The job won't trigger because it is not 11 yet. The first time cron is called after 11, the job will trigger and the "last" month will be reset to 9 (the current month). From then on it will skip this job because it is flagged as complete until you get to October. In a similar way, daily jobs show the month and day it was last done, so it won't be triggered twice a day. And hourly jobs show the hour and minute last done so it won't be triggered more than once each hour.

You don't have to understand all the numbers, just set the times you want, and trust cron to figure it out. But you should know that the first monthly job won't be till next month, the first weekly job till next week, the next daily job till tomorrow, etc. This gives you time to gradually start introducing you cron jobs, and make sure everything is working properly without them all starting all at once. You can speed this process up however by resetting the appropriate numbers in the "last" column to the previous month, week, or day.

Cron Jobs

For a cron job to work, there must be a cron job page, like cron.expires or cron.renewals. And that page must contain a function or script that runs some process. Normally, these are special php scripts like <(cronmailer)> or <(cronrenewals)>. You simply put these functions on the cron job page, and the cron master scheduler will call those at the appropriate time.

Typically, these scripts log cron activity to their own log pages as well. So rather than going to cron.mailer (which would actually trigger the mailer cron job on that page) the actual log information for that specific job is stored at cron.mailer.log. The main cron.log page only gives an overview of which jobs were called and when. The job logs give specific information about what each job does, and any error messages. I've included a simple cron dashboard in the site admin area so you can manage your cron jobs more easily.

The default cron job settings include a cron job for mailer (always) which is used to send your outgoing system messages. And another for a test job (hourly) which simply logs calls to the cron.test page, to verify it is being called at the appointed times. That can be switched to different frequencies or turned off completely once you are confident things are working. I will be adding additional cron jobs in time, and as there are requests for it.

There is also a built in cron.indexer page which can be used to index pages in the background. Normally BoltWire checks to see if pages need indexing each time a page is loaded, and will index one page at a time. But this can slow your site down slightly, especially if you have multiple indexes, or very large indexes. In that case, you can create an indexer entry on your cron page (set it to always) and then disable automatic indexing by setting indexing: false on your site.config page. By letting cron manage your indexing, your users can enjoy faster page loads.

Cron Access

For cron to work, the cron page directory should have guest view permissions, as freshping calls your page as a guest, not a member. The cron function should load automatically if you have dynafunc enabled. All cron jobs need to be properly enabled to work.