Ecommercen Docs

Appearance

Review Reminder Emails ​

Flow ID: SY-11 | Module(s): job, eshop | Complexity: Medium

Business Overview ​

The review reminder system sends automated emails to customers prompting them to leave reviews on Google, Facebook, or Skroutz after their orders are delivered. Each platform has its own query logic targeting different customer segments (e.g., Skroutz reviews only target Skroutz-referred orders). The job tracks sent reminders in a dedicated table to prevent duplicate emails, and a permission check ensures each customer receives at most one review request per platform.

Architecture ​

AdvSendMailToCustomersForReview (job)
  (requires reviewKey option)
         |
         v
  order_model::sendMailForReviewToCustomers($reviewKey)
         |
         +--- reviewForGoogle ---> getMailsForGoogleReview()
         |                         (4-day delivery window, gtflag check)
         |
         +--- reviewForFacebook -> getMailsForFacebookReview()
         |                         (order date + delivery confirmation)
         |
         +--- reviewForSkroutz --> getMailsForSkroutzReview()
                                   (skroutz_referer=1 + delivery)
         |
         v
  For each eligible customer:
    allowSendEmailForReview() check
         |
         v
    adv_mailer::sendCustomerPromptReview()
         |
         v
    INSERT into shop_customer_reviews (tracking)

Key Components ​

ComponentPathRole
AdvSendMailToCustomersForReviewecommercen/job/libraries/AdvSendMailToCustomersForReview.phpJob: dispatches review reminder flow
Adv_order_modelecommercen/eshop/models/Adv_order_model.phpModel: platform-specific eligible customer queries
Adv_mailerapplication/models/Adv_mailer.phpMailer: sends templated review request emails
allowSendEmailForReview()ecommercen/helpers/shopmodule_helper.phpHelper: duplicate prevention check
Review configapplication/config/app.phpReview platform definitions (IDs and subject keys)
Client stubapplication/modules/job/libraries/SendMailToCustomersForReview.phpEmpty extension point

Code Flow ​

Job Execution ​

  1. Entry: executeCommand(['reviewKey' => $key]) where reviewKey is one of reviewForGoogle, reviewForFacebook, or reviewForSkroutz.
  2. Model dispatch: Calls order_model->sendMailForReviewToCustomers($reviewKey).
  3. Platform routing: A switch on reviewKey calls the appropriate query method. If no valid key is provided, exit(0) terminates immediately.
  4. Per-customer loop: For each eligible customer record:
    • Duplicate check: allowSendEmailForReview($email, $actionId) queries shop_customer_reviews for an existing record with the same email and action ID. Returns true only if no prior record exists.
    • Email send: adv_mailer->sendCustomerPromptReview($customer, $reviewKey) sends the templated email. Subject line is resolved from registry (EMAIL_SUBJECTS group) per platform.
    • Tracking insert: Records {mail, entry_date, action_id} in shop_customer_reviews.

Platform-Specific Queries ​

Google Reviews (getMailsForGoogleReview) ​

  • Date window: Yesterday's deliveries (gtdatetime within previous day's 00:00-23:59).
  • Delivery span filter: Uses DATEDIFF(gtdatetime, entry_datetime) = 4 to target orders delivered exactly 4 days after placement.
  • Conditions: gtflag = 1 (delivery confirmed), email not matching the invalid email pattern.
  • Returns: id, mail, lang per customer (DISTINCT).

Facebook Reviews (getMailsForFacebookReview) ​

  • Order date: 5 days ago (yesterday minus 4 days).
  • Delivery date: Yesterday or later.
  • Conditions: gtflag = 1, status IN (INVOICED, SENT, PAID_SENT), email not matching invalid pattern.
  • Returns: id, mail, lang per customer (DISTINCT).

Skroutz Reviews (getMailsForSkroutzReview) ​

  • Same logic as Facebook with additional filter: skroutz_referer = 1 (order originated from Skroutz marketplace).
  • Returns: id, mail, lang per customer (DISTINCT).

Data Model ​

Tables ​

TableRelevant ColumnsRole
shop_ordercustomer_id, entry_datetime, gtflag, gtdatetime, status, skroutz_refererOrder records with delivery tracking data
shop_customerid, mail, langCustomer contact info and language preference
shop_customer_reviewsmail, entry_date, action_idTracks which review emails have been sent

Review Action IDs ​

Platformaction_idConfig Key
Facebook1reviewForFacebook
Skroutz2reviewForSkroutz
Google3reviewForGoogle

Key Fields ​

FieldTableDescription
gtflagshop_orderBoolean: courier delivery confirmed
gtdatetimeshop_orderTimestamp of courier delivery confirmation
skroutz_referershop_orderBoolean/int: order originated from Skroutz marketplace
entry_datetimeshop_orderOrder placement timestamp

Configuration ​

Application Config: application/config/app.php ​

php
$config['reviews'] = [
    'reviewForFacebook' => ['id' => 1, 'subject' => 'site.emails.prompt_review.facebook'],
    'reviewForSkroutz'  => ['id' => 2, 'subject' => 'site.emails.prompt_review.skroutz'],
    'reviewForGoogle'   => ['id' => 3, 'subject' => 'site.emails.prompt_review.google'],
];

Registry Settings (Email Subjects) ​

GroupKeyDescription
EMAIL_SUBJECTSREVIEW_FOR_FACEBOOKLocalized email subject for Facebook review
EMAIL_SUBJECTSREVIEW_FOR_SKROUTZLocalized email subject for Skroutz review
EMAIL_SUBJECTSREVIEW_FOR_GOOGLELocalized email subject for Google review

Email Templates ​

reviewKeyTemplate View
reviewForFacebookreviewForFacebook (via emailViews->layoutView())
reviewForSkroutzreviewForSkroutz
reviewForGooglereviewForGoogle

Job Options ​

JobOptionTypeRequiredDescription
AdvSendMailToCustomersForReviewreviewKeystringYes (effectively)Platform: reviewForGoogle, reviewForFacebook, or reviewForSkroutz

Note: The job is typically scheduled three times in the cron -- once per platform -- each with a different reviewKey value.

Client Extension Points ​

  • Job override: Create SendMailToCustomersForReview in application/modules/job/libraries/ extending the Adv* base to add custom review platforms or modify query logic.
  • Order model override: Override the getMailsFor*Review() methods in application/models/ to change delivery window, status filters, or add custom conditions.
  • Mailer override: Override sendCustomerPromptReview() in Adv_mailer to customize email content or add platform-specific tracking parameters.
  • Review config: Add new entries to $config['reviews'] in application/config/app.php for additional review platforms.

Business Rules ​

  1. One email per platform per customer: The allowSendEmailForReview() check ensures a customer never receives more than one review request per platform (lifetime, not per order).
  2. 4-day delivery window: Google reviews specifically target orders delivered exactly 4 days after placement (DATEDIFF = 4), ensuring the customer has had time to evaluate the product.
  3. Delivery confirmation required: All platforms require gtflag = 1 (courier delivery confirmed) before sending.
  4. Invalid email exclusion: Sanitized customers (with UUID-based invalid emails) are automatically excluded via the NOT LIKE filter on the invalid email domain.
  5. Skroutz exclusivity: Skroutz review reminders only target orders that originated from the Skroutz marketplace (skroutz_referer = 1).
  6. Language awareness: The customer's lang field is included in query results, enabling the mailer to send localized emails.
  7. No feature toggle: Unlike other email jobs, review reminders have no registry-based enable/disable flag. Scheduling or unscheduling the cron job is the on/off mechanism.
  8. Exit on invalid key: If an invalid or missing reviewKey is provided, the flow calls exit(0) rather than throwing an exception.