api/v3/Job.php

   1 <?php
   2 // $Id$
   3
   4 /*
   5  +--------------------------------------------------------------------+
   6  | CiviCRM version 4.3                                                |
   7  +--------------------------------------------------------------------+
   8  | Copyright CiviCRM LLC (c) 2004-2013                                |
   9  +--------------------------------------------------------------------+
  10  | This file is a part of CiviCRM.                                    |
  11  |                                                                    |
  12  | CiviCRM is free software; you can copy, modify, and distribute it  |
  13  | under the terms of the GNU Affero General Public License           |
  14  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  15  |                                                                    |
  16  | CiviCRM is distributed in the hope that it will be useful, but     |
  17  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  18  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  19  | See the GNU Affero General Public License for more details.        |
  20  |                                                                    |
  21  | You should have received a copy of the GNU Affero General Public   |
  22  | License and the CiviCRM Licensing Exception along                  |
  23  | with this program; if not, contact CiviCRM LLC                     |
  24  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  25  | GNU Affero General Public License or the licensing of CiviCRM,     |
  26  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  27  +--------------------------------------------------------------------+
  28 */
  29
  30 /**
  31  * new version of civicrm apis. See blog post at
  32  * http://civicrm.org/node/131
  33  * @todo Write sth
  34  *
  35  * @package CiviCRM_APIv3
  36  * @subpackage API_Job
  37  * @copyright CiviCRM LLC (c) 2004-2013
  38  * $Id: Contact.php 30879 2010-11-22 15:45:55Z shot $
  39  *
  40  */
  41
  42 /**
  43  * Include common API util functions
  44  */
  45 require_once 'api/v3/utils.php';
  46
  47 /**
  48  * Adjust metadata for "Create" action
  49  *
  50  * The metadata is used for setting defaults, documentation & validation
  51  * @param array $params array or parameters determined by getfields
  52  */
  53 function _civicrm_api3_job_create_spec(&$params) {
  54   $params['run_frequency']['api.required'] = 1;
  55   $params['name']['api.required'] = 1;
  56   $params['api_entity']['api.required'] = 1;
  57   $params['api_action']['api.required'] = 1;
  58
  59   $params['domain_id']['api.default'] = CRM_Core_Config::domainID();
  60   $params['is_active']['api.default'] = 1;
  61 }
  62
  63 /**
  64  * Function to create scheduled job
  65  *
  66  * @param  array $params   Associative array of property name/value pairs to insert in new job.
  67  *
  68  * @return success or error
  69  * {@getfields Job_create}
  70  * @access public
  71  * {@schema Core/Job.xml}
  72  */
  73 function civicrm_api3_job_create($params) {
  74   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  75 }
  76
  77 /**
  78  * Retrieve one or more job
  79  * @param  array input parameters
  80  * @return  array api result array
  81  * {@getfields email_get}
  82  * @access public
  83  */
  84 function civicrm_api3_job_get($params) {
  85   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  86 }
  87
  88 /**
  89  * Delete a job
  90  *
  91  * @param int $id
  92  *
  93  * @return array API Result Array
  94  * {@getfields Job_delete}
  95  * @static void
  96  * @access public
  97  */
  98 function civicrm_api3_job_delete($params) {
  99   if ($params['id'] != NULL && !CRM_Utils_Rule::integer($params['id'])) {
 100     return civicrm_api3_create_error('Invalid value for job ID');
 101   }
 102
 103   $result = CRM_Core_BAO_Job::del($params['id']);
 104   if (!$result) {
 105     return civicrm_api3_create_error('Could not delete job');
 106   }
 107   return civicrm_api3_create_success($result, $params, 'job', 'delete');
 108 }
 109
 110 /**
 111  * Dumb wrapper to execute scheduled jobs. Always creates success - errors
 112  * and results are handled in the job log.
 113  *
 114  * @param  array       $params (reference ) input parameters
 115  *
 116  * @return array API Result Array
 117  *
 118  * @static void
 119  * @access public
 120  *
 121  */
 122 function civicrm_api3_job_execute($params) {
 123   $facility = new CRM_Core_JobManager();
 124   $facility->execute(FALSE);
 125
 126   // always creates success - results are handled elsewhere
 127   return civicrm_api3_create_success();
 128 }
 129
 130 /**
 131  * Adjust Metadata for Execute action
 132  *
 133  * @param array $params array or parameters determined by getfields
 134  */
 135 function _civicrm_api3_job_execute_spec(&$params) {
 136 }
 137
 138 /**
 139  * Geocode group of contacts based on given params
 140  *
 141  * @param  array       $params (reference ) input parameters
 142  *
 143  * @return array API Result Array
 144  * {@getfields contact_geocode}
 145  *
 146  * @static void
 147  * @access public
 148  *
 149  *
 150  */
 151 function civicrm_api3_job_geocode($params) {
 152   $gc = new CRM_Utils_Address_BatchUpdate($params);
 153
 154
 155   $result = $gc->run();
 156
 157   if ($result['is_error'] == 0) {
 158     return civicrm_api3_create_success($result['messages']);
 159   }
 160   else {
 161     return civicrm_api3_create_error($result['messages']);
 162   }
 163 }
 164 /**
 165  * First check on Code documentation
 166  */
 167 function _civicrm_api3_job_geocode_spec(&$params) {
 168   $params['start'] = array('title' => 'Start Date');
 169   $params['end'] = array('title' => 'End Date');
 170   $params['geocoding'] = array('title' => 'Is this for GeoCoding? (I think this is a 1,0 field?)');
 171   $params['parse'] = array('title' => 'Is this for parsing? (I think this is a 1,0 field?)');
 172   $params['throttle'] = array('title' => 'Throttle? (no idea what you enter in this field)');
 173 }
 174
 175 /**
 176  * Send the scheduled reminders for all contacts (either for activities or events)
 177  *
 178  * @param  array       $params (reference ) input parameters
 179  *                        now - the time to use, in YmdHis format
 180  *                            - makes testing a bit simpler since we can simulate past/future time
 181  *
 182  * @return boolean        true if success, else false
 183  * @static void
 184  * @access public
 185  *
 186  */
 187 function civicrm_api3_job_send_reminder($params) {
 188   $lock = new CRM_Core_Lock('civimail.job.EmailProcessor');
 189   if (!$lock->isAcquired()) {
 190     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 191   }
 192
 193   $result = CRM_Core_BAO_ActionSchedule::processQueue(CRM_Utils_Array::value('now', $params));
 194   $lock->release();
 195
 196   if ($result['is_error'] == 0) {
 197     return civicrm_api3_create_success();
 198   }
 199   else {
 200     return civicrm_api3_create_error($result['messages']);
 201   }
 202 }
 203
 204 /**
 205  * Execute a specific report instance and send the output via email
 206  *
 207  * @param  array       $params (reference ) input parameters
 208  *                        sendmail - Boolean - should email be sent?, required
 209  *                        instanceId - Integer - the report instance ID
 210  *                        resetVal - Integer - should we reset form state (always true)?
 211  *
 212  * @return boolean        true if success, else false
 213  * @static void
 214  * @access public
 215  *
 216  */
 217 function civicrm_api3_job_mail_report($params) {
 218   $result = CRM_Report_Utils_Report::processReport($params);
 219
 220   if ($result['is_error'] == 0) {
 221     // this should be handling by throwing exceptions but can't remove until we can test that.
 222     return civicrm_api3_create_success();
 223   }
 224   else {
 225     return civicrm_api3_create_error($result['messages']);
 226   }
 227 }
 228
 229 /**
 230  *
 231  * This method allows to update Email Greetings, Postal Greetings and Addressee for a specific contact type.
 232  * IMPORTANT: You must first create valid option value before using via admin interface.
 233  * Check option lists for Email Greetings, Postal Greetings and Addressee
 234  *
 235  *                        id - Integer - greetings option group
 236  *
 237  * @return boolean        true if success, else false
 238  * @static
 239  * @access public
 240  *
 241  */
 242 function civicrm_api3_job_update_greeting($params) {
 243
 244   if (isset($params['ct']) && isset($params['gt'])) {
 245     $ct = $gt = array();
 246     $ct = explode(',', $params['ct']);
 247     $gt = explode(',', $params['gt']);
 248     foreach ($ct as $ctKey => $ctValue) {
 249       foreach ($gt as $gtKey => $gtValue) {
 250         $params['ct'] = trim($ctValue);
 251         $params['gt'] = trim($gtValue);
 252         $result[] = CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
 253       }
 254     }
 255   }
 256   else {
 257     $result = CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
 258   }
 259
 260   foreach ($result as $resultKey => $resultValue) {
 261     if ($resultValue['is_error'] == 0) {
 262       //really we should rely on the exception mechanism here - but we need to test that before removing this line
 263       return civicrm_api3_create_success();
 264     }
 265     else {
 266       return civicrm_api3_create_error($resultValue['messages']);
 267     }
 268   }
 269 }
 270
 271 /**
 272  * Adjust Metadata for Get action
 273 *
 274 * The metadata is used for setting defaults, documentation & validation
 275 * @param array $params array or parameters determined by getfields
 276 */
 277 function _civicrm_api3_job_update_greeting_spec(&$params) {
 278   $params['ct'] = array(
 279     'api.required' => 1,
 280     'title' => 'Contact Type',
 281     'type' => CRM_Utils_Type::T_STRING,
 282   );
 283   $params['gt'] = array(
 284       'api.required' => 1,
 285       'title' => 'Greeting Type',
 286       'type' => CRM_Utils_Type::T_STRING,
 287   );
 288 }
 289
 290 /**
 291  * Mass update pledge statuses
 292  *
 293  * @param  array       $params (reference ) input parameters
 294  *
 295  * @return boolean        true if success, else false
 296  * @static
 297  * @access public
 298  *
 299  */
 300 function civicrm_api3_job_process_pledge($params) {
 301   // *** Uncomment the next line if you want automated reminders to be sent
 302   // $params['send_reminders'] = true;
 303   $result = CRM_Pledge_BAO_Pledge::updatePledgeStatus($params);
 304
 305   if ($result['is_error'] == 0) {
 306     // experiment: detailed execution log is a result here
 307     return civicrm_api3_create_success($result['messages']);
 308   }
 309   else {
 310     return civicrm_api3_create_error($result['error_message']);
 311   }
 312 }
 313
 314 /**
 315  * Process mail queue
 316  *
 317  * @param array $params
 318  *
 319  * @return array
 320  */
 321 function civicrm_api3_job_process_mailing($params) {
 322
 323   if (!CRM_Mailing_BAO_Mailing::processQueue()) {
 324     return civicrm_api3_create_error('Process Queue failed');
 325   }
 326   else {
 327     $values = array();
 328     return civicrm_api3_create_success($values, $params, 'mailing', 'process');
 329   }
 330 }
 331
 332 /**
 333  * Process sms queue
 334  *
 335  * @param array $params
 336  *
 337  * @return array
 338  */
 339 function civicrm_api3_job_process_sms($params) {
 340   if (!CRM_Mailing_BAO_Mailing::processQueue('sms')) {
 341     return civicrm_api3_create_error('Process Queue failed');
 342   }
 343   else {
 344     $values = array();
 345     return civicrm_api3_create_success($values, $params, 'mailing', 'process');
 346   }
 347 }
 348
 349 /**
 350  * Job to get mail responses from civimailing
 351  */
 352 function civicrm_api3_job_fetch_bounces($params) {
 353   $lock = new CRM_Core_Lock('civimail.job.EmailProcessor');
 354   if (!$lock->isAcquired()) {
 355     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 356   }
 357   if (!CRM_Utils_Mail_EmailProcessor::processBounces()) {
 358     $lock->release();
 359     return civicrm_api3_create_error('Process Bounces failed');
 360   }
 361   $lock->release();
 362
 363   // FIXME: processBounces doesn't return true/false on success/failure
 364   $values = array();
 365   return civicrm_api3_create_success($values, $params, 'mailing', 'bounces');
 366 }
 367
 368 /**
 369  * Job to get mail and create activities
 370  */
 371 function civicrm_api3_job_fetch_activities($params) {
 372   $lock = new CRM_Core_Lock('civimail.job.EmailProcessor');
 373   if (!$lock->isAcquired()) {
 374     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 375   }
 376
 377   try {
 378     CRM_Utils_Mail_EmailProcessor::processActivities();
 379     $values = array( );
 380     $lock->release();
 381     return civicrm_api3_create_success($values, $params,'mailing','activities');
 382   } catch (Exception $e) {
 383     $lock->release();
 384     return civicrm_api3_create_error('Process Activities failed');
 385   }
 386 }
 387
 388 /**
 389  * Process participant statuses
 390  *
 391  * @param  array   $params           (reference ) input parameters
 392  *
 393  * @return array (reference )        array of properties, if error an array with an error id and error message
 394  * @access public
 395  */
 396 function civicrm_api3_job_process_participant($params) {
 397   $result = CRM_Event_BAO_ParticipantStatusType::process($params);
 398
 399   if (!$result['is_error']) {
 400     return civicrm_api3_create_success(implode("\r\r", $result['messages']));
 401   }
 402   else {
 403     return civicrm_api3_create_error('Error while processing participant statuses');
 404   }
 405 }
 406
 407
 408 /**
 409  * This api checks and updates the status of all membership records for a given domain using the calc_membership_status and
 410  * update_contact_membership APIs.
 411  *
 412  * IMPORTANT:
 413  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
 414  *
 415  * @param  array $params input parameters NOT USED
 416  *
 417  * @return boolean true if success, else false
 418  * @static void
 419  * @access public
 420  */
 421 function civicrm_api3_job_process_membership($params) {
 422   $lock = new CRM_Core_Lock('civimail.job.updateMembership');
 423   if (!$lock->isAcquired()) {
 424     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 425   }
 426
 427   $result = CRM_Member_BAO_Membership::updateAllMembershipStatus();
 428   $lock->release();
 429
 430   if ($result['is_error'] == 0) {
 431     return civicrm_api3_create_success($result['messages']);
 432   }
 433   else {
 434     return civicrm_api3_create_error($result['messages']);
 435   }
 436 }
 437
 438 /**
 439  * This api checks and updates the status of all survey respondants.
 440  *
 441  * @param  array       $params (reference ) input parameters
 442  *
 443  * @return boolean        true if success, else false
 444  * @static void
 445  * @access public
 446  */
 447 function civicrm_api3_job_process_respondent($params) {
 448   $result = CRM_Campaign_BAO_Survey::releaseRespondent($params);
 449
 450   if ($result['is_error'] == 0) {
 451     return civicrm_api3_create_success();
 452   }
 453   else {
 454     return civicrm_api3_create_error($result['messages']);
 455   }
 456 }
 457
 458 /**
 459  * Merges given pair of duplicate contacts.
 460  *
 461  * @param  array   $params   input parameters
 462  *
 463  * Allowed @params array keys are:
 464  * {int     $rgid        rule group id}
 465  * {int     $gid         group id}
 466  * {string  mode        helps decide how to behave when there are conflicts.
 467  *                      A 'safe' value skips the merge if there are no conflicts. Does a force merge otherwise.}
 468  * {boolean auto_flip   wether to let api decide which contact to retain and which to delete.}
 469  *
 470  * @return array  API Result Array
 471  *
 472  * @static void
 473  * @access public
 474  */
 475 function civicrm_api3_job_process_batch_merge($params) {
 476   $rgid = CRM_Utils_Array::value('rgid', $params);
 477   $gid = CRM_Utils_Array::value('gid', $params);
 478
 479   $mode = CRM_Utils_Array::value('mode', $params, 'safe');
 480   $autoFlip = CRM_Utils_Array::value('auto_flip', $params, TRUE);
 481
 482   $result = CRM_Dedupe_Merger::batchMerge($rgid, $gid, $mode, $autoFlip);
 483
 484   if ($result['is_error'] == 0) {
 485     return civicrm_api3_create_success();
 486   }
 487   else {
 488     return civicrm_api3_create_error($result['messages']);
 489   }
 490 }
 491
 492 /**
 493  * Runs handlePaymentCron method in the specified payment processor
 494  *
 495  * @param  array   $params   input parameters
 496  *
 497  * Expected @params array keys are:
 498  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
 499  *
 500  * @access public
 501  */
 502 function civicrm_api3_job_run_payment_cron($params) {
 503
 504   // live mode
 505   CRM_Core_Payment::handlePaymentMethod(
 506     'PaymentCron',
 507     array_merge(
 508       $params,
 509       array(
 510         'caller' => 'api',
 511       )
 512     )
 513   );
 514
 515   // test mode
 516   CRM_Core_Payment::handlePaymentMethod(
 517     'PaymentCron',
 518     array_merge(
 519       $params,
 520       array(
 521         'mode' => 'test',
 522       )
 523     )
 524   );
 525 }
 526
 527 /**
 528  * This api cleans up all the old session entries and temp tables. We recommend that sites run this on an hourly basis
 529  *
 530  * @param  array    $params (reference ) - sends in various config parameters to decide what needs to be cleaned
 531  *
 532  * @return boolean  true if success, else false
 533  * @static void
 534  * @access public
 535  */
 536 function civicrm_api3_job_cleanup( $params ) {
 537   $session   = CRM_Utils_Array::value( 'session'   , $params, true  );
 538   $tempTable = CRM_Utils_Array::value( 'tempTables', $params, true  );
 539   $jobLog    = CRM_Utils_Array::value( 'jobLog'    , $params, true  );
 540   $prevNext  = CRM_Utils_Array::value( 'prevNext'  , $params, true  );
 541   $dbCache   = CRM_Utils_Array::value( 'dbCache'   , $params, false );
 542   $memCache  = CRM_Utils_Array::value( 'memCache'  , $params, false );
 543
 544   if ( $session || $tempTable || $prevNext ) {
 545     CRM_Core_BAO_Cache::cleanup( $session, $tempTable, $prevNext );
 546   }
 547
 548   if ( $jobLog ) {
 549     CRM_Core_BAO_Job::cleanup( );
 550   }
 551
 552   if ( $dbCache ) {
 553     CRM_Core_Config::clearDBCache( );
 554   }
 555
 556   if ( $memCache ) {
 557     CRM_Utils_System::flushCache( );
 558   }
 559 }
 560
 561 /**
 562  * Set expired relationships to disabled.
 563  *
 564  */
 565 function civicrm_api3_job_disable_expired_relationships($params) {
 566   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
 567   if ($result) {
 568     return civicrm_api3_create_success();
 569   }
 570   else {
 571     return civicrm_api3_create_error('Failed to disable all expired relationships.');
 572   }
 573 }
 574
 575 /**
 576  * This api reloads all the smart groups. If the org has a large number of smart groups
 577  * it is recommended that they use the limit clause to limit the number of smart groups
 578  * evaluated on a per job basis. Might also help to increase the smartGroupCacheTimeout
 579  * and use the cache
 580  */
 581 function civicrm_api3_job_group_rebuild( $params ) {
 582   $lock = new CRM_Core_Lock('civimail.job.groupRebuild');
 583   if (!$lock->isAcquired()) {
 584     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 585   }
 586
 587   $limit = CRM_Utils_Array::value( 'limit', $params, 0 );
 588
 589   CRM_Contact_BAO_GroupContactCache::loadAll(null, $limit);
 590   $lock->release();
 591
 592   return civicrm_api3_create_success();
 593 }