Differences

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

--- cron_jobs [2025/03/30 18:12] – just removed top notice about still working on this page wtkadmin
+++ cron_jobs [2025/03/30 19:46] (current) – [Background Actions] outlined wtkadmin
@@ Line 91: / Line 91: @@
 ===== 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.
-Details will be added before end of today (March 30th, 2025).
+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>