community.egroupware.org: Community wiki

  
Community wiki
TimedAsyncServices

Timed Asynchron Services vor eGroupWare

This general API interface allows all app's to start tasks at certain times.

Eg. the user should get
  • a notification, if a delegated task in InfoLog is not started / finished at the given start- / endtime (notification not received from the user its delegated to).
  • an alarm from the calendar for a Meeting or for a sheduled Phonecall in InfoLog
  • the backup app should run nightly at 2am.

Installation

For windows follow the installation instructions at TimedAsyncServicesWindows
For MAC OS follow the installation instructions at TimedAsyncServicesMacOs

On a Linux or other *nix system you usualy only have to hit the [Install crontab] button, unless you are using the rpm's provided by EGroupware, which install it automatic via a file in /etc/cron.d

The asyncservices are tested on the following linux-systems now:
The webserver-user 'wwwrun' needs to be included in the group 'trusted', to be able to call the crontab command
  • Debian Woody: tested on the phpgroupware.org by ralfbecker
Problem was the php4-binary is called php4 (not php) and the db-support is not compiled in the cgi-binary by default. This is solved now (the class checks for a php4 binary and loads dl() the db-support).
  • Redhat: acording to ReinerJ?
  • Mandrake: tested
You need to include the webserver-user 'apache' into /etc/cron.allow, to allow the webserver to use the crontab command
You need to include the webserver-user 'apache' into the group 'cron', to allow the webserver to use the crontab command

If you or your system-administrator dont want to give the webserver the right to make "his" own crontab entries. You can do it manualy by adding the following line to your /etc/crontab:
  • /5 * * * * <webserver-user> /usr/bin/php -q <eGW-install-dir>/phpgwapi/cron/asyncservices.php <domain>
Eg. for a standard install on redhat:
  • /5 * * * * apache /usr/bin/php -q /var/www/html/phpgwapi/cron/asyncservices.php default
Now you can log into eGW and go to Admin >> Async Services. As you now manualy installed the crontab entry, you should select Disabled (not recomended) for running the asyncservice. If you hit update, you can check that the asyncservice is (still) called by "crontab".

If you have no PHP CLI or CGI binary installed, you can use wget to execute the file via the webserver:
  • /5 * * * * <webserver-user> /usr/bin/wget -q -O /dev/null
http://localhost/egroupware/phpgwapi/cron/asyncservices.php?domain=default

Please let me know if you have problems with the service or the testjob.

General Documentation

All this can not be done with the normal approach of a web-based application. Some app's have included scripts, to be installed as cron jobs (eg. backup).

The new class offers standard eGW service where all app's can register timer, some data and a callback-methode. That service calls the given methode with the data at the given time (or repetivly), if the timer is not canceled before.

Status of the implemenation

The class is up and running in eGW. By default it is only running in the Fallback mode, which means it only checks for jobs to run after each page-request. This methode should run on any platform. On a linux system the service can be run via cron. To do so, you have to go to Admin -> Async Services and hit [install crontab] (if you havn't do so already). If it shows no errors you should be able to change run async service to 'crontab (recomended)'.
If you get an error-message its probably because your webserver-user is not allowed to use the 'crontab' command. See the next section on how to change that for your distribution.
If the service is installed in the crontab and runs via 'crontab', you can test it by starting the test-job. It sends u a mail every 5min (or what ever times u used when installing it).


How to implement that in a portable (*nix and win) and stable way ?

This can hardly be done in one way only, we need several methodes the admin can choose from and a default that works without further actions:
  1. Fallback Mode: is called on every page-request of any user and checks if any timer is ready to run.
    • Benefits: does not need any special installation
    • Drawbacks: can not garantee a in-time delivery (depending on the user of the whole system), might be a performance penality for big installations
  2. Crontab: admin installs it via phpGW admin -> asyncron services to run every 1, 5, 10, ... minutes.
    • Benefits: garanties delivery times in the given frequenz of the script-calls and is realy asnychron (no user has to wait for the script to do its job)
    • Drawbacks: *nix only, needs the cgi-binary of php and has to be installed by admin (see above)
  3. Service under NT: this could be the NT counterpart for the cronjob -- not yet implemented / I have no win-system ;-)

function set_timer($time,$id,$methode,$data)

$time:
unix timestamp or array('min','hour','day','month','year') with execution time. Repeated events are possible to shedule by setting the array only partly, eg. array('day' => 1) for first day in each month 0am or array('min' => '*/5','hour' => '9-17') for every 5mins in the time from 9am to 5pm.
$id:
unique id to cancel the request later, if necessary. Should be in a form like eg. '<app><id>X' where id is the internal id of app and X might indicate the action.
$methode:
Methode to be called via ExecMethode($methode,$data). $methode has the form '<app>.<class>.<public function>'.
$data:
This data is passed back when the method is called. It might simply be an integer id, but it can also be a complete array.
Returns: False if $id already exists, else True

function cancel_timer($id)

Cancels the timer, $id has to be the one used to set it.
Returns: true if the timer exists and is not expired.

Implementation

DB table

'phpgw_timer' => array(
fd => array(
'id' => array('type' => 'varchar', precission => '255', 'notnull' => 'True'), // unique id
'next' => array('type' => 'int', precission => '4', 'notnull' => 'True'), // the timestamp of the next call
'times' => array('type' => 'varchar', 'precission' => '256', 'default' => ''), // serialized array for repetive timers, $time param
'method' => array('type' => 'varchar', 'precission' => '80', 'notnull' => 'True'), // $method param
'data' => array('type' => 'text') // serialized $data param
),
'pk' => array('id'),
'fk' => array( ),
'ix' => array('next'),
'uc' => array( )
);

General Implemenation

set_timer() calculates the next run of the timer and puts that with the rest of the data in the db.
check_run() is called eg. by the cron-script and querys all timers with expired next time and executes there methode with the given data. If the times field is not empty the next execution time is calculated and the db updated with it, else the row is deleted.
cancel_timer() querys the db for the given id and deletes the row

  • NT/W2K has a at service. This is like the cron daemon. Linux has the at daemon too. (lkneschke)
You are here