api/v3/Job.php

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