api/v3/Job.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   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, 'Job');
  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   try {
 318     CRM_Core_BAO_Setting::isAPIJobAllowedToRun($params);
 319   }
 320   catch (Exception $e) {
 321     return civicrm_api3_create_error($e->getMessage());
 322   }
 323
 324   if (!CRM_Mailing_BAO_Mailing::processQueue()) {
 325     return civicrm_api3_create_error('Process Queue failed');
 326   }
 327   else {
 328     $values = array(
 329       'processed' => CRM_Mailing_BAO_MailingJob::$mailsProcessed - $mailsProcessedOrig,
 330     );
 331     return civicrm_api3_create_success($values, $params, 'Job', 'process_mailing');
 332   }
 333 }
 334
 335 /**
 336  * Process sms queue.
 337  *
 338  * @param array $params
 339  *
 340  * @return array
 341  */
 342 function civicrm_api3_job_process_sms($params) {
 343   $mailsProcessedOrig = CRM_Mailing_BAO_MailingJob::$mailsProcessed;
 344
 345   if (!CRM_Mailing_BAO_Mailing::processQueue('sms')) {
 346     return civicrm_api3_create_error('Process Queue failed');
 347   }
 348   else {
 349     $values = array(
 350       'processed' => CRM_Mailing_BAO_MailingJob::$mailsProcessed - $mailsProcessedOrig,
 351     );
 352     return civicrm_api3_create_success($values, $params, 'Job', 'process_sms');
 353   }
 354 }
 355
 356 /**
 357  * Job to get mail responses from civiMailing.
 358  *
 359  * @param array $params
 360  *
 361  * @return array
 362  */
 363 function civicrm_api3_job_fetch_bounces($params) {
 364   $lock = Civi::lockManager()->acquire('worker.mailing.EmailProcessor');
 365   if (!$lock->isAcquired()) {
 366     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 367   }
 368   CRM_Utils_Mail_EmailProcessor::processBounces($params['is_create_activities']);
 369   $lock->release();
 370
 371   return civicrm_api3_create_success(1, $params, 'Job', 'fetch_bounces');
 372 }
 373
 374 /**
 375  * Metadata for bounce function.
 376  *
 377  * @param array $params
 378  */
 379 function _civicrm_api3_job_fetch_bounces_spec(&$params) {
 380   $params['is_create_activities'] = array(
 381     'api.default' => 0,
 382     'type' => CRM_Utils_Type::T_BOOLEAN,
 383     'title' => ts('Create activities for replies?'),
 384   );
 385 }
 386
 387 /**
 388  * Job to get mail and create activities.
 389  *
 390  * @param array $params
 391  *
 392  * @return array
 393  */
 394 function civicrm_api3_job_fetch_activities($params) {
 395   $lock = Civi::lockManager()->acquire('worker.mailing.EmailProcessor');
 396   if (!$lock->isAcquired()) {
 397     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 398   }
 399
 400   try {
 401     CRM_Utils_Mail_EmailProcessor::processActivities();
 402     $values = array();
 403     $lock->release();
 404     return civicrm_api3_create_success($values, $params, 'Job', 'fetch_activities');
 405   }
 406   catch (Exception $e) {
 407     $lock->release();
 408     return civicrm_api3_create_error($e->getMessage());
 409   }
 410 }
 411
 412 /**
 413  * Process participant statuses.
 414  *
 415  * @param array $params
 416  *  Input parameters.
 417  *
 418  * @return array
 419  *   array of properties, if error an array with an error id and error message
 420  */
 421 function civicrm_api3_job_process_participant($params) {
 422   $result = CRM_Event_BAO_ParticipantStatusType::process($params);
 423
 424   if (!$result['is_error']) {
 425     return civicrm_api3_create_success(implode("\r\r", $result['messages']));
 426   }
 427   else {
 428     return civicrm_api3_create_error('Error while processing participant statuses');
 429   }
 430 }
 431
 432
 433 /**
 434  * This api checks and updates the status of all membership records for a given domain.
 435  *
 436  * The function uses the calc_membership_status and update_contact_membership APIs.
 437  *
 438  * IMPORTANT:
 439  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
 440  *
 441  * @param array $params
 442  *   Input parameters NOT USED.
 443  *
 444  * @return bool
 445  *   true if success, else false
 446  */
 447 function civicrm_api3_job_process_membership($params) {
 448   $lock = Civi::lockManager()->acquire('worker.member.UpdateMembership');
 449   if (!$lock->isAcquired()) {
 450     return civicrm_api3_create_error('Could not acquire lock, another Membership Processing process is running');
 451   }
 452
 453   $result = CRM_Member_BAO_Membership::updateAllMembershipStatus();
 454   $lock->release();
 455
 456   if ($result['is_error'] == 0) {
 457     return civicrm_api3_create_success($result['messages'], $params, 'Job', 'process_membership');
 458   }
 459   else {
 460     return civicrm_api3_create_error($result['messages']);
 461   }
 462 }
 463
 464 /**
 465  * This api checks and updates the status of all survey respondents.
 466  *
 467  * @param array $params
 468  *   (reference ) input parameters.
 469  *
 470  * @return bool
 471  *   true if success, else false
 472  */
 473 function civicrm_api3_job_process_respondent($params) {
 474   $result = CRM_Campaign_BAO_Survey::releaseRespondent($params);
 475
 476   if ($result['is_error'] == 0) {
 477     return civicrm_api3_create_success();
 478   }
 479   else {
 480     return civicrm_api3_create_error($result['messages']);
 481   }
 482 }
 483
 484 /**
 485  * Merges given pair of duplicate contacts.
 486  *
 487  * @param array $params
 488  *   Input parameters.
 489  *
 490  * @return array
 491  *   API Result Array
 492  * @throws \CiviCRM_API3_Exception
 493  */
 494 function civicrm_api3_job_process_batch_merge($params) {
 495   $rule_group_id = CRM_Utils_Array::value('rule_group_id', $params);
 496   if (!$rule_group_id) {
 497     $rule_group_id = civicrm_api3('RuleGroup', 'getvalue', array(
 498       'contact_type' => 'Individual',
 499       'used' => 'Unsupervised',
 500       'return' => 'id',
 501       'options' => array('limit' => 1),
 502     ));
 503   }
 504   $rgid = CRM_Utils_Array::value('rgid', $params);
 505   $gid = CRM_Utils_Array::value('gid', $params);
 506   $mode = CRM_Utils_Array::value('mode', $params, 'safe');
 507
 508   $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));
 509
 510   return civicrm_api3_create_success($result, $params);
 511 }
 512
 513 /**
 514  * Metadata for batch merge function.
 515  *
 516  * @param $params
 517  */
 518 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
 519   $params['rule_group_id'] = array(
 520     'title' => 'Dedupe rule group id, defaults to Contact Unsupervised rule',
 521     'type' => CRM_Utils_Type::T_INT,
 522     'api.aliases' => array('rgid'),
 523   );
 524   $params['gid'] = array(
 525     'title' => 'group id',
 526     'type' => CRM_Utils_Type::T_INT,
 527   );
 528   $params['mode'] = array(
 529     'title' => 'Mode',
 530     '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.',
 531     'type' => CRM_Utils_Type::T_STRING,
 532   );
 533   $params['auto_flip'] = array(
 534     'title' => 'Auto Flip',
 535     'description' => 'let the api decide which contact to retain and which to delete?',
 536     'type' => CRM_Utils_Type::T_BOOLEAN,
 537   );
 538 }
 539
 540 /**
 541  * Runs handlePaymentCron method in the specified payment processor.
 542  *
 543  * @param array $params
 544  *   Input parameters.
 545  *
 546  * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function
 547  * for retrieval via getfields.
 548  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
 549  */
 550 function civicrm_api3_job_run_payment_cron($params) {
 551
 552   // live mode
 553   CRM_Core_Payment::handlePaymentMethod(
 554     'PaymentCron',
 555     array_merge(
 556       $params,
 557       array(
 558         'caller' => 'api',
 559       )
 560     )
 561   );
 562
 563   // test mode
 564   CRM_Core_Payment::handlePaymentMethod(
 565     'PaymentCron',
 566     array_merge(
 567       $params,
 568       array(
 569         'mode' => 'test',
 570       )
 571     )
 572   );
 573 }
 574
 575 /**
 576  * This api cleans up all the old session entries and temp tables.
 577  *
 578  * We recommend that sites run this on an hourly basis.
 579  *
 580  * @param array $params
 581  *   Sends in various config parameters to decide what needs to be cleaned.
 582  */
 583 function civicrm_api3_job_cleanup($params) {
 584   $session   = CRM_Utils_Array::value('session', $params, TRUE);
 585   $tempTable = CRM_Utils_Array::value('tempTables', $params, TRUE);
 586   $jobLog    = CRM_Utils_Array::value('jobLog', $params, TRUE);
 587   $prevNext  = CRM_Utils_Array::value('prevNext', $params, TRUE);
 588   $dbCache   = CRM_Utils_Array::value('dbCache', $params, FALSE);
 589   $memCache  = CRM_Utils_Array::value('memCache', $params, FALSE);
 590   $tplCache  = CRM_Utils_Array::value('tplCache', $params, FALSE);
 591   $wordRplc  = CRM_Utils_Array::value('wordRplc', $params, FALSE);
 592
 593   if ($session || $tempTable || $prevNext) {
 594     CRM_Core_BAO_Cache::cleanup($session, $tempTable, $prevNext);
 595   }
 596
 597   if ($jobLog) {
 598     CRM_Core_BAO_Job::cleanup();
 599   }
 600
 601   if ($tplCache) {
 602     $config = CRM_Core_Config::singleton();
 603     $config->cleanup(1, FALSE);
 604   }
 605
 606   if ($dbCache) {
 607     CRM_Core_Config::clearDBCache();
 608   }
 609
 610   if ($memCache) {
 611     CRM_Utils_System::flushCache();
 612   }
 613
 614   if ($wordRplc) {
 615     CRM_Core_BAO_WordReplacement::rebuild();
 616   }
 617 }
 618
 619 /**
 620  * Set expired relationships to disabled.
 621  *
 622  * @param array $params
 623  *
 624  * @return array
 625  * @throws \API_Exception
 626  */
 627 function civicrm_api3_job_disable_expired_relationships($params) {
 628   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
 629   if (!$result) {
 630     throw new API_Exception('Failed to disable all expired relationships.');
 631   }
 632   return civicrm_api3_create_success(1, $params, 'Job', 'disable_expired_relationships');
 633 }
 634
 635 /**
 636  * This api reloads all the smart groups.
 637  *
 638  * If the org has a large number of smart groups it is recommended that they use the limit clause
 639  * to limit the number of smart groups evaluated on a per job basis.
 640  *
 641  * Might also help to increase the smartGroupCacheTimeout and use the cache.
 642  *
 643  * @param array $params
 644  *
 645  * @return array
 646  * @throws \API_Exception
 647  */
 648 function civicrm_api3_job_group_rebuild($params) {
 649   $lock = Civi::lockManager()->acquire('worker.core.GroupRebuild');
 650   if (!$lock->isAcquired()) {
 651     throw new API_Exception('Could not acquire lock, another GroupRebuild process is running');
 652   }
 653
 654   $limit = CRM_Utils_Array::value('limit', $params, 0);
 655
 656   CRM_Contact_BAO_GroupContactCache::loadAll(NULL, $limit);
 657   $lock->release();
 658
 659   return civicrm_api3_create_success();
 660 }
 661
 662 /**
 663  * Flush smart groups caches.
 664  *
 665  * This job purges aged smart group cache data (based on the timeout value). Sites can decide whether they want this
 666  * job and / or the group cache rebuild job to run. In some cases performance is better when old caches are cleared out
 667  * prior to any attempt to rebuild them. Also, many sites are very happy to have caches built on demand, provided the
 668  * user is not having to wait for deadlocks to clear when invalidating them.
 669  *
 670  * @param array $params
 671  *
 672  * @return array
 673  * @throws \API_Exception
 674  */
 675 function civicrm_api3_job_group_cache_flush($params) {
 676   CRM_Contact_BAO_GroupContactCache::deterministicCacheFlush();
 677   return civicrm_api3_create_success();
 678 }
 679
 680 /**
 681  * Check for CiviCRM software updates.
 682  *
 683  * Anonymous site statistics are sent back to civicrm.org during this check.
 684  */
 685 function civicrm_api3_job_version_check() {
 686   $vc = new CRM_Utils_VersionCheck();
 687   $vc->fetch();
 688   return civicrm_api3_create_success();
 689 }