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';
26 $spec['domain_id']['api.default'] = CRM_Core_Config
::domainID();
30 * Handle a create mailing ab testing.
32 * @param array $params
37 function civicrm_api3_mailing_a_b_create($params) {
38 return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__
), $params, 'MailingAB');
42 * Handle a delete event.
44 * @param array $params
49 function civicrm_api3_mailing_a_b_delete($params) {
50 return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
56 * @param array $params
60 function civicrm_api3_mailing_a_b_get($params) {
61 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
65 * Adjust Metadata for submit action.
67 * The metadata is used for setting defaults, documentation & validation.
70 * Array of parameters determined by getfields.
72 function _civicrm_api3_mailing_a_b_submit_spec(&$spec) {
73 $mailingFields = CRM_Mailing_DAO_Mailing
::fields();
74 $mailingAbFields = CRM_Mailing_DAO_MailingAB
::fields();
75 $spec['id'] = $mailingAbFields['id'];
76 $spec['status'] = $mailingAbFields['status'];
77 $spec['scheduled_date'] = $mailingFields['scheduled_date'];
78 $spec['approval_date'] = $mailingFields['approval_date'];
79 $spec['approval_status_id'] = $mailingFields['approval_status_id'];
80 $spec['approval_note'] = $mailingFields['approval_note'];
81 $spec['winner_id'] = [
82 'name' => 'winner_id',
84 'title' => 'Winner ID',
85 'description' => 'The experimental mailing with the best results. If specified, values are copied to the final mailing.',
88 // Note: we'll pass through approval_* fields to the underlying mailing, but they may be ignored
89 // if the user doesn't have suitable permission. If separate approvals are required, they must be provided
90 // outside the A/B Test UI.
94 * Send A/B mail to A/B recipients respectively.
96 * @param array $params
99 * @throws API_Exception
101 function civicrm_api3_mailing_a_b_submit($params) {
102 civicrm_api3_verify_mandatory($params, 'CRM_Mailing_DAO_MailingAB', ['id', 'status']);
104 if (!isset($params['scheduled_date']) && !isset($updateParams['approval_date'])) {
105 throw new API_Exception("Missing parameter scheduled_date and/or approval_date");
108 $dao = new CRM_Mailing_DAO_MailingAB();
109 $dao->id
= $params['id'];
110 if (!$dao->find(TRUE)) {
111 throw new API_Exception("Failed to locate A/B test by ID");
113 if (empty($dao->mailing_id_a
) ||
empty($dao->mailing_id_b
) ||
empty($dao->mailing_id_c
)) {
114 throw new API_Exception("Missing mailing IDs for A/B test");
117 $submitParams = CRM_Utils_Array
::subset($params, [
121 'approval_status_id',
124 switch ($params['status']) {
126 if (!empty($dao->status
) && $dao->status
!= 'Draft') {
127 throw new API_Exception("Cannot transition to state 'Testing'");
129 civicrm_api3('Mailing', 'submit', $submitParams +
[
130 'id' => $dao->mailing_id_a
,
131 '_skip_evil_bao_auto_recipients_' => 0,
133 civicrm_api3('Mailing', 'submit', $submitParams +
[
134 'id' => $dao->mailing_id_b
,
135 '_skip_evil_bao_auto_recipients_' => 1,
137 CRM_Mailing_BAO_MailingAB
::distributeRecipients($dao);
141 if ($dao->status
!= 'Testing') {
142 throw new API_Exception("Cannot transition to state 'Final'");
144 if (!empty($params['winner_id'])) {
145 _civicrm_api3_mailing_a_b_fill_winner($params['winner_id'], $dao->mailing_id_c
);
147 civicrm_api3('Mailing', 'submit', $submitParams +
[
148 'id' => $dao->mailing_id_c
,
149 '_skip_evil_bao_auto_recipients_' => 1,
154 throw new API_Exception("Unrecognized submission status");
157 return civicrm_api3('MailingAB', 'create', [
159 'status' => $params['status'],
167 * @param int $winner_id
168 * The experimental mailing chosen as the "winner".
169 * @param int $final_id
170 * The final mailing which should imitate the "winner".
171 * @throws \API_Exception
173 function _civicrm_api3_mailing_a_b_fill_winner($winner_id, $final_id) {
203 $f = CRM_Utils_SQL_Select
::from('civicrm_mailing')
204 ->where('id = #id', ['id' => $winner_id])
205 ->select($copyFields)
208 if (count($f) !== 1) {
209 throw new API_Exception('Invalid winner_id');
211 foreach ($f as $winner) {
212 civicrm_api3('Mailing', 'create', $winner +
[
214 '_skip_evil_bao_auto_recipients_' => 1,
220 * Adjust Metadata for graph_stats action.
222 * The metadata is used for setting defaults, documentation & validation.
224 * @param array $params
225 * Array of parameters determined by getfields.
227 function _civicrm_api3_mailing_a_b_graph_stats_spec(&$params) {
228 $params['criteria'] = [
229 'title' => 'Criteria',
231 'type' => CRM_Utils_Type
::T_STRING
,
234 // mailing_ab_winner_criteria
235 $params['target_date']['title'] = 'Target Date';
236 $params['target_date']['type'] = CRM_Utils_Type
::T_DATE + CRM_Utils_Type
::T_TIME
;
237 $params['split_count'] = [
238 'title' => 'Split Count',
240 'type' => CRM_Utils_Type
::T_INT
,
242 $params['split_count_select']['title'] = 'Split Count Select';
243 $params['split_count_select']['api.required'] = 1;
244 $params['target_url']['title'] = 'Target URL';
248 * Send graph detail for A/B tests mail.
250 * @param array $params
253 * @throws API_Exception
255 function civicrm_api3_mailing_a_b_graph_stats($params) {
256 civicrm_api3_verify_mandatory($params,
257 'CRM_Mailing_DAO_MailingAB',
263 'criteria' => 'Open',
264 'target_date' => CRM_Utils_Time
::getTime('YmdHis'),
266 'split_count_select' => 1,
268 $params = array_merge($defaults, $params);
270 $mailingAB = civicrm_api3('MailingAB', 'getsingle', ['id' => $params['id']]);
272 $ABFormat = ['A' => 'mailing_id_a', 'B' => 'mailing_id_b'];
274 foreach ($ABFormat as $name => $column) {
275 switch (strtolower($params['criteria'])) {
277 $result = CRM_Mailing_Event_BAO_Opened
::getRows($mailingAB['mailing_id_a'], NULL, TRUE, 0, 1, "civicrm_mailing_event_opened.time_stamp ASC");
278 $startDate = CRM_Utils_Date
::processDate($result[0]['date']);
279 $targetDate = CRM_Utils_Date
::processDate($params['target_date']);
280 $dateDuration = round(round(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
281 $toDate = strtotime($startDate) +
($dateDuration * $params['split_count_select']);
282 $toDate = date('YmdHis', $toDate);
283 $graphStats[$name] = [
284 $params['split_count_select'] => [
285 'count' => CRM_Mailing_Event_BAO_Opened
::getTotalCount($mailingAB[$column], NULL, TRUE, $toDate),
286 'time' => CRM_Utils_Date
::customFormat($toDate),
291 case 'total unique clicks':
292 $result = CRM_Mailing_Event_BAO_TrackableURLOpen
::getRows($mailingAB['mailing_id_a'], NULL, TRUE, 0, 1, "civicrm_mailing_event_trackable_url_open.time_stamp ASC");
293 $startDate = CRM_Utils_Date
::processDate($result[0]['date']);
294 $targetDate = CRM_Utils_Date
::processDate($params['target_date']);
295 $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
296 $toDate = strtotime($startDate) +
($dateDuration * $params['split_count_select']);
297 $toDate = date('YmdHis', $toDate);
298 $graphStats[$name] = [
299 $params['split_count_select'] => [
300 'count' => CRM_Mailing_Event_BAO_TrackableURLOpen
::getTotalCount($params['mailing_id'], NULL, FALSE, NULL, $toDate),
301 'time' => CRM_Utils_Date
::customFormat($toDate),
306 case 'total clicks on a particular link':
307 if (empty($params['target_url'])) {
308 throw new API_Exception("Provide url to get stats result for total clicks on a particular link");
310 // FIXME: doesn't make sense to get url_id mailing_id_(a|b) while getting start date in mailing_id_a
311 $url_id = CRM_Mailing_BAO_TrackableURL
::getTrackerURLId($mailingAB[$column], $params['target_url']);
312 $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");
313 $startDate = CRM_Utils_Date
::processDate($result[0]['date']);
314 $targetDate = CRM_Utils_Date
::processDate($params['target_date']);
315 $dateDuration = round(abs(strtotime($targetDate) - strtotime($startDate)) / $params['split_count']);
316 $toDate = strtotime($startDate) +
($dateDuration * $params['split_count_select']);
317 $toDate = CRM_Utils_Date
::processDate($toDate);
318 $graphStats[$name] = [
319 $params['split_count_select'] => [
320 'count' => CRM_Mailing_Event_BAO_TrackableURLOpen
::getTotalCount($params['mailing_id'], NULL, FALSE, $url_id, $toDate),
321 'time' => CRM_Utils_Date
::customFormat($toDate),
328 return civicrm_api3_create_success($graphStats);