Running scheduled tasks in SeedDMS
Whenever lots of data is managed like SeedDMS does it, there is sooner or later a need for running certain task, e.g. to do clean ups or update operations, or simply to check for data changes occured over the past. One of the rather obious operations in SeedDMS is checking for expired documents. But there are others, like informing users about reviews or approvals to be due or updating the full text index. None of them would ever be done without an external trigger, because a web application is not a constantly running process doing all the above at recurring intervals. A document in SeedDMS, which has expired some time ago, will not change its status to expired unless a user accesses that document and forces SeedDMS to check the expiration date again. If you were looking at the database, you would see a document remaining in its old state. In most cases this is just fine, because nobody actually cares about the status of a document unless it is being accessed. But there are other cases where it makes a difference. The full text index, which also stores the status of a document, will not be aware of the expired documents, unless it is updated regulary. That’s why the so called scheduler was added in SeedDMS 6.
The scheduler in SeedDMS manages those task which need to be run regulary. It is much like a cron daemon on Unix systems and actually the way to schedule a task has been borrowed from crond.
SeedDMS 6 already ships with a small number of tasks, which need to be configured and activated to be of any use.
- finding expired documents and informing the owner
- updating or recreating the full text index
- checking for an incorrect checksum of a document
- checking for missing preview images
- checking for upcomming events in the calendar and informing the owner of the event
Many of the available extensions add more task of this kind, e.g. to import mail attachments, checking for due reviѕions, emptying the trash can, etc.
If you have ever looked into the directory
utils of your SeedDMS
installation, you will find some php scripts which do excatly what the tasks
above do. In the past those scripts had to be called individually by a cron job. Hence,
each task needs its own cron job. The scheduler comprises all tasks into one
cron job, by just calling
utils/seeddms-schedulercli. All the remaining
configuration and activation of a task can be done within SeedDMS.
Configuring the scheduler
The scheduler itself also is not a constantly running process, it must be run by a cronjob with the same user running your webserver
*/5 * * * * /home/seeddms/utils/seeddms-schedulercli --mode=run
In this particular case it is run every 5 minutes. It could be less or more time between the runs, but keep in mind that this is also the minimum time between two runs of a task. If you configure a task to run every minute, it will not do it if the scheduler is run every 5 minutes.
The scheduler will not run unless a user
cli_scheduler exists in SeedDMS. This
user will be the one used to access the documents and folders. Hence, it should
have sufficient access rights.
Thought the scheduler script
seeddms-schedulercli is usually called from
a cronjob it can also be called on the command line. This can be very helpful
for debugging. In that case it’s worth to have a look at the different options
which can be passed on the command line. Just run the script with the option
to get a list of possible command line parameters. Always run the scheduler with
the same user like your web server user, otherwise files created by any of the
tasks may not be changable later (e.g. the full text index if recreated). On
Debian would usually run
sudo -u www-data utils/seeddms-schedulercli --mode=run
In case SeedDMS’ configuration file cannot be found, then just specify the full
path of the configuration file with the command line option
What if you can’t run it as a cronjob
There are cases where you cannot run the scheduler by a cron daemon.
That’s why the page
op/op.Cron.php exists. Calling this page with
mode=run will be identical to running
utils/seeddms-schedulercli --mode=run. The result of that call
is a json data object with information about each task. You may
evaluate it, but often it’s sufficient to check for the http status
code 200, whether the execution of the scheduler was successful or not.
The page uses basic authentication and requires to log in as user
Configuring a task
Each task itself is configured in SeedDMS. Just click on the button ‘Scheduler’
in the admin area. The page will list all available task classes. It’s
important to recognize the difference between the task class and it’s
instantiation. It’s very much like objects and classes in object oriented
programming. The task classes shipped with SeedDMS all start with
Extensions should use its extension name as prefix followed by
The first step to run a task is chosing one of the task classes and
clicking on the
+ button. It will open a form next to the list of
task classes. The first four fields of the form are identical for all
tasks. The name and the frequency are mandatory. The frequency
follows the same syntax like the first five numbers in a crontab. It
also understand the terms
@hourly which mean excatly
what the say. The fourth parameter Disabled can be use to activate
or deactive a task. If there are more fields in the form, then they
are specific for the task. Those extra parameters explain, why there
can be more tasks derived from the same task class. They do different
things depending on the parameters. A common scenario is to have two
task base on the class
core::indexingdocs. One running more
frequently with the parameter recreate not being checked and a second
task, running e.g. once a week, to recreate the whole full text index.
Once you have created the first task it will appear in another table below the task classes. Those task which are activated will have a green background all other task are white. Besides the name, description, class and frequency of a task, it also shows the time of the last and next run. Tasks which have been deactived may have a time for the next run a long time ago. If such as task is activated again, it will be run the next time the scheduler is run.
Most installations of SeedDMS get along without tasks, but sooner or later your users will request reminders, status reports, monitoring, etc. or your daily administrative duties become too boring. Than it’s time to automate things with periodically run tasks. A good starting point might be the example extension in SeedDMS.