api/v3/Job.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   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('title' => 'Start Date');
 143   $params['end'] = array('title' => 'End Date');
 144   $params['geocoding'] = array('title' => 'Geocode address?');
 145   $params['parse'] = array('title' => 'Parse street address?');
 146   $params['throttle'] = array('title' => 'Throttle? if enabled, geo-codes at a slow rate');
 147 }
 148
 149 /**
 150  * Send the scheduled reminders for all contacts (either for activities or events).
 151  *
 152  * @param array $params
 153  *   (reference ) input parameters.
 154  *                        now - the time to use, in YmdHis format
 155  *                            - makes testing a bit simpler since we can simulate past/future time
 156  *
 157  * @return array
 158  */
 159 function civicrm_api3_job_send_reminder($params) {
 160   //note that $params['rowCount' can be overridden by one of the preferred syntaxes ($options['limit'] = x
 161   //It's not clear whether than syntax can be passed in via the UI config - but this keeps the pre 4.4.4 behaviour
 162   // in that case (ie. makes it non-configurable via the UI). Another approach would be to set a default of 0
 163   // in the _spec function - but since that is a deprecated value it seems more contentious than this approach
 164   $params['rowCount'] = 0;
 165   $lock = new CRM_Core_Lock('civimail.job.EmailProcessor');
 166   if (!$lock->isAcquired()) {
 167     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 168   }
 169
 170   $result = CRM_Core_BAO_ActionSchedule::processQueue(CRM_Utils_Array::value('now', $params), $params);
 171   $lock->release();
 172
 173   if ($result['is_error'] == 0) {
 174     return civicrm_api3_create_success();
 175   }
 176   else {
 177     return civicrm_api3_create_error($result['messages']);
 178   }
 179 }
 180 /**
 181  * Adjust metadata for "send_reminder" action.
 182  *
 183  * The metadata is used for setting defaults, documentation & validation.
 184  *
 185  * @param array $params
 186  *   Array of parameters determined by getfields.
 187  */
 188 function _civicrm_api3_job_send_reminder(&$params) {
 189   //@todo this function will now take all fields in action_schedule as params
 190   // as it is calling the api fn to set the filters - update getfields to reflect
 191   $params['id'] = array(
 192     'type' => CRM_Utils_Type::T_INT,
 193     'title' => 'Action Schedule ID',
 194   );
 195 }
 196 /**
 197  * Execute a specific report instance and send the output via email.
 198  *
 199  * @param array $params
 200  *   (reference ) input parameters.
 201  *                        sendmail - Boolean - should email be sent?, required
 202  *                        instanceId - Integer - the report instance ID
 203  *                        resetVal - Integer - should we reset form state (always true)?
 204  *
 205  * @return array
 206  */
 207 function civicrm_api3_job_mail_report($params) {
 208   $result = CRM_Report_Utils_Report::processReport($params);
 209
 210   if ($result['is_error'] == 0) {
 211     // this should be handling by throwing exceptions but can't remove until we can test that.
 212     return civicrm_api3_create_success();
 213   }
 214   else {
 215     return civicrm_api3_create_error($result['messages']);
 216   }
 217 }
 218
 219 /**
 220  * This method allows to update Email Greetings, Postal Greetings and Addressee for a specific contact type.
 221  *
 222  * IMPORTANT: You must first create valid option value before using via admin interface.
 223  * Check option lists for Email Greetings, Postal Greetings and Addressee
 224  *
 225  * @todo - is this here by mistake or should it be added to _spec function :id - Integer - greetings option group.
 226  *
 227  * @param array $params
 228  *
 229  * @return array
 230  */
 231 function civicrm_api3_job_update_greeting($params) {
 232   if (isset($params['ct']) && isset($params['gt'])) {
 233     $ct = explode(',', $params['ct']);
 234     $gt = explode(',', $params['gt']);
 235     foreach ($ct as $ctKey => $ctValue) {
 236       foreach ($gt as $gtKey => $gtValue) {
 237         $params['ct'] = trim($ctValue);
 238         $params['gt'] = trim($gtValue);
 239         CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
 240       }
 241     }
 242   }
 243   else {
 244     CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
 245   }
 246   return civicrm_api3_create_success();
 247 }
 248
 249 /**
 250  * Adjust Metadata for Get action.
 251  *
 252  * The metadata is used for setting defaults, documentation & validation.
 253  *
 254  * @param array $params
 255  *   Array of parameters determined by getfields.
 256  */
 257 function _civicrm_api3_job_update_greeting_spec(&$params) {
 258   $params['ct'] = array(
 259     'api.required' => 1,
 260     'title' => 'Contact Type',
 261     'type' => CRM_Utils_Type::T_STRING,
 262   );
 263   $params['gt'] = array(
 264     'api.required' => 1,
 265     'title' => 'Greeting Type',
 266     'type' => CRM_Utils_Type::T_STRING,
 267   );
 268 }
 269
 270 /**
 271  * Mass update pledge statuses.
 272  *
 273  * @param array $params
 274  *
 275  * @return array
 276  */
 277 function civicrm_api3_job_process_pledge($params) {
 278   // *** Uncomment the next line if you want automated reminders to be sent
 279   // $params['send_reminders'] = true;
 280   $result = CRM_Pledge_BAO_Pledge::updatePledgeStatus($params);
 281
 282   if ($result['is_error'] == 0) {
 283     // experiment: detailed execution log is a result here
 284     return civicrm_api3_create_success($result['messages']);
 285   }
 286   else {
 287     return civicrm_api3_create_error($result['error_message']);
 288   }
 289 }
 290
 291 /**
 292  * Process mail queue.
 293  *
 294  * @param array $params
 295  *
 296  * @return array
 297  */
 298 function civicrm_api3_job_process_mailing($params) {
 299
 300   if (!CRM_Mailing_BAO_Mailing::processQueue()) {
 301     return civicrm_api3_create_error('Process Queue failed');
 302   }
 303   else {
 304     $values = array();
 305     return civicrm_api3_create_success($values, $params, 'Job', 'process_mailing');
 306   }
 307 }
 308
 309 /**
 310  * Process sms queue.
 311  *
 312  * @param array $params
 313  *
 314  * @return array
 315  */
 316 function civicrm_api3_job_process_sms($params) {
 317   if (!CRM_Mailing_BAO_Mailing::processQueue('sms')) {
 318     return civicrm_api3_create_error('Process Queue failed');
 319   }
 320   else {
 321     $values = array();
 322     return civicrm_api3_create_success($values, $params, 'Job', 'process_sms');
 323   }
 324 }
 325
 326 /**
 327  * Job to get mail responses from civiMailing.
 328  *
 329  * @param array $params
 330  *
 331  * @return array
 332  */
 333 function civicrm_api3_job_fetch_bounces($params) {
 334   $lock = new CRM_Core_Lock('civimail.job.EmailProcessor');
 335   if (!$lock->isAcquired()) {
 336     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 337   }
 338   if (!CRM_Utils_Mail_EmailProcessor::processBounces()) {
 339     $lock->release();
 340     return civicrm_api3_create_error('Process Bounces failed');
 341   }
 342   $lock->release();
 343
 344   // FIXME: processBounces doesn't return true/false on success/failure
 345   $values = array();
 346   return civicrm_api3_create_success($values, $params, 'Job', 'fetch_bounces');
 347 }
 348
 349 /**
 350  * Job to get mail and create activities.
 351  *
 352  * @param array $params
 353  *
 354  * @return array
 355  */
 356 function civicrm_api3_job_fetch_activities($params) {
 357   $lock = new CRM_Core_Lock('civimail.job.EmailProcessor');
 358   if (!$lock->isAcquired()) {
 359     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 360   }
 361
 362   try {
 363     CRM_Utils_Mail_EmailProcessor::processActivities();
 364     $values = array();
 365     $lock->release();
 366     return civicrm_api3_create_success($values, $params, 'Job', 'fetch_activities');
 367   }
 368   catch (Exception $e) {
 369     $lock->release();
 370     return civicrm_api3_create_error('Process Activities failed');
 371   }
 372 }
 373
 374 /**
 375  * Process participant statuses.
 376  *
 377  * @param array $params
 378  *  Input parameters.
 379  *
 380  * @return array
 381  *   array of properties, if error an array with an error id and error message
 382  */
 383 function civicrm_api3_job_process_participant($params) {
 384   $result = CRM_Event_BAO_ParticipantStatusType::process($params);
 385
 386   if (!$result['is_error']) {
 387     return civicrm_api3_create_success(implode("\r\r", $result['messages']));
 388   }
 389   else {
 390     return civicrm_api3_create_error('Error while processing participant statuses');
 391   }
 392 }
 393
 394
 395 /**
 396  * This api checks and updates the status of all membership records for a given domain.
 397  *
 398  * The function uses the calc_membership_status and update_contact_membership APIs.
 399  *
 400  * IMPORTANT:
 401  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
 402  *
 403  * @param array $params
 404  *   Input parameters NOT USED.
 405  *
 406  * @return bool
 407  *   true if success, else false
 408  */
 409 function civicrm_api3_job_process_membership($params) {
 410   $lock = new CRM_Core_Lock('civimail.job.updateMembership');
 411   if (!$lock->isAcquired()) {
 412     return civicrm_api3_create_error('Could not acquire lock, another Membership Processing process is running');
 413   }
 414
 415   $result = CRM_Member_BAO_Membership::updateAllMembershipStatus();
 416   $lock->release();
 417
 418   if ($result['is_error'] == 0) {
 419     return civicrm_api3_create_success($result['messages'], $params, 'Job', 'process_membership');
 420   }
 421   else {
 422     return civicrm_api3_create_error($result['messages']);
 423   }
 424 }
 425
 426 /**
 427  * This api checks and updates the status of all survey respondents.
 428  *
 429  * @param array $params
 430  *   (reference ) input parameters.
 431  *
 432  * @return bool
 433  *   true if success, else false
 434  */
 435 function civicrm_api3_job_process_respondent($params) {
 436   $result = CRM_Campaign_BAO_Survey::releaseRespondent($params);
 437
 438   if ($result['is_error'] == 0) {
 439     return civicrm_api3_create_success();
 440   }
 441   else {
 442     return civicrm_api3_create_error($result['messages']);
 443   }
 444 }
 445
 446 /**
 447  * Merges given pair of duplicate contacts.
 448  *
 449  * @param array $params
 450  *   Input parameters.
 451  *
 452  * @return array
 453  *   API Result Array
 454  */
 455 function civicrm_api3_job_process_batch_merge($params) {
 456   $rgid = CRM_Utils_Array::value('rgid', $params);
 457   $gid = CRM_Utils_Array::value('gid', $params);
 458
 459   $mode = CRM_Utils_Array::value('mode', $params, 'safe');
 460   $autoFlip = CRM_Utils_Array::value('auto_flip', $params, TRUE);
 461
 462   $result = CRM_Dedupe_Merger::batchMerge($rgid, $gid, $mode, $autoFlip);
 463
 464   if ($result['is_error'] == 0) {
 465     return civicrm_api3_create_success();
 466   }
 467   else {
 468     return civicrm_api3_create_error($result['messages']);
 469   }
 470 }
 471
 472 /**
 473  * Metadata for batch merge function.
 474  *
 475  * @param $params
 476  */
 477 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
 478   $params['rgid'] = array(
 479     'title' => 'rule group id',
 480     'type' => CRM_Utils_Type::T_INT,
 481   );
 482   $params['gid'] = array(
 483     'title' => 'group id',
 484     'type' => CRM_Utils_Type::T_INT,
 485   );
 486   $params['mode'] = array(
 487     'title' => 'Mode',
 488     '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.',
 489     'type' => CRM_Utils_Type::T_STRING,
 490   );
 491   $params['auto_flip'] = array(
 492     'title' => 'Auto Flip',
 493     'description' => 'let the api decide which contact to retain and which to delete?',
 494     'type' => CRM_Utils_Type::T_BOOLEAN,
 495   );
 496 }
 497
 498 /**
 499  * Runs handlePaymentCron method in the specified payment processor.
 500  *
 501  * @param array $params
 502  *   Input parameters.
 503  *
 504  * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function
 505  * for retrieval via getfields.
 506  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
 507  */
 508 function civicrm_api3_job_run_payment_cron($params) {
 509
 510   // live mode
 511   CRM_Core_Payment::handlePaymentMethod(
 512     'PaymentCron',
 513     array_merge(
 514       $params,
 515       array(
 516         'caller' => 'api',
 517       )
 518     )
 519   );
 520
 521   // test mode
 522   CRM_Core_Payment::handlePaymentMethod(
 523     'PaymentCron',
 524     array_merge(
 525       $params,
 526       array(
 527         'mode' => 'test',
 528       )
 529     )
 530   );
 531 }
 532
 533 /**
 534  * This api cleans up all the old session entries and temp tables.
 535  *
 536  * We recommend that sites run this on an hourly basis.
 537  *
 538  * @param array $params
 539  *   Sends in various config parameters to decide what needs to be cleaned.
 540  */
 541 function civicrm_api3_job_cleanup($params) {
 542   $session   = CRM_Utils_Array::value('session', $params, TRUE);
 543   $tempTable = CRM_Utils_Array::value('tempTables', $params, TRUE);
 544   $jobLog    = CRM_Utils_Array::value('jobLog', $params, TRUE);
 545   $prevNext  = CRM_Utils_Array::value('prevNext', $params, TRUE);
 546   $dbCache   = CRM_Utils_Array::value('dbCache', $params, FALSE);
 547   $memCache  = CRM_Utils_Array::value('memCache', $params, FALSE);
 548
 549   if ($session || $tempTable || $prevNext) {
 550     CRM_Core_BAO_Cache::cleanup($session, $tempTable, $prevNext);
 551   }
 552
 553   if ($jobLog) {
 554     CRM_Core_BAO_Job::cleanup();
 555   }
 556
 557   if ($dbCache) {
 558     CRM_Core_Config::clearDBCache();
 559   }
 560
 561   if ($memCache) {
 562     CRM_Utils_System::flushCache();
 563   }
 564 }
 565
 566 /**
 567  * Set expired relationships to disabled.
 568  *
 569  * @param array $params
 570  *
 571  * @return array
 572  * @throws \API_Exception
 573  */
 574 function civicrm_api3_job_disable_expired_relationships($params) {
 575   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
 576   if (!$result) {
 577     throw new API_Exception('Failed to disable all expired relationships.');
 578   }
 579   return civicrm_api3_create_success(1, $params, 'Job', 'disable_expired_relationships');
 580 }
 581
 582 /**
 583  * This api reloads all the smart groups.
 584  *
 585  * If the org has a large number of smart groups it is recommended that they use the limit clause
 586  * to limit the number of smart groups evaluated on a per job basis.
 587  *
 588  * Might also help to increase the smartGroupCacheTimeout and use the cache.
 589  *
 590  * @param array $params
 591  *
 592  * @return array
 593  * @throws \API_Exception
 594  */
 595 function civicrm_api3_job_group_rebuild($params) {
 596   $lock = new CRM_Core_Lock('civimail.job.groupRebuild');
 597   if (!$lock->isAcquired()) {
 598     throw new API_Exception('Could not acquire lock, another EmailProcessor process is running');
 599   }
 600
 601   $limit = CRM_Utils_Array::value('limit', $params, 0);
 602
 603   CRM_Contact_BAO_GroupContactCache::loadAll(NULL, $limit);
 604   $lock->release();
 605
 606   return civicrm_api3_create_success();
 607 }