api/v3/Job.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2016                                |
   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   if (!CRM_Utils_Mail_EmailProcessor::processBounces()) {
 362     $lock->release();
 363     return civicrm_api3_create_error('Process Bounces failed');
 364   }
 365   $lock->release();
 366
 367   // FIXME: processBounces doesn't return true/false on success/failure
 368   $values = array();
 369   return civicrm_api3_create_success($values, $params, 'Job', 'fetch_bounces');
 370 }
 371
 372 /**
 373  * Job to get mail and create activities.
 374  *
 375  * @param array $params
 376  *
 377  * @return array
 378  */
 379 function civicrm_api3_job_fetch_activities($params) {
 380   $lock = Civi::lockManager()->acquire('worker.mailing.EmailProcessor');
 381   if (!$lock->isAcquired()) {
 382     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 383   }
 384
 385   try {
 386     CRM_Utils_Mail_EmailProcessor::processActivities();
 387     $values = array();
 388     $lock->release();
 389     return civicrm_api3_create_success($values, $params, 'Job', 'fetch_activities');
 390   }
 391   catch (Exception $e) {
 392     $lock->release();
 393     return civicrm_api3_create_error('Process Activities failed');
 394   }
 395 }
 396
 397 /**
 398  * Process participant statuses.
 399  *
 400  * @param array $params
 401  *  Input parameters.
 402  *
 403  * @return array
 404  *   array of properties, if error an array with an error id and error message
 405  */
 406 function civicrm_api3_job_process_participant($params) {
 407   $result = CRM_Event_BAO_ParticipantStatusType::process($params);
 408
 409   if (!$result['is_error']) {
 410     return civicrm_api3_create_success(implode("\r\r", $result['messages']));
 411   }
 412   else {
 413     return civicrm_api3_create_error('Error while processing participant statuses');
 414   }
 415 }
 416
 417
 418 /**
 419  * This api checks and updates the status of all membership records for a given domain.
 420  *
 421  * The function uses the calc_membership_status and update_contact_membership APIs.
 422  *
 423  * IMPORTANT:
 424  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
 425  *
 426  * @param array $params
 427  *   Input parameters NOT USED.
 428  *
 429  * @return bool
 430  *   true if success, else false
 431  */
 432 function civicrm_api3_job_process_membership($params) {
 433   $lock = Civi::lockManager()->acquire('worker.member.UpdateMembership');
 434   if (!$lock->isAcquired()) {
 435     return civicrm_api3_create_error('Could not acquire lock, another Membership Processing process is running');
 436   }
 437
 438   $result = CRM_Member_BAO_Membership::updateAllMembershipStatus();
 439   $lock->release();
 440
 441   if ($result['is_error'] == 0) {
 442     return civicrm_api3_create_success($result['messages'], $params, 'Job', 'process_membership');
 443   }
 444   else {
 445     return civicrm_api3_create_error($result['messages']);
 446   }
 447 }
 448
 449 /**
 450  * This api checks and updates the status of all survey respondents.
 451  *
 452  * @param array $params
 453  *   (reference ) input parameters.
 454  *
 455  * @return bool
 456  *   true if success, else false
 457  */
 458 function civicrm_api3_job_process_respondent($params) {
 459   $result = CRM_Campaign_BAO_Survey::releaseRespondent($params);
 460
 461   if ($result['is_error'] == 0) {
 462     return civicrm_api3_create_success();
 463   }
 464   else {
 465     return civicrm_api3_create_error($result['messages']);
 466   }
 467 }
 468
 469 /**
 470  * Merges given pair of duplicate contacts.
 471  *
 472  * @param array $params
 473  *   Input parameters.
 474  *
 475  * @return array
 476  *   API Result Array
 477  * @throws \CiviCRM_API3_Exception
 478  */
 479 function civicrm_api3_job_process_batch_merge($params) {
 480   $rule_group_id = CRM_Utils_Array::value('rgid', $params);
 481   if (!$rule_group_id) {
 482     $rule_group_id = civicrm_api3('RuleGroup', 'getvalue', array(
 483       'contact_type' => 'Individual',
 484       'used' => 'Unsupervised',
 485       'return' => 'id',
 486     ));
 487   }
 488   $gid = CRM_Utils_Array::value('gid', $params);
 489
 490   $mode = CRM_Utils_Array::value('mode', $params, 'safe');
 491   $autoFlip = CRM_Utils_Array::value('auto_flip', $params, TRUE);
 492
 493   $result = CRM_Dedupe_Merger::batchMerge($rule_group_id, $gid, $mode, $autoFlip, 1, 2, CRM_Utils_Array::value('criteria', $params, array()));
 494
 495   return civicrm_api3_create_success($result, $params);
 496 }
 497
 498 /**
 499  * Metadata for batch merge function.
 500  *
 501  * @param $params
 502  */
 503 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
 504   $params['rgid'] = array(
 505     'title' => 'Dedupe rule group id, defaults to Contact Unsupervised rule',
 506     'type' => CRM_Utils_Type::T_INT,
 507   );
 508   $params['gid'] = array(
 509     'title' => 'group id',
 510     'type' => CRM_Utils_Type::T_INT,
 511   );
 512   $params['mode'] = array(
 513     'title' => 'Mode',
 514     '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.',
 515     'type' => CRM_Utils_Type::T_STRING,
 516   );
 517   $params['auto_flip'] = array(
 518     'title' => 'Auto Flip',
 519     'description' => 'let the api decide which contact to retain and which to delete?',
 520     'type' => CRM_Utils_Type::T_BOOLEAN,
 521   );
 522 }
 523
 524 /**
 525  * Runs handlePaymentCron method in the specified payment processor.
 526  *
 527  * @param array $params
 528  *   Input parameters.
 529  *
 530  * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function
 531  * for retrieval via getfields.
 532  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
 533  */
 534 function civicrm_api3_job_run_payment_cron($params) {
 535
 536   // live mode
 537   CRM_Core_Payment::handlePaymentMethod(
 538     'PaymentCron',
 539     array_merge(
 540       $params,
 541       array(
 542         'caller' => 'api',
 543       )
 544     )
 545   );
 546
 547   // test mode
 548   CRM_Core_Payment::handlePaymentMethod(
 549     'PaymentCron',
 550     array_merge(
 551       $params,
 552       array(
 553         'mode' => 'test',
 554       )
 555     )
 556   );
 557 }
 558
 559 /**
 560  * This api cleans up all the old session entries and temp tables.
 561  *
 562  * We recommend that sites run this on an hourly basis.
 563  *
 564  * @param array $params
 565  *   Sends in various config parameters to decide what needs to be cleaned.
 566  */
 567 function civicrm_api3_job_cleanup($params) {
 568   $session   = CRM_Utils_Array::value('session', $params, TRUE);
 569   $tempTable = CRM_Utils_Array::value('tempTables', $params, TRUE);
 570   $jobLog    = CRM_Utils_Array::value('jobLog', $params, TRUE);
 571   $prevNext  = CRM_Utils_Array::value('prevNext', $params, TRUE);
 572   $dbCache   = CRM_Utils_Array::value('dbCache', $params, FALSE);
 573   $memCache  = CRM_Utils_Array::value('memCache', $params, FALSE);
 574   $tplCache  = CRM_Utils_Array::value('tplCache', $params, FALSE);
 575   $wordRplc  = CRM_Utils_Array::value('wordRplc', $params, FALSE);
 576
 577   if ($session || $tempTable || $prevNext) {
 578     CRM_Core_BAO_Cache::cleanup($session, $tempTable, $prevNext);
 579   }
 580
 581   if ($jobLog) {
 582     CRM_Core_BAO_Job::cleanup();
 583   }
 584
 585   if ($tplCache) {
 586     $config = CRM_Core_Config::singleton();
 587     $config->cleanup(1, FALSE);
 588   }
 589
 590   if ($dbCache) {
 591     CRM_Core_Config::clearDBCache();
 592   }
 593
 594   if ($memCache) {
 595     CRM_Utils_System::flushCache();
 596   }
 597
 598   if ($wordRplc) {
 599     CRM_Core_BAO_WordReplacement::rebuild();
 600   }
 601 }
 602
 603 /**
 604  * Set expired relationships to disabled.
 605  *
 606  * @param array $params
 607  *
 608  * @return array
 609  * @throws \API_Exception
 610  */
 611 function civicrm_api3_job_disable_expired_relationships($params) {
 612   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
 613   if (!$result) {
 614     throw new API_Exception('Failed to disable all expired relationships.');
 615   }
 616   return civicrm_api3_create_success(1, $params, 'Job', 'disable_expired_relationships');
 617 }
 618
 619 /**
 620  * This api reloads all the smart groups.
 621  *
 622  * If the org has a large number of smart groups it is recommended that they use the limit clause
 623  * to limit the number of smart groups evaluated on a per job basis.
 624  *
 625  * Might also help to increase the smartGroupCacheTimeout and use the cache.
 626  *
 627  * @param array $params
 628  *
 629  * @return array
 630  * @throws \API_Exception
 631  */
 632 function civicrm_api3_job_group_rebuild($params) {
 633   $lock = Civi::lockManager()->acquire('worker.core.GroupRebuild');
 634   if (!$lock->isAcquired()) {
 635     throw new API_Exception('Could not acquire lock, another EmailProcessor process is running');
 636   }
 637
 638   $limit = CRM_Utils_Array::value('limit', $params, 0);
 639
 640   CRM_Contact_BAO_GroupContactCache::loadAll(NULL, $limit);
 641   $lock->release();
 642
 643   return civicrm_api3_create_success();
 644 }
 645
 646 /**
 647  * Check for CiviCRM software updates.
 648  *
 649  * Anonymous site statistics are sent back to civicrm.org during this check.
 650  */
 651 function civicrm_api3_job_version_check() {
 652   $vc = new CRM_Utils_VersionCheck();
 653   $vc->fetch();
 654   return civicrm_api3_create_success();
 655 }