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   }
 410   catch (Exception $e) {
 411     $lock->release();
 412     return civicrm_api3_create_error('Process Activities failed');
 413   }
 414 }
 415
 416 /**
 417  * Process participant statuses
 418  *
 419  * @param array $params
 420  *   (reference ) input parameters.
 421  *
 422  * @return array (reference )        array of properties, if error an array with an error id and error message
 423  * @access public
 424  */
 425 function civicrm_api3_job_process_participant($params) {
 426   $result = CRM_Event_BAO_ParticipantStatusType::process($params);
 427
 428   if (!$result['is_error']) {
 429     return civicrm_api3_create_success(implode("\r\r", $result['messages']));
 430   }
 431   else {
 432     return civicrm_api3_create_error('Error while processing participant statuses');
 433   }
 434 }
 435
 436
 437 /**
 438  * This api checks and updates the status of all membership records for a given domain using the calc_membership_status and
 439  * update_contact_membership APIs.
 440  *
 441  * IMPORTANT:
 442  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
 443  *
 444  * @param array $params
 445  *   Input parameters NOT USED.
 446  *
 447  * @return boolean true if success, else false
 448  * @static void
 449  * @access public
 450  */
 451 function civicrm_api3_job_process_membership($params) {
 452   $lock = new CRM_Core_Lock('civimail.job.updateMembership');
 453   if (!$lock->isAcquired()) {
 454     return civicrm_api3_create_error('Could not acquire lock, another Membership Processing process is running');
 455   }
 456
 457   $result = CRM_Member_BAO_Membership::updateAllMembershipStatus();
 458   $lock->release();
 459
 460   if ($result['is_error'] == 0) {
 461     return civicrm_api3_create_success($result['messages']);
 462   }
 463   else {
 464     return civicrm_api3_create_error($result['messages']);
 465   }
 466 }
 467
 468 /**
 469  * This api checks and updates the status of all survey respondants.
 470  *
 471  * @param array $params
 472  *   (reference ) input parameters.
 473  *
 474  * @return boolean        true if success, else false
 475  * @static void
 476  * @access public
 477  */
 478 function civicrm_api3_job_process_respondent($params) {
 479   $result = CRM_Campaign_BAO_Survey::releaseRespondent($params);
 480
 481   if ($result['is_error'] == 0) {
 482     return civicrm_api3_create_success();
 483   }
 484   else {
 485     return civicrm_api3_create_error($result['messages']);
 486   }
 487 }
 488
 489 /**
 490  * Merges given pair of duplicate contacts.
 491  *
 492  * @param array $params
 493  *   Input parameters.
 494  *
 495  * Allowed @params array keys are:
 496  * {int     $rgid        rule group id}
 497  * {int     $gid         group id}
 498  * {string  mode        helps decide how to behave when there are conflicts.
 499  *                      A 'safe' value skips the merge if there are no conflicts. Does a force merge otherwise.}
 500  * {boolean auto_flip   wether to let api decide which contact to retain and which to delete.}
 501  *
 502  * @return array  API Result Array
 503  *
 504  * @static void
 505  * @access public
 506  */
 507 function civicrm_api3_job_process_batch_merge($params) {
 508   $rgid = CRM_Utils_Array::value('rgid', $params);
 509   $gid = CRM_Utils_Array::value('gid', $params);
 510
 511   $mode = CRM_Utils_Array::value('mode', $params, 'safe');
 512   $autoFlip = CRM_Utils_Array::value('auto_flip', $params, TRUE);
 513
 514   $result = CRM_Dedupe_Merger::batchMerge($rgid, $gid, $mode, $autoFlip);
 515
 516   if ($result['is_error'] == 0) {
 517     return civicrm_api3_create_success();
 518   }
 519   else {
 520     return civicrm_api3_create_error($result['messages']);
 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:
 531  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
 532  *
 533  * @access public
 534  */
 535 function civicrm_api3_job_run_payment_cron($params) {
 536
 537   // live mode
 538   CRM_Core_Payment::handlePaymentMethod(
 539     'PaymentCron',
 540     array_merge(
 541       $params,
 542       array(
 543         'caller' => 'api',
 544       )
 545     )
 546   );
 547
 548   // test mode
 549   CRM_Core_Payment::handlePaymentMethod(
 550     'PaymentCron',
 551     array_merge(
 552       $params,
 553       array(
 554         'mode' => 'test',
 555       )
 556     )
 557   );
 558 }
 559
 560 /**
 561  * This api cleans up all the old session entries and temp tables. We recommend that sites run this on an hourly basis
 562  *
 563  * @param array $params
 564  *   (reference ) - sends in various config parameters to decide what needs to be cleaned.
 565  *
 566  * @return boolean  true if success, else false
 567  * @static void
 568  * @access public
 569  */
 570 function civicrm_api3_job_cleanup($params) {
 571   $session   = CRM_Utils_Array::value('session'   , $params, true );
 572   $tempTable = CRM_Utils_Array::value('tempTables', $params, true );
 573   $jobLog    = CRM_Utils_Array::value('jobLog'    , $params, true );
 574   $prevNext  = CRM_Utils_Array::value('prevNext'  , $params, true );
 575   $dbCache   = CRM_Utils_Array::value('dbCache'   , $params, false);
 576   $memCache  = CRM_Utils_Array::value('memCache'  , $params, false);
 577
 578   if ($session || $tempTable || $prevNext) {
 579     CRM_Core_BAO_Cache::cleanup($session, $tempTable, $prevNext);
 580   }
 581
 582   if ($jobLog) {
 583     CRM_Core_BAO_Job::cleanup();
 584   }
 585
 586   if ($dbCache) {
 587     CRM_Core_Config::clearDBCache();
 588   }
 589
 590   if ($memCache) {
 591     CRM_Utils_System::flushCache();
 592   }
 593 }
 594
 595 /**
 596  * Set expired relationships to disabled.
 597  *
 598  * @param array $params
 599  *
 600  * @return array
 601  */
 602 function civicrm_api3_job_disable_expired_relationships($params) {
 603   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
 604   if ($result) {
 605     return civicrm_api3_create_success();
 606   }
 607   else {
 608     return civicrm_api3_create_error('Failed to disable all expired relationships.');
 609   }
 610 }
 611
 612 /**
 613  * This api reloads all the smart groups. If the org has a large number of smart groups
 614  * it is recommended that they use the limit clause to limit the number of smart groups
 615  * evaluated on a per job basis. Might also help to increase the smartGroupCacheTimeout
 616  * and use the cache
 617  *
 618  * @param array $params
 619  *
 620  * @return array
 621  */
 622 function civicrm_api3_job_group_rebuild($params) {
 623   $lock = new CRM_Core_Lock('civimail.job.groupRebuild');
 624   if (!$lock->isAcquired()) {
 625     return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
 626   }
 627
 628   $limit = CRM_Utils_Array::value('limit', $params, 0);
 629
 630   CRM_Contact_BAO_GroupContactCache::loadAll(null, $limit);
 631   $lock->release();
 632
 633   return civicrm_api3_create_success();
 634 }