api/v3/MailingAB.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  *
  30  * APIv3 functions for registering/processing mailing ab testing events.
  31  *
  32  * @package CiviCRM_APIv3
  33  */
  34
  35 /**
  36  * @param array $spec
  37  */
  38 function _civicrm_api3_mailing_a_b_create_spec(&$spec) {
  39   $spec['created_date']['api.default'] = 'now';
  40   $spec['created_id']['api.required'] = 1;
  41   $spec['created_id']['api.default'] = 'user_contact_id';
  42 }
  43
  44 /**
  45  * Handle a create mailing ab testing.
  46  *
  47  * @param array $params
  48  *
  49  * @return array
  50  *   API Success Array
  51  */
  52 function civicrm_api3_mailing_a_b_create($params) {
  53   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'MailingAB');
  54 }
  55
  56 /**
  57  * Handle a delete event.
  58  *
  59  * @param array $params
  60  *
  61  * @return array
  62  *   API Success Array
  63  */
  64 function civicrm_api3_mailing_a_b_delete($params) {
  65   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  66 }
  67
  68 /**
  69  * Handle a get event.
  70  *
  71  * @param array $params
  72  *
  73  * @return array
  74  */
  75 function civicrm_api3_mailing_a_b_get($params) {
  76   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  77 }
  78
  79 /**
  80  * Adjust Metadata for submit action.
  81  *
  82  * The metadata is used for setting defaults, documentation & validation.
  83  *
  84  * @param array $spec
  85  *   Array of parameters determined by getfields.
  86  */
  87 function _civicrm_api3_mailing_a_b_submit_spec(&$spec) {
  88   $mailingFields = CRM_Mailing_DAO_Mailing::fields();
  89   $mailingAbFields = CRM_Mailing_DAO_MailingAB::fields();
  90   $spec['id'] = $mailingAbFields['id'];
  91   $spec['status'] = $mailingAbFields['status'];
  92   $spec['scheduled_date'] = $mailingFields['scheduled_date'];
  93   $spec['approval_date'] = $mailingFields['approval_date'];
  94   $spec['approval_status_id'] = $mailingFields['approval_status_id'];
  95   $spec['approval_note'] = $mailingFields['approval_note'];
  96   $spec['winner_id'] = [
  97     'name' => 'winner_id',
  98     'type' => 1,
  99     'title' => 'Winner ID',
 100     'description' => 'The experimental mailing with the best results. If specified, values are copied to the final mailing.',
 101     'localizable' => 0,
 102   ];
 103   // Note: we'll pass through approval_* fields to the underlying mailing, but they may be ignored
 104   // if the user doesn't have suitable permission. If separate approvals are required, they must be provided
 105   // outside the A/B Test UI.
 106 }
 107
 108 /**
 109  * Send A/B mail to A/B recipients respectively.
 110  *
 111  * @param array $params
 112  *
 113  * @return array
 114  * @throws API_Exception
 115  */
 116 function civicrm_api3_mailing_a_b_submit($params) {
 117   civicrm_api3_verify_mandatory($params, 'CRM_Mailing_DAO_MailingAB', ['id', 'status']);
 118
 119   if (!isset($params['scheduled_date']) && !isset($updateParams['approval_date'])) {
 120     throw new API_Exception("Missing parameter scheduled_date and/or approval_date");
 121   }
 122
 123   $dao = new CRM_Mailing_DAO_MailingAB();
 124   $dao->id = $params['id'];
 125   if (!$dao->find(TRUE)) {
 126     throw new API_Exception("Failed to locate A/B test by ID");
 127   }
 128   if (empty($dao->mailing_id_a) || empty($dao->mailing_id_b) || empty($dao->mailing_id_c)) {
 129     throw new API_Exception("Missing mailing IDs for A/B test");
 130   }
 131
 132   $submitParams = CRM_Utils_Array::subset($params, [
 133     'scheduled_date',
 134     'approval_date',
 135     'approval_note',
 136     'approval_status_id',
 137   ]);
 138
 139   switch ($params['status']) {
 140     case 'Testing':
 141       if (!empty($dao->status) && $dao->status != 'Draft') {
 142         throw new API_Exception("Cannot transition to state 'Testing'");
 143       }
 144       civicrm_api3('Mailing', 'submit', $submitParams + [
 145         'id' => $dao->mailing_id_a,
 146         '_skip_evil_bao_auto_recipients_' => 0,
 147       ]);
 148       civicrm_api3('Mailing', 'submit', $submitParams + [
 149         'id' => $dao->mailing_id_b,
 150         '_skip_evil_bao_auto_recipients_' => 1,
 151       ]);
 152       CRM_Mailing_BAO_MailingAB::distributeRecipients($dao);
 153       break;
 154
 155     case 'Final':
 156       if ($dao->status != 'Testing') {
 157         throw new API_Exception("Cannot transition to state 'Final'");
 158       }
 159       if (!empty($params['winner_id'])) {
 160         _civicrm_api3_mailing_a_b_fill_winner($params['winner_id'], $dao->mailing_id_c);
 161       }
 162       civicrm_api3('Mailing', 'submit', $submitParams + [
 163         'id' => $dao->mailing_id_c,
 164         '_skip_evil_bao_auto_recipients_' => 1,
 165       ]);
 166       break;
 167
 168     default:
 169       throw new API_Exception("Unrecognized submission status");
 170   }
 171
 172   return civicrm_api3('MailingAB', 'create', [
 173     'id' => $dao->id,
 174     'status' => $params['status'],
 175     'options' => [
 176       'reload' => 1,
 177     ],
 178   ]);
 179 }
 180
 181 /**
 182  * @param int $winner_id
 183  *   The experimental mailing chosen as the "winner".
 184  * @param int $final_id
 185  *   The final mailing which should imitate the "winner".
 186  * @throws \API_Exception
 187  */
 188 function _civicrm_api3_mailing_a_b_fill_winner($winner_id, $final_id) {
 189   $copyFields = [
 190     // 'id',
 191     // 'name',
 192     'campaign_id',
 193     'from_name',
 194     'from_email',
 195     'replyto_email',
 196     'subject',
 197     'dedupe_email',
 198     // 'recipients',
 199     'body_html',
 200     'body_text',
 201     'footer_id',
 202     'header_id',
 203     'visibility',
 204     'url_tracking',
 205     'dedupe_email',
 206     'forward_replies',
 207     'auto_responder',
 208     'open_tracking',
 209     'override_verp',
 210     'optout_id',
 211     'reply_id',
 212     'resubscribe_id',
 213     'unsubscribe_id'
 214   ];
 215   $f = CRM_Utils_SQL_Select::from('civicrm_mailing')
 216     ->where('id = #id', ['id' => $winner_id])
 217     ->select($copyFields)
 218     ->execute()
 219     ->fetchAll();
 220   if (count($f) !== 1) {
 221     throw new API_Exception('Invalid winner_id');
 222   }
 223   foreach ($f as $winner) {
 224     civicrm_api3('Mailing', 'create', $winner + [
 225       'id' => $final_id,
 226       '_skip_evil_bao_auto_recipients_' => 1,
 227     ]);
 228   }
 229 }
 230
 231 /**
 232  * Adjust Metadata for graph_stats action.
 233  *
 234  * The metadata is used for setting defaults, documentation & validation.
 235  *
 236  * @param array $params
 237  *   Array of parameters determined by getfields.
 238  */
 239 function _civicrm_api3_mailing_a_b_graph_stats_spec(&$params) {
 240   $params['criteria'] = [
 241     'title' => 'Criteria',
 242     'default' => 'Open',
 243     'type' => CRM_Utils_Type::T_STRING,
 244   ];
 245
 246   // mailing_ab_winner_criteria
 247   $params['target_date']['title'] = 'Target Date';
 248   $params['target_date']['type'] = CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME;
 249   $params['split_count'] = [
 250     'title' => 'Split Count',
 251     'api.default' => 6,
 252     'type' => CRM_Utils_Type::T_INT,
 253   ];
 254   $params['split_count_select']['title'] = 'Split Count Select';
 255   $params['split_count_select']['api.required'] = 1;
 256   $params['target_url']['title'] = 'Target URL';
 257 }
 258
 259 /**
 260  * Send graph detail for A/B tests mail.
 261  *
 262  * @param array $params
 263  *
 264  * @return array
 265  * @throws API_Exception
 266  */
 267 function civicrm_api3_mailing_a_b_graph_stats($params) {
 268   civicrm_api3_verify_mandatory($params,
 269     'CRM_Mailing_DAO_MailingAB',
 270     ['id'],
 271     FALSE
 272   );
 273
 274   $defaults = [
 275     'criteria' => 'Open',
 276     'target_date' => CRM_Utils_Time::getTime('YmdHis'),
 277     'split_count' => 6,
 278     'split_count_select' => 1,
 279   ];
 280   $params = array_merge($defaults, $params);
 281
 282   $mailingAB = civicrm_api3('MailingAB', 'getsingle', ['id' => $params['id']]);
 283   $graphStats = [];
 284   $ABFormat = ['A' => 'mailing_id_a', 'B' => 'mailing_id_b'];
 285
 286   foreach ($ABFormat as $name => $column) {
 287     switch (strtolower($params['criteria'])) {
 288       case 'open':
 289         $result = CRM_Mailing_Event_BAO_Opened::getRows($mailingAB['mailing_id_a'], NULL, TRUE, 0, 1, "civicrm_mailing_event_opened.time_stamp ASC");
 290         $startDate = CRM_Utils_Date::processDate($result[0]['date']);
 291         $targetDate = CRM_Utils_Date::processDate($params['target_date']);
 292         $dateDuration = round(round(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
 293         $toDate = strtotime($startDate) + ($dateDuration * $params['split_count_select']);
 294         $toDate = date('YmdHis', $toDate);
 295         $graphStats[$name] = [
 296           $params['split_count_select'] => [
 297             'count' => CRM_Mailing_Event_BAO_Opened::getTotalCount($mailingAB[$column], NULL, TRUE, $toDate),
 298             'time' => CRM_Utils_Date::customFormat($toDate),
 299           ],
 300         ];
 301         break;
 302
 303       case 'total unique clicks':
 304         $result = CRM_Mailing_Event_BAO_TrackableURLOpen::getRows($mailingAB['mailing_id_a'], NULL, TRUE, 0, 1, "civicrm_mailing_event_trackable_url_open.time_stamp ASC");
 305         $startDate = CRM_Utils_Date::processDate($result[0]['date']);
 306         $targetDate = CRM_Utils_Date::processDate($params['target_date']);
 307         $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
 308         $toDate = strtotime($startDate) + ($dateDuration * $params['split_count_select']);
 309         $toDate = date('YmdHis', $toDate);
 310         $graphStats[$name] = [
 311           $params['split_count_select'] => [
 312             'count' => CRM_Mailing_Event_BAO_TrackableURLOpen::getTotalCount($params['mailing_id'], NULL, FALSE, NULL, $toDate),
 313             'time' => CRM_Utils_Date::customFormat($toDate),
 314           ],
 315         ];
 316         break;
 317
 318       case 'total clicks on a particular link':
 319         if (empty($params['target_url'])) {
 320           throw new API_Exception("Provide url to get stats result for total clicks on a particular link");
 321         }
 322         // FIXME: doesn't make sense to get url_id mailing_id_(a|b) while getting start date in mailing_id_a
 323         $url_id = CRM_Mailing_BAO_TrackableURL::getTrackerURLId($mailingAB[$column], $params['target_url']);
 324         $result = CRM_Mailing_Event_BAO_TrackableURLOpen::getRows($mailingAB['mailing_id_a'], NULL, FALSE, $url_id, 0, 1, "civicrm_mailing_event_trackable_url_open.time_stamp ASC");
 325         $startDate = CRM_Utils_Date::processDate($result[0]['date']);
 326         $targetDate = CRM_Utils_Date::processDate($params['target_date']);
 327         $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
 328         $toDate = strtotime($startDate) + ($dateDuration * $params['split_count_select']);
 329         $toDate = CRM_Utils_Date::processDate($toDate);
 330         $graphStats[$name] = [
 331           $params['split_count_select'] => [
 332             'count' => CRM_Mailing_Event_BAO_TrackableURLOpen::getTotalCount($params['mailing_id'], NULL, FALSE, $url_id, $toDate),
 333             'time' => CRM_Utils_Date::customFormat($toDate),
 334           ],
 335         ];
 336         break;
 337     }
 338   }
 339
 340   return civicrm_api3_create_success($graphStats);
 341 }