3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
14 * APIv3 functions for registering/processing mailing ab testing events.
16 * @package CiviCRM_APIv3
22 function _civicrm_api3_mailing_a_b_create_spec(&$spec) {
23 $spec['created_date']['api.default'] = 'now';
24 $spec['created_id']['api.required'] = 1;
25 $spec['created_id']['api.default'] = 'user_contact_id';
29 * Handle a create mailing ab testing.
31 * @param array $params
36 function civicrm_api3_mailing_a_b_create($params) {
37 return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__
), $params, 'MailingAB');
41 * Handle a delete event.
43 * @param array $params
48 function civicrm_api3_mailing_a_b_delete($params) {
49 return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
55 * @param array $params
59 function civicrm_api3_mailing_a_b_get($params) {
60 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
64 * Adjust Metadata for submit action.
66 * The metadata is used for setting defaults, documentation & validation.
69 * Array of parameters determined by getfields.
71 function _civicrm_api3_mailing_a_b_submit_spec(&$spec) {
72 $mailingFields = CRM_Mailing_DAO_Mailing
::fields();
73 $mailingAbFields = CRM_Mailing_DAO_MailingAB
::fields();
74 $spec['id'] = $mailingAbFields['id'];
75 $spec['status'] = $mailingAbFields['status'];
76 $spec['scheduled_date'] = $mailingFields['scheduled_date'];
77 $spec['approval_date'] = $mailingFields['approval_date'];
78 $spec['approval_status_id'] = $mailingFields['approval_status_id'];
79 $spec['approval_note'] = $mailingFields['approval_note'];
80 $spec['winner_id'] = [
81 'name' => 'winner_id',
83 'title' => 'Winner ID',
84 'description' => 'The experimental mailing with the best results. If specified, values are copied to the final mailing.',
87 // Note: we'll pass through approval_* fields to the underlying mailing, but they may be ignored
88 // if the user doesn't have suitable permission. If separate approvals are required, they must be provided
89 // outside the A/B Test UI.
93 * Send A/B mail to A/B recipients respectively.
95 * @param array $params
98 * @throws API_Exception
100 function civicrm_api3_mailing_a_b_submit($params) {
101 civicrm_api3_verify_mandatory($params, 'CRM_Mailing_DAO_MailingAB', ['id', 'status']);
103 if (!isset($params['scheduled_date']) && !isset($updateParams['approval_date'])) {
104 throw new API_Exception("Missing parameter scheduled_date and/or approval_date");
107 $dao = new CRM_Mailing_DAO_MailingAB();
108 $dao->id
= $params['id'];
109 if (!$dao->find(TRUE)) {
110 throw new API_Exception("Failed to locate A/B test by ID");
112 if (empty($dao->mailing_id_a
) ||
empty($dao->mailing_id_b
) ||
empty($dao->mailing_id_c
)) {
113 throw new API_Exception("Missing mailing IDs for A/B test");
116 $submitParams = CRM_Utils_Array
::subset($params, [
120 'approval_status_id',
123 switch ($params['status']) {
125 if (!empty($dao->status
) && $dao->status
!= 'Draft') {
126 throw new API_Exception("Cannot transition to state 'Testing'");
128 civicrm_api3('Mailing', 'submit', $submitParams +
[
129 'id' => $dao->mailing_id_a
,
130 '_skip_evil_bao_auto_recipients_' => 0,
132 civicrm_api3('Mailing', 'submit', $submitParams +
[
133 'id' => $dao->mailing_id_b
,
134 '_skip_evil_bao_auto_recipients_' => 1,
136 CRM_Mailing_BAO_MailingAB
::distributeRecipients($dao);
140 if ($dao->status
!= 'Testing') {
141 throw new API_Exception("Cannot transition to state 'Final'");
143 if (!empty($params['winner_id'])) {
144 _civicrm_api3_mailing_a_b_fill_winner($params['winner_id'], $dao->mailing_id_c
);
146 civicrm_api3('Mailing', 'submit', $submitParams +
[
147 'id' => $dao->mailing_id_c
,
148 '_skip_evil_bao_auto_recipients_' => 1,
153 throw new API_Exception("Unrecognized submission status");
156 return civicrm_api3('MailingAB', 'create', [
158 'status' => $params['status'],
166 * @param int $winner_id
167 * The experimental mailing chosen as the "winner".
168 * @param int $final_id
169 * The final mailing which should imitate the "winner".
170 * @throws \API_Exception
172 function _civicrm_api3_mailing_a_b_fill_winner($winner_id, $final_id) {
199 $f = CRM_Utils_SQL_Select
::from('civicrm_mailing')
200 ->where('id = #id', ['id' => $winner_id])
201 ->select($copyFields)
204 if (count($f) !== 1) {
205 throw new API_Exception('Invalid winner_id');
207 foreach ($f as $winner) {
208 civicrm_api3('Mailing', 'create', $winner +
[
210 '_skip_evil_bao_auto_recipients_' => 1,
216 * Adjust Metadata for graph_stats action.
218 * The metadata is used for setting defaults, documentation & validation.
220 * @param array $params
221 * Array of parameters determined by getfields.
223 function _civicrm_api3_mailing_a_b_graph_stats_spec(&$params) {
224 $params['criteria'] = [
225 'title' => 'Criteria',
227 'type' => CRM_Utils_Type
::T_STRING
,
230 // mailing_ab_winner_criteria
231 $params['target_date']['title'] = 'Target Date';
232 $params['target_date']['type'] = CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
;
233 $params['split_count'] = [
234 'title' => 'Split Count',
236 'type' => CRM_Utils_Type
::T_INT
,
238 $params['split_count_select']['title'] = 'Split Count Select';
239 $params['split_count_select']['api.required'] = 1;
240 $params['target_url']['title'] = 'Target URL';
244 * Send graph detail for A/B tests mail.
246 * @param array $params
249 * @throws API_Exception
251 function civicrm_api3_mailing_a_b_graph_stats($params) {
252 civicrm_api3_verify_mandatory($params,
253 'CRM_Mailing_DAO_MailingAB',
259 'criteria' => 'Open',
260 'target_date' => CRM_Utils_Time
::getTime('YmdHis'),
262 'split_count_select' => 1,
264 $params = array_merge($defaults, $params);
266 $mailingAB = civicrm_api3('MailingAB', 'getsingle', ['id' => $params['id']]);
268 $ABFormat = ['A' => 'mailing_id_a', 'B' => 'mailing_id_b'];
270 foreach ($ABFormat as $name => $column) {
271 switch (strtolower($params['criteria'])) {
273 $result = CRM_Mailing_Event_BAO_Opened
::getRows($mailingAB['mailing_id_a'], NULL, TRUE, 0, 1, "civicrm_mailing_event_opened.time_stamp ASC");
274 $startDate = CRM_Utils_Date
::processDate($result[0]['date']);
275 $targetDate = CRM_Utils_Date
::processDate($params['target_date']);
276 $dateDuration = round(round(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
277 $toDate = strtotime($startDate) +
($dateDuration * $params['split_count_select']);
278 $toDate = date('YmdHis', $toDate);
279 $graphStats[$name] = [
280 $params['split_count_select'] => [
281 'count' => CRM_Mailing_Event_BAO_Opened
::getTotalCount($mailingAB[$column], NULL, TRUE, $toDate),
282 'time' => CRM_Utils_Date
::customFormat($toDate),
287 case 'total unique clicks':
288 $result = CRM_Mailing_Event_BAO_TrackableURLOpen
::getRows($mailingAB['mailing_id_a'], NULL, TRUE, 0, 1, "civicrm_mailing_event_trackable_url_open.time_stamp ASC");
289 $startDate = CRM_Utils_Date
::processDate($result[0]['date']);
290 $targetDate = CRM_Utils_Date
::processDate($params['target_date']);
291 $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
292 $toDate = strtotime($startDate) +
($dateDuration * $params['split_count_select']);
293 $toDate = date('YmdHis', $toDate);
294 $graphStats[$name] = [
295 $params['split_count_select'] => [
296 'count' => CRM_Mailing_Event_BAO_TrackableURLOpen
::getTotalCount($params['mailing_id'], NULL, FALSE, NULL, $toDate),
297 'time' => CRM_Utils_Date
::customFormat($toDate),
302 case 'total clicks on a particular link':
303 if (empty($params['target_url'])) {
304 throw new API_Exception("Provide url to get stats result for total clicks on a particular link");
306 // FIXME: doesn't make sense to get url_id mailing_id_(a|b) while getting start date in mailing_id_a
307 $url_id = CRM_Mailing_BAO_TrackableURL
::getTrackerURLId($mailingAB[$column], $params['target_url']);
308 $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");
309 $startDate = CRM_Utils_Date
::processDate($result[0]['date']);
310 $targetDate = CRM_Utils_Date
::processDate($params['target_date']);
311 $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
312 $toDate = strtotime($startDate) +
($dateDuration * $params['split_count_select']);
313 $toDate = CRM_Utils_Date
::processDate($toDate);
314 $graphStats[$name] = [
315 $params['split_count_select'] => [
316 'count' => CRM_Mailing_Event_BAO_TrackableURLOpen
::getTotalCount($params['mailing_id'], NULL, FALSE, $url_id, $toDate),
317 'time' => CRM_Utils_Date
::customFormat($toDate),
324 return civicrm_api3_create_success($graphStats);