Differences

This shows you the differences between two versions of the page.

--- cron_jobs [2025/03/30 15:15] – starting wtkadmin
+++ cron_jobs [2025/03/30 19:46] (current) – [Background Actions] outlined wtkadmin
@@ Line 1: / Line 1: @@
-This document is in-progress and will be finished later today (3/30/25).
 ====== CRON Jobs ======
@@ Line 7: / Line 5: @@
 ===== Simple Security =====
-To prevent calls from outside sources
+All cron job files are kept in the /cron/ folder.  Of course, you can move these to a different folder as needed.
+WTK has a default robots.txt which tells search engines to ignore the /cron/ folder and other folders which generally should not be crawled, for example the /exports/ folder.  This robots.txt should be uploaded to your root directory of your web server.  Modify it as needed for your specific needs.
+To prevent calls from outside sources to your CRON jobs, a `pw` parameter is required.  The password is specific to your server and you set what you want the password to be in the /wtk/wtkServerInfo.php file.
+<code php>
+$gloAuthStatus = 'setYourUniqueCodeHere';  // guarantees uniqueness for login security level checks
+</code>
+Whatever value you set there, prepend 'wtk' before it when calling your cron jobs.  For example, to trigger the monthly.php cron job you would call it this way:
+<code>
+https://your-domain.com/cron/monthly.php?pw=wtksetYourUniqueCodeHere
+</code>
+===== Example CRON Job Call =====
+Different OS have different calling methods so check with your DevOps and verify the settings used work as expected and meet your security requirements.  This is just one possible way of defining a cron job to call a specific web page:
+<code>
+/usr/bin/curl --silent --insecure --output - https://your-domain.com/cron/minute.php?pw=wtksetYourUniqueCodeHere > /dev/null 2>&1
+</code>
+===== WTK CRON pages =====
+These pages provide a solid starting point for any client.  Each client's needs are going to be very specific, but using these as a starting point gives you a solid framework.
+==== cronTop.php ====
+This page is called by all cron job pages.  Here is where it checks the security and you can enhance the security as-required.  If the calling page sets $gloDebug = 'Y' before the require('cronTop.php') it adds debug code:
+<code php>
+if ($gloDebug == 'Y'):
+    error_reporting(E_ALL | E_STRICT);
+    ini_set('display_errors', 1);
+    $pgSQL = 'INSERT INTO `wtkDebug` (`DevNote`) VALUES (:DevNote)';
+    $pgSqlFilter = array('DevNote' => $gloMyPage . ' called');
+    wtkSqlExec($pgSQL, $pgSqlFilter);
+endif;
+</code>
+This page also starts a timer so during testing you can see how long the cron jobs take.
+==== cronEnd.php ====
+This page is called at the bottom of cron job pages.  If there is $gloDebug information, it displays it.  Then it shows how long the page took to process.
+<code php>
+if ($gloDebug != ''):
+    $pgHtm .= '<hr><h4>Debug</h4>' . $gloDebug . '<hr>' . "\n";
+//  $pgHtm .= '<hr>' . $pgSQL . '<hr>' . "\n";
+endif;
+$pgTimePassed = (((hrtime(true) - $pgStartTime)/1e+6)/1000);
+$pgHtm .= '<br><p>Time it took: ' . $pgTimePassed . ' seconds.</p>' . "\n";
+wtkSearchReplace('col m4 offset-m4 s12','col m6 offset-m3 s12');
+wtkMergePage($pgHtm, 'CRON Jobs', _WTK_RootPATH . '/htm/minibox.htm');
+</code>
+==== monthly.php ====
+This cron job should be called on 1st of each month.  It inserts a row into the `wtkIncomeByMonth` data table based on the `wtkRevenue` data for the prior month.  This `wtkIncomeByMonth` data is used for moneyHistory.php analytic reporting.
+==== nightly.php ====
+After you modify it, this cron job would be called nightly and usually should be set to run some time between 1am and 5am, depending on your client's needs.
+Currently the code has an example of how it could be used for processing monthly payroll on the 16th of the month.  This way you can easily change it for your needs, whether that be triggering payroll on a certain day of the month or other **nightly** activities.
+==== minute.php ====
+This file has the most functional code in it.  All source code is available (as always) so you can easily modify and expand upon it for your needs.
+  * files more than 15 minutes old are deleted from /exports/ folder
+  * wtkNotifications processed and sent via Email or SMS
+  * migration of files from local storage to AWS S3 or Cloudflare R2 (code commented out)
+If you are not using the `wtkNotifications` system, this will have no affect because will be a quick loop through a zero-row table.
+If you are using AWS S3 or Cloudflare R2, with Wizard's Toolkit you can have the files uploaded to a local folder (or AWS EFS) initially since this is fastest.  Then once per minute this **minute.php** cron job will loop through the local files (stored in `wtkFiles` data table), and migrate them to the external storage location.  After it does that, it changes a flag in `wtkFiles` so thereafter when users access the file it pulls the file from S3 or R2.  The settings for your S3 or R2 keys are all in wtk/wtkServerInfo.php.
 ===== Background Actions =====
-These can easily be managed in the data table aptly named `wtkBackgroundActions`.
+These can easily be managed in the data table aptly named `wtkBackgroundActions`.  In the **/cron/backgroundActions.php** page it loops through the background actions that have not been started yet, and processes them based on what their **`ActionType`** is.
+Normally it is recommended to have this be a cron job which processes once per minute.  It could be integrated into the **/cron/minute.php** file, but often the requirements for Background Actions grows over time and thus it deserves it's own separate file for ease of maintenance.
+There are unlimited possibilities for this and since you have the source code you can modify it as needed.  Two standard `ActionType` methods are already defined and working with the starting WTK environment.
+The definition of the `wtkBackgroundActions` table is as follows:
+<code SQL>
+CREATE TABLE `wtkBackgroundActions` (
+  `UID`       INT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `AddDate`   timestamp NOT NULL default CURRENT_TIMESTAMP,
+  `TriggerTime` DATETIME NOT NULL,
+  `StartTime`   DATETIME,
+  `CompletedTime` DATETIME,
+  `ActionType` varchar(20) NOT NULL,
+  `ForUserUID` int UNSIGNED,
+  `Param1UID`  int UNSIGNED,
+  `Param2UID`  int UNSIGNED,
+  `Param1Str`  varchar(20),
+  `Param2Str`  varchar(20),
+  PRIMARY KEY (`UID`),
+  CONSTRAINT `fk_wtkBackgroundActions_ForUserUID`
+    FOREIGN KEY (`ForUserUID`) REFERENCES `wtkUsers`(`UID`),
+  INDEX `ix_wtkBackgroundActions` (`StartTime`, `TriggerTime`),
+  INDEX `ix_wtkBackgroundAction_Param1` (`Param1UID`, `ActionType`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 AUTO_INCREMENT=1;
+</code>
+The backgroundActions.php page loops through the data based on:
+<code SQL>
+WHERE `TriggerTime` < NOW() AND `StartTime` IS NULL
+</code>
+This allows for defining background actions to trigger in the future.  For example, when a sale is made you may want to INSERT INTO `wtkBackgroundActions` rows to trigger future events of:
+  * Thank4Order - to send a thank you email to customer
+  * ExtraWarranty - wait one week then send customer offer to purchase additional warranty
+  * Remind2Pay - if initial order was partial payment, schedule when you want to send them a reminder to finish paying
+When inserting the data into `wtkBackgroundActions` you can fill the Param1UID, Param2UID, Param1Str, Param2Str columns with whatever data you need so in /cron/backgroundActions.php you can do whatever lookups you need to process the background action.
+==== Thank4Order ====
+This `ActionType` has already been defined.  In the initial setup data for Wizard's Toolkit is an insert into the `wtkEmailTemplate` table with a generic email for thanking customers, and it has an `EmailCode` of 'Thank4Order'.  This email template can easily be modified in the WTK back office.
+One example row has been inserted into `wtkBackgroundActions` to show this feature in-action.  Make certain to change the email account of wtkUses.UID = 1 so the email actually reaches someone.  Here is an example of the insert script you could put in a SQL trigger or PHP page that handles your sales.
+<code SQL>
+INSERT INTO `wtkBackgroundActions` (`TriggerTime`, `ActionType`, `ForUserUID`, `Param1UID`, `Param2UID`, `Param1Str`, `Param2Str`)
+ VALUES (NOW(), 'Thank4Order', 1, NULL, NULL, 'SKU123', 'support');
+</code>
+You will want to fill the `ForUserUID` with the `wtkUsers`.`UID` of the customer placing the order.  Then the cron job will lookup their email address and use the data-driven email template to send them an email.
+The value in `Param1Str` will be used to replace the token @SkuNumber@ in both the email Subject and Body from the template.
+For this demo, the `Param2Str` is used as a secondary method of checking how you want to customize the email.  For example, passing 'support' will alter the outbound email one way, and passing 'warranty' will alter it a different way.
+==== SendEmail ====
+Normally it is best to send emails directly but if using slow email processing, you may want to send emails as background action so does not slow down website.  For example, for one client using AWS SES emails can take 2.5 to 4 seconds to process with AWS is busy.  That is just not acceptable if your web page is waiting for email processing.  So having emails sent in the background is a better solution.
+In which case, save email to `wtkEmailsSent` table then insert into `wtkBackgroundActions` as follows:
+<code SQL>
+/*
+Below is PHP:
+$pgUserUID should be the `wtkUsers`.`UID` of the person sending to
+$pgEmailUID should be `wtkEmailsSent`.`UID`
+*/
+INSERT INTO `wtkBackgroundActions` (`TriggerTime`, `ActionType`, `ForUserUID`, `Param1UID`)
+  VALUES (NOW(), 'SendEmail', $pgUserUID, $pgEmailUID);
+</code>