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