api/v3/Job.php

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