3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2019 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
29 * This api is used for working with scheduled "cron" jobs.
31 * @package CiviCRM_APIv3
35 * Adjust metadata for "Create" action.
37 * The metadata is used for setting defaults, documentation & validation.
39 * @param array $params
40 * Array of parameters determined by getfields.
42 function _civicrm_api3_job_create_spec(&$params) {
43 $params['run_frequency']['api.required'] = 1;
44 $params['name']['api.required'] = 1;
45 $params['api_entity']['api.required'] = 1;
46 $params['api_action']['api.required'] = 1;
48 $params['domain_id']['api.default'] = CRM_Core_Config
::domainID();
49 $params['is_active']['api.default'] = 1;
53 * Create scheduled job.
55 * @param array $params
56 * Associative array of property name/value pairs to insert in new job.
60 function civicrm_api3_job_create($params) {
61 return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__
), $params, 'Job');
65 * Adjust metadata for clone spec action.
69 function _civicrm_api3_job_clone_spec(&$spec) {
70 $spec['id']['title'] = 'Job ID to clone';
71 $spec['id']['type'] = CRM_Utils_Type
::T_INT
;
72 $spec['id']['api.required'] = 1;
73 $spec['is_active']['title'] = 'Job is Active?';
74 $spec['is_active']['type'] = CRM_Utils_Type
::T_BOOLEAN
;
75 $spec['is_active']['api.required'] = 0;
81 * @param array $params
84 * @throws \API_Exception
85 * @throws \CiviCRM_API3_Exception
87 function civicrm_api3_job_clone($params) {
88 if (empty($params['id'])) {
89 throw new API_Exception("Mandatory key(s) missing from params array: id field is required");
93 $params['last_run'] = 'null';
94 $params['scheduled_run_date'] = 'null';
95 $newJobDAO = CRM_Core_BAO_Job
::copy($id, $params);
96 return civicrm_api3('Job', 'get', array('id' => $newJobDAO->id
));
100 * Retrieve one or more job.
102 * @param array $params
107 function civicrm_api3_job_get($params) {
108 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
114 * @param array $params
116 function civicrm_api3_job_delete($params) {
117 _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
121 * Dumb wrapper to execute scheduled jobs.
123 * Always creates success - errors and results are handled in the job log.
125 * @param array $params
126 * input parameters (unused).
131 function civicrm_api3_job_execute($params) {
133 $facility = new CRM_Core_JobManager();
134 $facility->execute(FALSE);
136 // Always creates success - results are handled elsewhere.
137 return civicrm_api3_create_success(1, $params, 'Job');
141 * Adjust Metadata for Execute action.
143 * @param array $params
144 * Array of parameters determined by getfields.
146 function _civicrm_api3_job_execute_spec(&$params) {
150 * Geocode group of contacts based on given params.
152 * @param array $params
158 function civicrm_api3_job_geocode($params) {
159 $gc = new CRM_Utils_Address_BatchUpdate($params);
161 $result = $gc->run();
163 if ($result['is_error'] == 0) {
164 return civicrm_api3_create_success($result['messages']);
167 return civicrm_api3_create_error($result['messages']);
172 * First check on Code documentation.
174 * @param array $params
176 function _civicrm_api3_job_geocode_spec(&$params) {
177 $params['start'] = array(
178 'title' => 'Starting Contact ID',
179 'type' => CRM_Utils_Type
::T_INT
,
181 $params['end'] = array(
182 'title' => 'Ending Contact ID',
183 'type' => CRM_Utils_Type
::T_INT
,
185 $params['geocoding'] = array(
186 'title' => 'Geocode address?',
187 'type' => CRM_Utils_Type
::T_BOOLEAN
,
189 $params['parse'] = array(
190 'title' => 'Parse street address?',
191 'type' => CRM_Utils_Type
::T_BOOLEAN
,
193 $params['throttle'] = array(
194 'title' => 'Throttle?',
195 'description' => 'If enabled, geo-codes at a slow rate',
196 'type' => CRM_Utils_Type
::T_BOOLEAN
,
201 * Send the scheduled reminders for all contacts (either for activities or events).
203 * @param array $params
204 * (reference ) input parameters.
205 * now - the time to use, in YmdHis format
206 * - makes testing a bit simpler since we can simulate past/future time
210 function civicrm_api3_job_send_reminder($params) {
211 //note that $params['rowCount' can be overridden by one of the preferred syntaxes ($options['limit'] = x
212 //It's not clear whether than syntax can be passed in via the UI config - but this keeps the pre 4.4.4 behaviour
213 // in that case (ie. makes it non-configurable via the UI). Another approach would be to set a default of 0
214 // in the _spec function - but since that is a deprecated value it seems more contentious than this approach
215 $params['rowCount'] = 0;
216 $lock = Civi
::lockManager()->acquire('worker.core.ActionSchedule');
217 if (!$lock->isAcquired()) {
218 return civicrm_api3_create_error('Could not acquire lock, another ActionSchedule process is running');
221 $result = CRM_Core_BAO_ActionSchedule
::processQueue(CRM_Utils_Array
::value('now', $params), $params);
224 if ($result['is_error'] == 0) {
225 return civicrm_api3_create_success();
228 return civicrm_api3_create_error($result['messages']);
232 * Adjust metadata for "send_reminder" action.
234 * The metadata is used for setting defaults, documentation & validation.
236 * @param array $params
237 * Array of parameters determined by getfields.
239 function _civicrm_api3_job_send_reminder(&$params) {
240 //@todo this function will now take all fields in action_schedule as params
241 // as it is calling the api fn to set the filters - update getfields to reflect
242 $params['id'] = array(
243 'type' => CRM_Utils_Type
::T_INT
,
244 'title' => 'Action Schedule ID',
248 * Execute a specific report instance and send the output via email.
250 * @param array $params
251 * (reference ) input parameters.
252 * sendmail - Boolean - should email be sent?, required
253 * instanceId - Integer - the report instance ID
254 * resetVal - Integer - should we reset form state (always true)?
258 function civicrm_api3_job_mail_report($params) {
259 $result = CRM_Report_Utils_Report
::processReport($params);
261 if ($result['is_error'] == 0) {
262 // this should be handling by throwing exceptions but can't remove until we can test that.
263 return civicrm_api3_create_success();
266 return civicrm_api3_create_error($result['messages']);
271 * This method allows to update Email Greetings, Postal Greetings and Addressee for a specific contact type.
273 * IMPORTANT: You must first create valid option value before using via admin interface.
274 * Check option lists for Email Greetings, Postal Greetings and Addressee
276 * @todo - is this here by mistake or should it be added to _spec function :id - Integer - greetings option group.
278 * @param array $params
282 function civicrm_api3_job_update_greeting($params) {
283 if (isset($params['ct']) && isset($params['gt'])) {
284 $ct = explode(',', $params['ct']);
285 $gt = explode(',', $params['gt']);
286 foreach ($ct as $ctKey => $ctValue) {
287 foreach ($gt as $gtKey => $gtValue) {
288 $params['ct'] = trim($ctValue);
289 $params['gt'] = trim($gtValue);
290 CRM_Contact_BAO_Contact_Utils
::updateGreeting($params);
295 CRM_Contact_BAO_Contact_Utils
::updateGreeting($params);
297 return civicrm_api3_create_success();
301 * Adjust Metadata for Get action.
303 * The metadata is used for setting defaults, documentation & validation.
305 * @param array $params
306 * Array of parameters determined by getfields.
308 function _civicrm_api3_job_update_greeting_spec(&$params) {
309 $params['ct'] = array(
311 'title' => 'Contact Type',
312 'type' => CRM_Utils_Type
::T_STRING
,
314 $params['gt'] = array(
316 'title' => 'Greeting Type',
317 'type' => CRM_Utils_Type
::T_STRING
,
322 * Mass update pledge statuses.
324 * @param array $params
328 function civicrm_api3_job_process_pledge($params) {
329 // *** Uncomment the next line if you want automated reminders to be sent
330 // $params['send_reminders'] = true;
331 $result = CRM_Pledge_BAO_Pledge
::updatePledgeStatus($params);
333 if ($result['is_error'] == 0) {
334 // experiment: detailed execution log is a result here
335 return civicrm_api3_create_success($result['messages']);
338 return civicrm_api3_create_error($result['error_message']);
343 * Process mail queue.
345 * @param array $params
349 function civicrm_api3_job_process_mailing($params) {
350 $mailsProcessedOrig = CRM_Mailing_BAO_MailingJob
::$mailsProcessed;
353 CRM_Core_BAO_Setting
::isAPIJobAllowedToRun($params);
355 catch (Exception
$e) {
356 return civicrm_api3_create_error($e->getMessage());
359 if (!CRM_Mailing_BAO_Mailing
::processQueue()) {
360 return civicrm_api3_create_error('Process Queue failed');
364 'processed' => CRM_Mailing_BAO_MailingJob
::$mailsProcessed - $mailsProcessedOrig,
366 return civicrm_api3_create_success($values, $params, 'Job', 'process_mailing');
373 * @param array $params
377 function civicrm_api3_job_process_sms($params) {
378 $mailsProcessedOrig = CRM_Mailing_BAO_MailingJob
::$mailsProcessed;
380 if (!CRM_Mailing_BAO_Mailing
::processQueue('sms')) {
381 return civicrm_api3_create_error('Process Queue failed');
385 'processed' => CRM_Mailing_BAO_MailingJob
::$mailsProcessed - $mailsProcessedOrig,
387 return civicrm_api3_create_success($values, $params, 'Job', 'process_sms');
392 * Job to get mail responses from civiMailing.
394 * @param array $params
398 function civicrm_api3_job_fetch_bounces($params) {
399 $lock = Civi
::lockManager()->acquire('worker.mailing.EmailProcessor');
400 if (!$lock->isAcquired()) {
401 return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
403 CRM_Utils_Mail_EmailProcessor
::processBounces($params['is_create_activities']);
406 return civicrm_api3_create_success(1, $params, 'Job', 'fetch_bounces');
410 * Metadata for bounce function.
412 * @param array $params
414 function _civicrm_api3_job_fetch_bounces_spec(&$params) {
415 $params['is_create_activities'] = array(
417 'type' => CRM_Utils_Type
::T_BOOLEAN
,
418 'title' => ts('Create activities for replies?'),
423 * Job to get mail and create activities.
425 * @param array $params
429 function civicrm_api3_job_fetch_activities($params) {
430 $lock = Civi
::lockManager()->acquire('worker.mailing.EmailProcessor');
431 if (!$lock->isAcquired()) {
432 return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
436 CRM_Utils_Mail_EmailProcessor
::processActivities();
439 return civicrm_api3_create_success($values, $params, 'Job', 'fetch_activities');
441 catch (Exception
$e) {
443 return civicrm_api3_create_error($e->getMessage());
448 * Process participant statuses.
450 * @param array $params
454 * array of properties, if error an array with an error id and error message
456 function civicrm_api3_job_process_participant($params) {
457 $result = CRM_Event_BAO_ParticipantStatusType
::process($params);
459 if (!$result['is_error']) {
460 return civicrm_api3_create_success(implode("\r\r", $result['messages']));
463 return civicrm_api3_create_error('Error while processing participant statuses');
469 * This api checks and updates the status of all membership records for a given domain.
471 * The function uses the calc_membership_status and update_contact_membership APIs.
474 * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
476 * @param array $params
477 * Input parameters NOT USED.
480 * true if success, else false
482 function civicrm_api3_job_process_membership($params) {
483 $lock = Civi
::lockManager()->acquire('worker.member.UpdateMembership');
484 if (!$lock->isAcquired()) {
485 return civicrm_api3_create_error('Could not acquire lock, another Membership Processing process is running');
488 $result = CRM_Member_BAO_Membership
::updateAllMembershipStatus();
491 if ($result['is_error'] == 0) {
492 return civicrm_api3_create_success($result['messages'], $params, 'Job', 'process_membership');
495 return civicrm_api3_create_error($result['messages']);
500 * This api checks and updates the status of all survey respondents.
502 * @param array $params
503 * (reference ) input parameters.
506 * true if success, else false
508 function civicrm_api3_job_process_respondent($params) {
509 $result = CRM_Campaign_BAO_Survey
::releaseRespondent($params);
511 if ($result['is_error'] == 0) {
512 return civicrm_api3_create_success();
515 return civicrm_api3_create_error($result['messages']);
520 * Merges given pair of duplicate contacts.
522 * @param array $params
527 * @throws \CiviCRM_API3_Exception
529 function civicrm_api3_job_process_batch_merge($params) {
530 $rule_group_id = CRM_Utils_Array
::value('rule_group_id', $params);
531 if (!$rule_group_id) {
532 $rule_group_id = civicrm_api3('RuleGroup', 'getvalue', array(
533 'contact_type' => 'Individual',
534 'used' => 'Unsupervised',
536 'options' => array('limit' => 1),
539 $rgid = CRM_Utils_Array
::value('rgid', $params);
540 $gid = CRM_Utils_Array
::value('gid', $params);
541 $mode = CRM_Utils_Array
::value('mode', $params, 'safe');
543 $result = CRM_Dedupe_Merger
::batchMerge($rule_group_id, $gid, $mode, 1, 2, CRM_Utils_Array
::value('criteria', $params, array()), CRM_Utils_Array
::value('check_permissions', $params));
545 return civicrm_api3_create_success($result, $params);
549 * Metadata for batch merge function.
553 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
554 $params['rule_group_id'] = array(
555 'title' => 'Dedupe rule group id, defaults to Contact Unsupervised rule',
556 'type' => CRM_Utils_Type
::T_INT
,
557 'api.aliases' => array('rgid'),
559 $params['gid'] = array(
560 'title' => 'group id',
561 'type' => CRM_Utils_Type
::T_INT
,
563 $params['mode'] = array(
565 'description' => 'helps decide how to behave when there are conflicts. A \'safe\' value skips the merge if there are no conflicts. Does a force merge otherwise.',
566 'type' => CRM_Utils_Type
::T_STRING
,
568 $params['auto_flip'] = array(
569 'title' => 'Auto Flip',
570 'description' => 'let the api decide which contact to retain and which to delete?',
571 'type' => CRM_Utils_Type
::T_BOOLEAN
,
576 * Runs handlePaymentCron method in the specified payment processor.
578 * @param array $params
581 * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function
582 * for retrieval via getfields.
583 * {string 'processor_name' - the name of the payment processor, eg: Sagepay}
585 function civicrm_api3_job_run_payment_cron($params) {
588 CRM_Core_Payment
::handlePaymentMethod(
599 CRM_Core_Payment
::handlePaymentMethod(
611 * This api cleans up all the old session entries and temp tables.
613 * We recommend that sites run this on an hourly basis.
615 * @param array $params
616 * Sends in various config parameters to decide what needs to be cleaned.
618 function civicrm_api3_job_cleanup($params) {
619 $session = CRM_Utils_Array
::value('session', $params, TRUE);
620 $tempTable = CRM_Utils_Array
::value('tempTables', $params, TRUE);
621 $jobLog = CRM_Utils_Array
::value('jobLog', $params, TRUE);
622 $expired = CRM_Utils_Array
::value('expiredDbCache', $params, TRUE);
623 $prevNext = CRM_Utils_Array
::value('prevNext', $params, TRUE);
624 $dbCache = CRM_Utils_Array
::value('dbCache', $params, FALSE);
625 $memCache = CRM_Utils_Array
::value('memCache', $params, FALSE);
626 $tplCache = CRM_Utils_Array
::value('tplCache', $params, FALSE);
627 $wordRplc = CRM_Utils_Array
::value('wordRplc', $params, FALSE);
629 if ($session ||
$tempTable ||
$prevNext ||
$expired) {
630 CRM_Core_BAO_Cache
::cleanup($session, $tempTable, $prevNext, $expired);
634 CRM_Core_BAO_Job
::cleanup();
638 $config = CRM_Core_Config
::singleton();
639 $config->cleanup(1, FALSE);
643 CRM_Core_Config
::clearDBCache();
647 CRM_Utils_System
::flushCache();
651 CRM_Core_BAO_WordReplacement
::rebuild();
656 * Set expired relationships to disabled.
658 * @param array $params
661 * @throws \API_Exception
663 function civicrm_api3_job_disable_expired_relationships($params) {
664 $result = CRM_Contact_BAO_Relationship
::disableExpiredRelationships();
666 throw new API_Exception('Failed to disable all expired relationships.');
668 return civicrm_api3_create_success(1, $params, 'Job', 'disable_expired_relationships');
672 * This api reloads all the smart groups.
674 * If the org has a large number of smart groups it is recommended that they use the limit clause
675 * to limit the number of smart groups evaluated on a per job basis.
677 * Might also help to increase the smartGroupCacheTimeout and use the cache.
679 * @param array $params
682 * @throws \API_Exception
684 function civicrm_api3_job_group_rebuild($params) {
685 $lock = Civi
::lockManager()->acquire('worker.core.GroupRebuild');
686 if (!$lock->isAcquired()) {
687 throw new API_Exception('Could not acquire lock, another GroupRebuild process is running');
690 $limit = CRM_Utils_Array
::value('limit', $params, 0);
692 CRM_Contact_BAO_GroupContactCache
::loadAll(NULL, $limit);
695 return civicrm_api3_create_success();
699 * Flush smart groups caches.
701 * This job purges aged smart group cache data (based on the timeout value). Sites can decide whether they want this
702 * job and / or the group cache rebuild job to run. In some cases performance is better when old caches are cleared out
703 * prior to any attempt to rebuild them. Also, many sites are very happy to have caches built on demand, provided the
704 * user is not having to wait for deadlocks to clear when invalidating them.
706 * @param array $params
709 * @throws \API_Exception
711 function civicrm_api3_job_group_cache_flush($params) {
712 CRM_Contact_BAO_GroupContactCache
::deterministicCacheFlush();
713 return civicrm_api3_create_success();
717 * Check for CiviCRM software updates.
719 * Anonymous site statistics are sent back to civicrm.org during this check.
721 function civicrm_api3_job_version_check() {
722 $vc = new CRM_Utils_VersionCheck();
724 return civicrm_api3_create_success();