api/v3/Job.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2017                                |
   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  * This api is used for working with scheduled "cron" jobs.
  30  *
  31  * @package CiviCRM_APIv3
  32  */
  33
  34 /**
  35  * Adjust metadata for "Create" action.
  36  *
  37  * The metadata is used for setting defaults, documentation & validation.
  38  *
  39  * @param array $params
  40  *   Array of parameters determined by getfields.
  41  */
  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;
  47
  48   $params['domain_id']['api.default'] = CRM_Core_Config::domainID();
  49   $params['is_active']['api.default'] = 1;
  50 }
  51
  52 /**
  53  * Create scheduled job.
  54  *
  55  * @param array $params
  56  *   Associative array of property name/value pairs to insert in new job.
  57  *
  58  * @return array
  59  */
  60 function civicrm_api3_job_create($params) {
  61   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  62 }
  63
  64 /**
  65  * Retrieve one or more job.
  66  *
  67  * @param array $params
  68  *   input parameters
  69  *
  70  * @return array
  71  */
  72 function civicrm_api3_job_get($params) {
  73   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  74 }
  75
  76 /**
  77  * Delete a job.
  78  *
  79  * @param array $params
  80  */
  81 function civicrm_api3_job_delete($params) {
  82   _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  83 }
  84
  85 /**
  86  * Dumb wrapper to execute scheduled jobs.
  87  *
  88  * Always creates success - errors and results are handled in the job log.
  89  *
  90  * @param array $params
  91  *   input parameters (unused).
  92  *
  93  * @return array
  94  *   API Result Array
  95  */
  96 function civicrm_api3_job_execute($params) {
  97
  98   $facility = new CRM_Core_JobManager();
  99   $facility->execute(FALSE);
 100
 101   // Always creates success - results are handled elsewhere.
 102   return civicrm_api3_create_success(1, $params, 'Job');
 103 }
 104
 105 /**
 106  * Adjust Metadata for Execute action.
 107  *
 108  * @param array $params
 109  *   Array of parameters determined by getfields.
 110  */
 111 function _civicrm_api3_job_execute_spec(&$params) {
 112 }
 113
 114 /**
 115  * Geocode group of contacts based on given params.
 116  *
 117  * @param array $params
 118  *   input parameters.
 119  *
 120  * @return array
 121  *   API Result Array
 122  */
 123 function civicrm_api3_job_geocode($params) {
 124   $gc = new CRM_Utils_Address_BatchUpdate($params);
 125
 126   $result = $gc->run();
 127
 128   if ($result['is_error'] == 0) {
 129     return civicrm_api3_create_success($result['messages']);
 130   }
 131   else {
 132     return civicrm_api3_create_error($result['messages']);
 133   }
 134 }
 135
 136 /**
 137  * First check on Code documentation.
 138  *
 139  * @param array $params
 140  */
 141 function _civicrm_api3_job_geocode_spec(&$params) {
 142   $params['start'] = array(
 143     'title' => 'Starting Contact ID',
 144     'type' => CRM_Utils_Type::T_INT,
 145   );
 146   $params['end'] = array(
 147     'title' => 'Ending Contact ID',
 148     'type' => CRM_Utils_Type::T_INT,
 149   );
 150   $params['geocoding'] = array(
 151     'title' => 'Geocode address?',
 152     'type' => CRM_Utils_Type::T_BOOLEAN,
 153   );
 154   $params['parse'] = array(
 155     'title' => 'Parse street address?',
 156     'type' => CRM_Utils_Type::T_BOOLEAN,
 157   );
 158   $params['throttle'] = array(
 159     'title' => 'Throttle?',
 160     'description' => 'If enabled, geo-codes at a slow rate',
 161     'type' => CRM_Utils_Type::T_BOOLEAN,
 162   );
 163 }
 164
 165 /**
 166  * Send the scheduled reminders for all contacts (either for activities or events).
 167  *
 168  * @param array $params
 169  *   (reference ) input parameters.
 170  *                        now - the time to use, in YmdHis format
 171  *                            - makes testing a bit simpler since we can simulate past/future time
 172  *
 173  * @return array
 174  */
 175 function civicrm_api3_job_send_reminder($params) {
 176   //note that $params['rowCount' can be overridden by one of the preferred syntaxes ($options['limit'] = x
 177   //It's not clear whether than syntax can be passed in via the UI config - but this keeps the pre 4.4.4 behaviour
 178   // in that case (ie. makes it non-configurable via the UI). Another approach would be to set a default of 0
 179   // in the _spec function - but since that is a deprecated value it seems more contentious than this approach
 180   $params['rowCount'] = 0;
 181   $lock = Civi::lockManager()->acquire('worker.core.ActionSchedule');
 182   if (!$lock->isAcquired()) {
 183     return civicrm_api3_create_error('Could not acquire lock, another ActionSchedule process is running');
 184   }
 185
 186   $result = CRM_Core_BAO_ActionSchedule::processQueue(CRM_Utils_Array::value('now', $params), $params);
 187   $lock->release();
 188
 189   if ($result['is_error'] == 0) {
 190     return civicrm_api3_create_success();
 191   }
 192   else {
 193     return civicrm_api3_create_error($result['messages']);
 194   }
 195 }
 196 /**
 197  * Adjust metadata for "send_reminder" action.
 198  *
 199  * The metadata is used for setting defaults, documentation & validation.
 200  *
 201  * @param array $params
 202  *   Array of parameters determined by getfields.
 203  */
 204 function _civicrm_api3_job_send_reminder(&$params) {
 205   //@todo this function will now take all fields in action_schedule as params
 206   // as it is calling the api fn to set the filters - update getfields to reflect
 207   $params['id'] = array(
 208     'type' => CRM_Utils_Type::T_INT,
 209     'title' => 'Action Schedule ID',
 210   );
 211 }
 212 /**
 213  * Execute a specific report instance and send the output via email.
 214  *
 215  * @param array $params
 216  *   (reference ) input parameters.
 217  *                        sendmail - Boolean - should email be sent?, required
 218  *                        instanceId - Integer - the report instance ID
 219  *                        resetVal - Integer - should we reset form state (always true)?
 220  *
 221  * @return array
 222  */
 223 function civicrm_api3_job_mail_report($params) {
 224   $result = CRM_Report_Utils_Report::processReport($params);
 225
 226   if ($result['is_error'] == 0) {
 227     // this should be handling by throwing exceptions but can't remove until we can test that.
 228     return civicrm_api3_create_success();
 229   }
 230   else {
 231     return civicrm_api3_create_error($result['messages']);
 232   }
 233 }
 234
 235 /**
 236  * This method allows to update Email Greetings, Postal Greetings and Addressee for a specific contact type.
 237  *
 238  * IMPORTANT: You must first create valid option value before using via admin interface.
 239  * Check option lists for Email Greetings, Postal Greetings and Addressee
 240  *
 241  * @todo - is this here by mistake or should it be added to _spec function :id - Integer - greetings option group.
 242  *
 243  * @param array $params
 244  *
 245  * @return array
 246  */
 247 function civicrm_api3_job_update_greeting($params) {
 248   if (isset($params['ct']) && isset($params['gt'])) {
 249     $ct = explode(',', $params['ct']);
 250     $gt = explode(',', $params['gt']);
 251     foreach ($ct as $ctKey => $ctValue) {
 252       foreach ($gt as $gtKey => $gtValue) {
 253         $params['ct'] = trim($ctValue);
 254         $params['gt'] = trim($gtValue);
 255         CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
 256       }
 257     }
 258   }
 259   else {
 260     CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
 261   }
 262   return civicrm_api3_create_success();
 263 }
 264
 265 /**
 266  * Adjust Metadata for Get action.
 267  *
 268  * The metadata is used for setting defaults, documentation & validation.
 269  *
 270  * @param array $params
 271  *   Array of parameters determined by getfields.
 272  */
 273 function _civicrm_api3_job_update_greeting_spec(&$params) {
 274   $params['ct'] = array(
 275     'api.required' => 1,
 276     'title' => 'Contact Type',
 277     'type' => CRM_Utils_Type::T_STRING,
 278   );
 279   $params['gt'] = array(
 280     'api.required' => 1,
 281     'title' => 'Greeting Type',
 282     'type' => CRM_Utils_Type::T_STRING,
 283   );
 284 }
 285
 286 /**
 287  * Mass update pledge statuses.
 288  *
 289  * @param array $params
 290  *
 291  * @return array
 292  */
 293 function civicrm_api3_job_process_pledge($params) {
 294   // *** Uncomment the next line if you want automated reminders to be sent
 295   // $params['send_reminders'] = true;
 296   $result = CRM_Pledge_BAO_Pledge::updatePledgeStatus($params);
 297
 298   if ($result['is_error'] == 0) {
 299     // experiment: detailed execution log is a result here
 300     return civicrm_api3_create_success($result['messages']);
 301   }
 302   else {
 303     return civicrm_api3_create_error($result['error_message']);
 304   }
 305 }
 306
 307 /**
 308  * Process mail queue.
 309  *
 310  * @param array $params
 311  *
 312  * @return array
 313  */
 314 function civicrm_api3_job_process_mailing($params) {
 315   $mailsProcessedOrig = CRM_Mailing_BAO_MailingJob::$mailsProcessed;
 316
 317   if (!CRM_Mailing_BAO_Mailing::processQueue()) {
 318     return civicrm_api3_create_error('Process Queue failed');
 319   }
 320   else {
 321     $values = array(
 322       'processed' => CRM_Mailing_BAO_MailingJob::$mailsProcessed - $mailsProcessedOrig,
 323     );
 324     return civicrm_api3_create_success($values, $params, 'Job', 'process_mailing');
 325   }
 326 }
 327
 328 /**
 329  * Process sms queue.
 330  *
 331  * @param array $params
 332  *
 333  * @return array
 334  */
 335 function civicrm_api3_job_process_sms($params) {
 336   $mailsProcessedOrig = CRM_Mailing_BAO_MailingJob::$mailsProcessed;
 337
 338   if (!CRM_Mailing_BAO_Mailing::processQueue('sms')) {
 339     return civicrm_api3_create_error('Process Queue failed');
 340   }
 341   else {
 342     $values = array(
 343       'processed' => CRM_Mailing_BAO_MailingJob::$mailsProcessed - $mailsProcessedOrig,
 344     );
 345     return civicrm_api3_create_success($values, $params, 'Job', 'process_sms');
 346   }
 347 }
 348
 349 /**
 350  * Job to get mail responses from civiMailing.
 351  *
 352  * @param array $params
 353  *
 354  * @return array
 355  */
 356 function civicrm_api3_job_fetch_bounces($params) {
 357   $lock = Civi::lockManager()->acquire('worker.mailing.EmailProcessor');
 358   if (!$lock->isAcquired()) {
 359     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 360   }
 361   CRM_Utils_Mail_EmailProcessor::processBounces($params['is_create_activities']);
 362   $lock->release();
 363
 364   return civicrm_api3_create_success(1, $params, 'Job', 'fetch_bounces');
 365 }
 366
 367 /**
 368  * Metadata for bounce function.
 369  *
 370  * @param array $params
 371  */
 372 function _civicrm_api3_job_fetch_bounces_spec(&$params) {
 373   $params['is_create_activities'] = array(
 374     'api.default' => 0,
 375     'type' => CRM_Utils_Type::T_BOOLEAN,
 376     'title' => ts('Create activities for replies?'),
 377   );
 378 }
 379
 380 /**
 381  * Job to get mail and create activities.
 382  *
 383  * @param array $params
 384  *
 385  * @return array
 386  */
 387 function civicrm_api3_job_fetch_activities($params) {
 388   $lock = Civi::lockManager()->acquire('worker.mailing.EmailProcessor');
 389   if (!$lock->isAcquired()) {
 390     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 391   }
 392
 393   try {
 394     CRM_Utils_Mail_EmailProcessor::processActivities();
 395     $values = array();
 396     $lock->release();
 397     return civicrm_api3_create_success($values, $params, 'Job', 'fetch_activities');
 398   }
 399   catch (Exception $e) {
 400     $lock->release();
 401     return civicrm_api3_create_error($e->getMessage());
 402   }
 403 }
 404
 405 /**
 406  * Process participant statuses.
 407  *
 408  * @param array $params
 409  *  Input parameters.
 410  *
 411  * @return array
 412  *   array of properties, if error an array with an error id and error message
 413  */
 414 function civicrm_api3_job_process_participant($params) {
 415   $result = CRM_Event_BAO_ParticipantStatusType::process($params);
 416
 417   if (!$result['is_error']) {
 418     return civicrm_api3_create_success(implode("\r\r", $result['messages']));
 419   }
 420   else {
 421     return civicrm_api3_create_error('Error while processing participant statuses');
 422   }
 423 }
 424
 425
 426 /**
 427  * This api checks and updates the status of all membership records for a given domain.
 428  *
 429  * The function uses the calc_membership_status and update_contact_membership APIs.
 430  *
 431  * IMPORTANT:
 432  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
 433  *
 434  * @param array $params
 435  *   Input parameters NOT USED.
 436  *
 437  * @return bool
 438  *   true if success, else false
 439  */
 440 function civicrm_api3_job_process_membership($params) {
 441   $lock = Civi::lockManager()->acquire('worker.member.UpdateMembership');
 442   if (!$lock->isAcquired()) {
 443     return civicrm_api3_create_error('Could not acquire lock, another Membership Processing process is running');
 444   }
 445
 446   $result = CRM_Member_BAO_Membership::updateAllMembershipStatus();
 447   $lock->release();
 448
 449   if ($result['is_error'] == 0) {
 450     return civicrm_api3_create_success($result['messages'], $params, 'Job', 'process_membership');
 451   }
 452   else {
 453     return civicrm_api3_create_error($result['messages']);
 454   }
 455 }
 456
 457 /**
 458  * This api checks and updates the status of all survey respondents.
 459  *
 460  * @param array $params
 461  *   (reference ) input parameters.
 462  *
 463  * @return bool
 464  *   true if success, else false
 465  */
 466 function civicrm_api3_job_process_respondent($params) {
 467   $result = CRM_Campaign_BAO_Survey::releaseRespondent($params);
 468
 469   if ($result['is_error'] == 0) {
 470     return civicrm_api3_create_success();
 471   }
 472   else {
 473     return civicrm_api3_create_error($result['messages']);
 474   }
 475 }
 476
 477 /**
 478  * Merges given pair of duplicate contacts.
 479  *
 480  * @param array $params
 481  *   Input parameters.
 482  *
 483  * @return array
 484  *   API Result Array
 485  * @throws \CiviCRM_API3_Exception
 486  */
 487 function civicrm_api3_job_process_batch_merge($params) {
 488   $rule_group_id = CRM_Utils_Array::value('rule_group_id', $params);
 489   if (!$rule_group_id) {
 490     $rule_group_id = civicrm_api3('RuleGroup', 'getvalue', array(
 491       'contact_type' => 'Individual',
 492       'used' => 'Unsupervised',
 493       'return' => 'id',
 494       'options' => array('limit' => 1),
 495     ));
 496   }
 497   $gid = CRM_Utils_Array::value('gid', $params);
 498   $mode = CRM_Utils_Array::value('mode', $params, 'safe');
 499
 500   $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));
 501
 502   return civicrm_api3_create_success($result, $params);
 503 }
 504
 505 /**
 506  * Metadata for batch merge function.
 507  *
 508  * @param $params
 509  */
 510 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
 511   $params['rule_group_id'] = array(
 512     'title' => 'Dedupe rule group id, defaults to Contact Unsupervised rule',
 513     'type' => CRM_Utils_Type::T_INT,
 514     'api.aliases' => array('rgid'),
 515   );
 516   $params['gid'] = array(
 517     'title' => 'group id',
 518     'type' => CRM_Utils_Type::T_INT,
 519   );
 520   $params['mode'] = array(
 521     'title' => 'Mode',
 522     '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.',
 523     'type' => CRM_Utils_Type::T_STRING,
 524   );
 525   $params['auto_flip'] = array(
 526     'title' => 'Auto Flip',
 527     'description' => 'let the api decide which contact to retain and which to delete?',
 528     'type' => CRM_Utils_Type::T_BOOLEAN,
 529   );
 530 }
 531
 532 /**
 533  * Runs handlePaymentCron method in the specified payment processor.
 534  *
 535  * @param array $params
 536  *   Input parameters.
 537  *
 538  * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function
 539  * for retrieval via getfields.
 540  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
 541  */
 542 function civicrm_api3_job_run_payment_cron($params) {
 543
 544   // live mode
 545   CRM_Core_Payment::handlePaymentMethod(
 546     'PaymentCron',
 547     array_merge(
 548       $params,
 549       array(
 550         'caller' => 'api',
 551       )
 552     )
 553   );
 554
 555   // test mode
 556   CRM_Core_Payment::handlePaymentMethod(
 557     'PaymentCron',
 558     array_merge(
 559       $params,
 560       array(
 561         'mode' => 'test',
 562       )
 563     )
 564   );
 565 }
 566
 567 /**
 568  * This api cleans up all the old session entries and temp tables.
 569  *
 570  * We recommend that sites run this on an hourly basis.
 571  *
 572  * @param array $params
 573  *   Sends in various config parameters to decide what needs to be cleaned.
 574  */
 575 function civicrm_api3_job_cleanup($params) {
 576   $session   = CRM_Utils_Array::value('session', $params, TRUE);
 577   $tempTable = CRM_Utils_Array::value('tempTables', $params, TRUE);
 578   $jobLog    = CRM_Utils_Array::value('jobLog', $params, TRUE);
 579   $prevNext  = CRM_Utils_Array::value('prevNext', $params, TRUE);
 580   $dbCache   = CRM_Utils_Array::value('dbCache', $params, FALSE);
 581   $memCache  = CRM_Utils_Array::value('memCache', $params, FALSE);
 582   $tplCache  = CRM_Utils_Array::value('tplCache', $params, FALSE);
 583   $wordRplc  = CRM_Utils_Array::value('wordRplc', $params, FALSE);
 584
 585   if ($session || $tempTable || $prevNext) {
 586     CRM_Core_BAO_Cache::cleanup($session, $tempTable, $prevNext);
 587   }
 588
 589   if ($jobLog) {
 590     CRM_Core_BAO_Job::cleanup();
 591   }
 592
 593   if ($tplCache) {
 594     $config = CRM_Core_Config::singleton();
 595     $config->cleanup(1, FALSE);
 596   }
 597
 598   if ($dbCache) {
 599     CRM_Core_Config::clearDBCache();
 600   }
 601
 602   if ($memCache) {
 603     CRM_Utils_System::flushCache();
 604   }
 605
 606   if ($wordRplc) {
 607     CRM_Core_BAO_WordReplacement::rebuild();
 608   }
 609 }
 610
 611 /**
 612  * Set expired relationships to disabled.
 613  *
 614  * @param array $params
 615  *
 616  * @return array
 617  * @throws \API_Exception
 618  */
 619 function civicrm_api3_job_disable_expired_relationships($params) {
 620   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
 621   if (!$result) {
 622     throw new API_Exception('Failed to disable all expired relationships.');
 623   }
 624   return civicrm_api3_create_success(1, $params, 'Job', 'disable_expired_relationships');
 625 }
 626
 627 /**
 628  * This api reloads all the smart groups.
 629  *
 630  * If the org has a large number of smart groups it is recommended that they use the limit clause
 631  * to limit the number of smart groups evaluated on a per job basis.
 632  *
 633  * Might also help to increase the smartGroupCacheTimeout and use the cache.
 634  *
 635  * @param array $params
 636  *
 637  * @return array
 638  * @throws \API_Exception
 639  */
 640 function civicrm_api3_job_group_rebuild($params) {
 641   $lock = Civi::lockManager()->acquire('worker.core.GroupRebuild');
 642   if (!$lock->isAcquired()) {
 643     throw new API_Exception('Could not acquire lock, another GroupRebuild process is running');
 644   }
 645
 646   $limit = CRM_Utils_Array::value('limit', $params, 0);
 647
 648   CRM_Contact_BAO_GroupContactCache::loadAll(NULL, $limit);
 649   $lock->release();
 650
 651   return civicrm_api3_create_success();
 652 }
 653
 654 /**
 655  * Flush smart groups caches.
 656  *
 657  * This job purges aged smart group cache data (based on the timeout value). Sites can decide whether they want this
 658  * job and / or the group cache rebuild job to run. In some cases performance is better when old caches are cleared out
 659  * prior to any attempt to rebuild them. Also, many sites are very happy to have caches built on demand, provided the
 660  * user is not having to wait for deadlocks to clear when invalidating them.
 661  *
 662  * @param array $params
 663  *
 664  * @return array
 665  * @throws \API_Exception
 666  */
 667 function civicrm_api3_job_group_cache_flush($params) {
 668   CRM_Contact_BAO_GroupContactCache::deterministicCacheFlush();
 669   return civicrm_api3_create_success();
 670 }
 671
 672 /**
 673  * Check for CiviCRM software updates.
 674  *
 675  * Anonymous site statistics are sent back to civicrm.org during this check.
 676  */
 677 function civicrm_api3_job_version_check() {
 678   $vc = new CRM_Utils_VersionCheck();
 679   $vc->fetch();
 680   return civicrm_api3_create_success();
 681 }