Commit | Line | Data |
---|---|---|
4aef704e | 1 | <?php |
4aef704e | 2 | /* |
3 | +--------------------------------------------------------------------+ | |
fee14197 | 4 | | CiviCRM version 5 | |
4aef704e | 5 | +--------------------------------------------------------------------+ |
f299f7db | 6 | | Copyright CiviCRM LLC (c) 2004-2020 | |
4aef704e | 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 | +--------------------------------------------------------------------+ | |
d25dd0ee | 26 | */ |
4aef704e | 27 | |
28 | /** | |
29 | * | |
30 | * APIv3 functions for registering/processing mailing ab testing events. | |
31 | * | |
32 | * @package CiviCRM_APIv3 | |
4aef704e | 33 | */ |
34 | ||
8b06123b TO |
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 | ||
4aef704e | 44 | /** |
1747ab99 | 45 | * Handle a create mailing ab testing. |
4aef704e | 46 | * |
47 | * @param array $params | |
4aef704e | 48 | * |
a6c01b45 | 49 | * @return array |
72b3a70c | 50 | * API Success Array |
4aef704e | 51 | */ |
fd843187 | 52 | function civicrm_api3_mailing_a_b_create($params) { |
a25b46e9 | 53 | return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'MailingAB'); |
4aef704e | 54 | } |
55 | ||
56 | /** | |
57 | * Handle a delete event. | |
58 | * | |
59 | * @param array $params | |
4aef704e | 60 | * |
a6c01b45 | 61 | * @return array |
72b3a70c | 62 | * API Success Array |
4aef704e | 63 | */ |
fd843187 | 64 | function civicrm_api3_mailing_a_b_delete($params) { |
4aef704e | 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 | |
dc64d047 | 72 | * |
4aef704e | 73 | * @return array |
74 | */ | |
fd843187 | 75 | function civicrm_api3_mailing_a_b_get($params) { |
4aef704e | 76 | return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params); |
77 | } | |
78 | ||
7811a84b | 79 | /** |
1747ab99 | 80 | * Adjust Metadata for submit action. |
7811a84b | 81 | * |
0aa0303c EM |
82 | * The metadata is used for setting defaults, documentation & validation. |
83 | * | |
481259e3 | 84 | * @param array $spec |
b081365f | 85 | * Array of parameters determined by getfields. |
7811a84b | 86 | */ |
481259e3 | 87 | function _civicrm_api3_mailing_a_b_submit_spec(&$spec) { |
768c558c TO |
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']; | |
9ee73e80 TO |
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 | ]; | |
768c558c TO |
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. | |
7811a84b | 106 | } |
107 | ||
108 | /** | |
1747ab99 | 109 | * Send A/B mail to A/B recipients respectively. |
7811a84b | 110 | * |
111 | * @param array $params | |
1747ab99 | 112 | * |
7811a84b | 113 | * @return array |
768c558c | 114 | * @throws API_Exception |
7811a84b | 115 | */ |
768c558c | 116 | function civicrm_api3_mailing_a_b_submit($params) { |
cf8f0fff | 117 | civicrm_api3_verify_mandatory($params, 'CRM_Mailing_DAO_MailingAB', ['id', 'status']); |
768c558c TO |
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 | } | |
7811a84b | 122 | |
768c558c TO |
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"); | |
7811a84b | 127 | } |
768c558c TO |
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"); | |
7811a84b | 130 | } |
131 | ||
cf8f0fff | 132 | $submitParams = CRM_Utils_Array::subset($params, [ |
768c558c TO |
133 | 'scheduled_date', |
134 | 'approval_date', | |
135 | 'approval_note', | |
136 | 'approval_status_id', | |
cf8f0fff | 137 | ]); |
768c558c TO |
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 | } | |
cf8f0fff | 144 | civicrm_api3('Mailing', 'submit', $submitParams + [ |
7c31ae57 SL |
145 | 'id' => $dao->mailing_id_a, |
146 | '_skip_evil_bao_auto_recipients_' => 0, | |
147 | ]); | |
cf8f0fff | 148 | civicrm_api3('Mailing', 'submit', $submitParams + [ |
7c31ae57 SL |
149 | 'id' => $dao->mailing_id_b, |
150 | '_skip_evil_bao_auto_recipients_' => 1, | |
151 | ]); | |
768c558c TO |
152 | CRM_Mailing_BAO_MailingAB::distributeRecipients($dao); |
153 | break; | |
7811a84b | 154 | |
768c558c TO |
155 | case 'Final': |
156 | if ($dao->status != 'Testing') { | |
157 | throw new API_Exception("Cannot transition to state 'Final'"); | |
158 | } | |
9ee73e80 TO |
159 | if (!empty($params['winner_id'])) { |
160 | _civicrm_api3_mailing_a_b_fill_winner($params['winner_id'], $dao->mailing_id_c); | |
161 | } | |
cf8f0fff | 162 | civicrm_api3('Mailing', 'submit', $submitParams + [ |
7c31ae57 SL |
163 | 'id' => $dao->mailing_id_c, |
164 | '_skip_evil_bao_auto_recipients_' => 1, | |
165 | ]); | |
768c558c TO |
166 | break; |
167 | ||
168 | default: | |
169 | throw new API_Exception("Unrecognized submission status"); | |
7811a84b | 170 | } |
171 | ||
cf8f0fff | 172 | return civicrm_api3('MailingAB', 'create', [ |
768c558c TO |
173 | 'id' => $dao->id, |
174 | 'status' => $params['status'], | |
cf8f0fff | 175 | 'options' => [ |
768c558c | 176 | 'reload' => 1, |
cf8f0fff CW |
177 | ], |
178 | ]); | |
467cd00c | 179 | } |
180 | ||
9ee73e80 TO |
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', | |
d683bc99 | 213 | 'unsubscribe_id', |
9ee73e80 TO |
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 | ||
467cd00c | 231 | /** |
1747ab99 | 232 | * Adjust Metadata for graph_stats action. |
467cd00c | 233 | * |
0aa0303c EM |
234 | * The metadata is used for setting defaults, documentation & validation. |
235 | * | |
cf470720 | 236 | * @param array $params |
b081365f | 237 | * Array of parameters determined by getfields. |
467cd00c | 238 | */ |
239 | function _civicrm_api3_mailing_a_b_graph_stats_spec(&$params) { | |
cf8f0fff | 240 | $params['criteria'] = [ |
d142432b EM |
241 | 'title' => 'Criteria', |
242 | 'default' => 'Open', | |
243 | 'type' => CRM_Utils_Type::T_STRING, | |
cf8f0fff | 244 | ]; |
d142432b | 245 | |
360aaa75 TO |
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; | |
cf8f0fff | 249 | $params['split_count'] = [ |
d142432b EM |
250 | 'title' => 'Split Count', |
251 | 'api.default' => 6, | |
252 | 'type' => CRM_Utils_Type::T_INT, | |
cf8f0fff | 253 | ]; |
bd6658bd | 254 | $params['split_count_select']['title'] = 'Split Count Select'; |
202ebbab | 255 | $params['split_count_select']['api.required'] = 1; |
360aaa75 | 256 | $params['target_url']['title'] = 'Target URL'; |
202ebbab | 257 | } |
467cd00c | 258 | |
259 | /** | |
1747ab99 | 260 | * Send graph detail for A/B tests mail. |
467cd00c | 261 | * |
262 | * @param array $params | |
1747ab99 | 263 | * |
467cd00c | 264 | * @return array |
360aaa75 | 265 | * @throws API_Exception |
467cd00c | 266 | */ |
267 | function civicrm_api3_mailing_a_b_graph_stats($params) { | |
202ebbab | 268 | civicrm_api3_verify_mandatory($params, |
269 | 'CRM_Mailing_DAO_MailingAB', | |
cf8f0fff | 270 | ['id'], |
202ebbab | 271 | FALSE |
272 | ); | |
467cd00c | 273 | |
cf8f0fff | 274 | $defaults = [ |
360aaa75 TO |
275 | 'criteria' => 'Open', |
276 | 'target_date' => CRM_Utils_Time::getTime('YmdHis'), | |
277 | 'split_count' => 6, | |
278 | 'split_count_select' => 1, | |
cf8f0fff | 279 | ]; |
360aaa75 | 280 | $params = array_merge($defaults, $params); |
202ebbab | 281 | |
cf8f0fff CW |
282 | $mailingAB = civicrm_api3('MailingAB', 'getsingle', ['id' => $params['id']]); |
283 | $graphStats = []; | |
284 | $ABFormat = ['A' => 'mailing_id_a', 'B' => 'mailing_id_b']; | |
467cd00c | 285 | |
202ebbab | 286 | foreach ($ABFormat as $name => $column) { |
360aaa75 TO |
287 | switch (strtolower($params['criteria'])) { |
288 | case 'open': | |
768c558c TO |
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']); | |
360aaa75 TO |
291 | $targetDate = CRM_Utils_Date::processDate($params['target_date']); |
292 | $dateDuration = round(round(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']); | |
202ebbab | 293 | $toDate = strtotime($startDate) + ($dateDuration * $params['split_count_select']); |
294 | $toDate = date('YmdHis', $toDate); | |
cf8f0fff CW |
295 | $graphStats[$name] = [ |
296 | $params['split_count_select'] => [ | |
202ebbab | 297 | 'count' => CRM_Mailing_Event_BAO_Opened::getTotalCount($mailingAB[$column], NULL, TRUE, $toDate), |
21dfd5f5 | 298 | 'time' => CRM_Utils_Date::customFormat($toDate), |
cf8f0fff CW |
299 | ], |
300 | ]; | |
202ebbab | 301 | break; |
ea100cb5 | 302 | |
360aaa75 | 303 | case 'total unique clicks': |
202ebbab | 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']); | |
360aaa75 TO |
306 | $targetDate = CRM_Utils_Date::processDate($params['target_date']); |
307 | $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']); | |
202ebbab | 308 | $toDate = strtotime($startDate) + ($dateDuration * $params['split_count_select']); |
309 | $toDate = date('YmdHis', $toDate); | |
cf8f0fff CW |
310 | $graphStats[$name] = [ |
311 | $params['split_count_select'] => [ | |
202ebbab | 312 | 'count' => CRM_Mailing_Event_BAO_TrackableURLOpen::getTotalCount($params['mailing_id'], NULL, FALSE, NULL, $toDate), |
21dfd5f5 | 313 | 'time' => CRM_Utils_Date::customFormat($toDate), |
cf8f0fff CW |
314 | ], |
315 | ]; | |
202ebbab | 316 | break; |
ea100cb5 | 317 | |
360aaa75 TO |
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"); | |
202ebbab | 321 | } |
360aaa75 TO |
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']); | |
202ebbab | 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']); | |
360aaa75 TO |
326 | $targetDate = CRM_Utils_Date::processDate($params['target_date']); |
327 | $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']); | |
202ebbab | 328 | $toDate = strtotime($startDate) + ($dateDuration * $params['split_count_select']); |
329 | $toDate = CRM_Utils_Date::processDate($toDate); | |
cf8f0fff CW |
330 | $graphStats[$name] = [ |
331 | $params['split_count_select'] => [ | |
202ebbab | 332 | 'count' => CRM_Mailing_Event_BAO_TrackableURLOpen::getTotalCount($params['mailing_id'], NULL, FALSE, $url_id, $toDate), |
21dfd5f5 | 333 | 'time' => CRM_Utils_Date::customFormat($toDate), |
cf8f0fff CW |
334 | ], |
335 | ]; | |
202ebbab | 336 | break; |
337 | } | |
338 | } | |
339 | ||
340 | return civicrm_api3_create_success($graphStats); | |
b0f9e1df | 341 | } |