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