X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FJob.php;h=b12d4ae515aa2d4937e478b1e9160d2cf9029f16;hb=61fe4988936f8bb28644451af665a141d6eb4c7b;hp=46e62c2a4b5f2fe6de32f83fd4bdf48ecdff4f52;hpb=e9aca61e8b08d5ae372621c4397108b8f2ec28ba;p=civicrm-core.git diff --git a/api/v3/Job.php b/api/v3/Job.php index 46e62c2a4b..b12d4ae515 100644 --- a/api/v3/Job.php +++ b/api/v3/Job.php @@ -25,25 +25,25 @@ | GNU Affero General Public License or the licensing of CiviCRM, | | see the CiviCRM license FAQ at http://civicrm.org/licensing | +--------------------------------------------------------------------+ -*/ + */ /** - * new version of civicrm apis. See blog post at + * new version of civicrm APIs. See blog post at * http://civicrm.org/node/131 - * @todo Write sth * * @package CiviCRM_APIv3 * @subpackage API_Job * @copyright CiviCRM LLC (c) 2004-2014 * $Id: Contact.php 30879 2010-11-22 15:45:55Z shot $ - * */ /** - * Adjust metadata for "Create" action + * Adjust metadata for "Create" action. + * + * The metadata is used for setting defaults, documentation & validation. * - * The metadata is used for setting defaults, documentation & validation - * @param array $params array or parameters determined by getfields + * @param array $params + * Array or parameters determined by getfields. */ function _civicrm_api3_job_create_spec(&$params) { $params['run_frequency']['api.required'] = 1; @@ -56,89 +56,79 @@ function _civicrm_api3_job_create_spec(&$params) { } /** - * create scheduled job + * Create scheduled job. * - * @param array $params Associative array of property name/value pairs to insert in new job. + * @param array $params + * Associative array of property name/value pairs to insert in new job. * - * @return success or error - * {@getfields Job_create} - * @access public - * {@schema Core/Job.xml} + * @return array */ function civicrm_api3_job_create($params) { return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params); } /** - * Retrieve one or more job - * @param array input parameters - * @return array api result array - * {@getfields email_get} - * @access public + * Retrieve one or more job. + * + * @param array $params + * input parameters + * + * @return array */ function civicrm_api3_job_get($params) { return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params); } /** - * Delete a job + * Delete a job. * * @param array $params - * - * @return array API Result Array - * {@getfields Job_delete} - * @static void - * @access public */ function civicrm_api3_job_delete($params) { _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params); } /** - * Dumb wrapper to execute scheduled jobs. Always creates success - errors - * and results are handled in the job log. + * Dumb wrapper to execute scheduled jobs. * - * @param array $params (reference ) input parameters + * Always creates success - errors and results are handled in the job log. * - * @return array API Result Array - * - * @static void - * @access public + * @param array $params + * input parameters (unused). * + * @return array + * API Result Array */ function civicrm_api3_job_execute($params) { + $facility = new CRM_Core_JobManager(); $facility->execute(FALSE); - // always creates success - results are handled elsewhere - return civicrm_api3_create_success(); + // Always creates success - results are handled elsewhere. + return civicrm_api3_create_success(1, $params); } /** - * Adjust Metadata for Execute action + * Adjust Metadata for Execute action. * - * @param array $params array or parameters determined by getfields + * @param array $params + * Array or parameters determined by getfields. */ function _civicrm_api3_job_execute_spec(&$params) { } /** - * Geocode group of contacts based on given params - * - * @param array $params (reference ) input parameters - * - * @return array API Result Array - * {@getfields contact_geocode} - * - * @static void - * @access public + * Geocode group of contacts based on given params. * + * @param array $params + * input parameters. * + * @return array + * API Result Array */ function civicrm_api3_job_geocode($params) { $gc = new CRM_Utils_Address_BatchUpdate($params); - $result = $gc->run(); if ($result['is_error'] == 0) { @@ -150,7 +140,7 @@ function civicrm_api3_job_geocode($params) { } /** - * First check on Code documentation + * First check on Code documentation. * * @param array $params */ @@ -159,25 +149,23 @@ function _civicrm_api3_job_geocode_spec(&$params) { $params['end'] = array('title' => 'End Date'); $params['geocoding'] = array('title' => 'Geocode address?'); $params['parse'] = array('title' => 'Parse street address?'); - $params['throttle'] = array('title' => 'Throttle? if enabled, geocodes at a slow rate'); + $params['throttle'] = array('title' => 'Throttle? if enabled, geo-codes at a slow rate'); } /** - * Send the scheduled reminders for all contacts (either for activities or events) + * Send the scheduled reminders for all contacts (either for activities or events). * - * @param array $params (reference ) input parameters + * @param array $params + * (reference ) input parameters. * now - the time to use, in YmdHis format * - makes testing a bit simpler since we can simulate past/future time * - * @return boolean true if success, else false - * @static void - * @access public - * + * @return array */ function civicrm_api3_job_send_reminder($params) { //note that $params['rowCount' can be overridden by one of the preferred syntaxes ($options['limit'] = x //It's not clear whether than syntax can be passed in via the UI config - but this keeps the pre 4.4.4 behaviour - // in that case (ie. makes it unconfigurable via the UI). Another approach would be to set a default of 0 + // in that case (ie. makes it non-configurable via the UI). Another approach would be to set a default of 0 // in the _spec function - but since that is a deprecated value it seems more contentious than this approach $params['rowCount'] = 0; $lock = new CRM_Core_Lock('civimail.job.EmailProcessor'); @@ -196,31 +184,31 @@ function civicrm_api3_job_send_reminder($params) { } } /** - * Adjust metadata for "send_reminder" action + * Adjust metadata for "send_reminder" action. * - * The metadata is used for setting defaults, documentation & validation - * @param array $params array or parameters determined by getfields + * The metadata is used for setting defaults, documentation & validation. + * + * @param array $params + * Array or parameters determined by getfields. */ function _civicrm_api3_job_send_reminder(&$params) { //@todo this function will now take all fields in action_schedule as params // as it is calling the api fn to set the filters - update getfields to reflect $params['id'] = array( 'type' => CRM_Utils_Type::T_INT, - 'title' => 'Action Schedule ID' + 'title' => 'Action Schedule ID', ); } /** - * Execute a specific report instance and send the output via email + * Execute a specific report instance and send the output via email. * - * @param array $params (reference ) input parameters + * @param array $params + * (reference ) input parameters. * sendmail - Boolean - should email be sent?, required * instanceId - Integer - the report instance ID * resetVal - Integer - should we reset form state (always true)? * - * @return boolean true if success, else false - * @static void - * @access public - * + * @return array */ function civicrm_api3_job_mail_report($params) { $result = CRM_Report_Utils_Report::processReport($params); @@ -235,54 +223,43 @@ function civicrm_api3_job_mail_report($params) { } /** - * * This method allows to update Email Greetings, Postal Greetings and Addressee for a specific contact type. + * * IMPORTANT: You must first create valid option value before using via admin interface. * Check option lists for Email Greetings, Postal Greetings and Addressee * - * id - Integer - greetings option group + * @todo - is this here by mistake or should it be added to _spec function :id - Integer - greetings option group. * * @param array $params * - * @return boolean true if success, else false - * @static - * @access public + * @return array */ function civicrm_api3_job_update_greeting($params) { - if (isset($params['ct']) && isset($params['gt'])) { - $ct = $gt = array(); $ct = explode(',', $params['ct']); $gt = explode(',', $params['gt']); foreach ($ct as $ctKey => $ctValue) { foreach ($gt as $gtKey => $gtValue) { $params['ct'] = trim($ctValue); $params['gt'] = trim($gtValue); - $result[] = CRM_Contact_BAO_Contact_Utils::updateGreeting($params); + CRM_Contact_BAO_Contact_Utils::updateGreeting($params); } } } else { - $result = CRM_Contact_BAO_Contact_Utils::updateGreeting($params); - } - - foreach ($result as $resultKey => $resultValue) { - if ($resultValue['is_error'] == 0) { - //really we should rely on the exception mechanism here - but we need to test that before removing this line - return civicrm_api3_create_success(); - } - else { - return civicrm_api3_create_error($resultValue['messages']); - } + CRM_Contact_BAO_Contact_Utils::updateGreeting($params); } + return civicrm_api3_create_success(); } /** - * Adjust Metadata for Get action -* -* The metadata is used for setting defaults, documentation & validation -* @param array $params array or parameters determined by getfields -*/ + * Adjust Metadata for Get action. + * + * The metadata is used for setting defaults, documentation & validation. + * + * @param array $params + * Array or parameters determined by getfields. + */ function _civicrm_api3_job_update_greeting_spec(&$params) { $params['ct'] = array( 'api.required' => 1, @@ -290,21 +267,18 @@ function _civicrm_api3_job_update_greeting_spec(&$params) { 'type' => CRM_Utils_Type::T_STRING, ); $params['gt'] = array( - 'api.required' => 1, - 'title' => 'Greeting Type', - 'type' => CRM_Utils_Type::T_STRING, + 'api.required' => 1, + 'title' => 'Greeting Type', + 'type' => CRM_Utils_Type::T_STRING, ); } /** - * Mass update pledge statuses - * - * @param array $params (reference ) input parameters + * Mass update pledge statuses. * - * @return boolean true if success, else false - * @static - * @access public + * @param array $params * + * @return array */ function civicrm_api3_job_process_pledge($params) { // *** Uncomment the next line if you want automated reminders to be sent @@ -321,7 +295,7 @@ function civicrm_api3_job_process_pledge($params) { } /** - * Process mail queue + * Process mail queue. * * @param array $params * @@ -339,7 +313,7 @@ function civicrm_api3_job_process_mailing($params) { } /** - * Process sms queue + * Process sms queue. * * @param array $params * @@ -356,7 +330,7 @@ function civicrm_api3_job_process_sms($params) { } /** - * Job to get mail responses from civimailing + * Job to get mail responses from civiMailing. * * @param array $params * @@ -379,7 +353,7 @@ function civicrm_api3_job_fetch_bounces($params) { } /** - * Job to get mail and create activities + * Job to get mail and create activities. * * @param array $params * @@ -393,22 +367,24 @@ function civicrm_api3_job_fetch_activities($params) { try { CRM_Utils_Mail_EmailProcessor::processActivities(); - $values = array( ); + $values = array(); $lock->release(); - return civicrm_api3_create_success($values, $params,'mailing','activities'); - } catch (Exception $e) { + return civicrm_api3_create_success($values, $params, 'mailing', 'activities'); + } + catch (Exception $e) { $lock->release(); return civicrm_api3_create_error('Process Activities failed'); } } /** - * Process participant statuses + * Process participant statuses. * - * @param array $params (reference ) input parameters + * @param array $params + * Input parameters. * - * @return array (reference ) array of properties, if error an array with an error id and error message - * @access public + * @return array + * array of properties, if error an array with an error id and error message */ function civicrm_api3_job_process_participant($params) { $result = CRM_Event_BAO_ParticipantStatusType::process($params); @@ -423,17 +399,18 @@ function civicrm_api3_job_process_participant($params) { /** - * This api checks and updates the status of all membership records for a given domain using the calc_membership_status and - * update_contact_membership APIs. + * This api checks and updates the status of all membership records for a given domain. + * + * The function uses the calc_membership_status and update_contact_membership APIs. * * IMPORTANT: * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3. * - * @param array $params input parameters NOT USED + * @param array $params + * Input parameters NOT USED. * - * @return boolean true if success, else false - * @static void - * @access public + * @return bool + * true if success, else false */ function civicrm_api3_job_process_membership($params) { $lock = new CRM_Core_Lock('civimail.job.updateMembership'); @@ -445,7 +422,7 @@ function civicrm_api3_job_process_membership($params) { $lock->release(); if ($result['is_error'] == 0) { - return civicrm_api3_create_success($result['messages']); + return civicrm_api3_create_success($result['messages'], $params); } else { return civicrm_api3_create_error($result['messages']); @@ -453,13 +430,13 @@ function civicrm_api3_job_process_membership($params) { } /** - * This api checks and updates the status of all survey respondants. + * This api checks and updates the status of all survey respondents. * - * @param array $params (reference ) input parameters + * @param array $params + * (reference ) input parameters. * - * @return boolean true if success, else false - * @static void - * @access public + * @return bool + * true if success, else false */ function civicrm_api3_job_process_respondent($params) { $result = CRM_Campaign_BAO_Survey::releaseRespondent($params); @@ -475,19 +452,11 @@ function civicrm_api3_job_process_respondent($params) { /** * Merges given pair of duplicate contacts. * - * @param array $params input parameters - * - * Allowed @params array keys are: - * {int $rgid rule group id} - * {int $gid group id} - * {string mode helps decide how to behave when there are conflicts. - * A 'safe' value skips the merge if there are no conflicts. Does a force merge otherwise.} - * {boolean auto_flip wether to let api decide which contact to retain and which to delete.} - * - * @return array API Result Array + * @param array $params + * Input parameters. * - * @static void - * @access public + * @return array + * API Result Array */ function civicrm_api3_job_process_batch_merge($params) { $rgid = CRM_Utils_Array::value('rgid', $params); @@ -507,14 +476,40 @@ function civicrm_api3_job_process_batch_merge($params) { } /** - * Runs handlePaymentCron method in the specified payment processor + * Metadata for batch merge function. * - * @param array $params input parameters + * @param $params + */ +function _civicrm_api3_job_process_batch_merge_spec(&$params) { + $params['rgid'] = array( + 'title' => 'rule group id', + 'type' => CRM_Utils_Type::T_INT, + ); + $params['gid'] = array( + 'title' => 'group id', + 'type' => CRM_Utils_Type::T_INT, + ); + $params['mode'] = array( + 'title' => 'Mode', + 'description' => 'helps decide how to behave when there are conflicts. A \'safe\' value skips the merge if there are no conflicts. Does a force merge otherwise.', + 'type' => CRM_Utils_Type::T_STRING, + ); + $params['auto_flip'] = array( + 'title' => 'Auto Flip', + 'description' => 'let the api decide which contact to retain and which to delete?', + 'type' => CRM_Utils_Type::T_BOOLEAN, + ); +} + +/** + * Runs handlePaymentCron method in the specified payment processor. * - * Expected @params array keys are: - * {string 'processor_name' - the name of the payment processor, eg: Sagepay} + * @param array $params + * Input parameters. * - * @access public + * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function + * for retrieval via getfields. + * {string 'processor_name' - the name of the payment processor, eg: Sagepay} */ function civicrm_api3_job_run_payment_cron($params) { @@ -542,36 +537,35 @@ function civicrm_api3_job_run_payment_cron($params) { } /** - * This api cleans up all the old session entries and temp tables. We recommend that sites run this on an hourly basis + * This api cleans up all the old session entries and temp tables. * - * @param array $params (reference ) - sends in various config parameters to decide what needs to be cleaned + * We recommend that sites run this on an hourly basis. * - * @return boolean true if success, else false - * @static void - * @access public + * @param array $params + * Sends in various config parameters to decide what needs to be cleaned. */ -function civicrm_api3_job_cleanup( $params ) { - $session = CRM_Utils_Array::value( 'session' , $params, true ); - $tempTable = CRM_Utils_Array::value( 'tempTables', $params, true ); - $jobLog = CRM_Utils_Array::value( 'jobLog' , $params, true ); - $prevNext = CRM_Utils_Array::value( 'prevNext' , $params, true ); - $dbCache = CRM_Utils_Array::value( 'dbCache' , $params, false ); - $memCache = CRM_Utils_Array::value( 'memCache' , $params, false ); +function civicrm_api3_job_cleanup($params) { + $session = CRM_Utils_Array::value('session', $params, TRUE); + $tempTable = CRM_Utils_Array::value('tempTables', $params, TRUE); + $jobLog = CRM_Utils_Array::value('jobLog', $params, TRUE); + $prevNext = CRM_Utils_Array::value('prevNext', $params, TRUE); + $dbCache = CRM_Utils_Array::value('dbCache', $params, FALSE); + $memCache = CRM_Utils_Array::value('memCache', $params, FALSE); - if ( $session || $tempTable || $prevNext ) { - CRM_Core_BAO_Cache::cleanup( $session, $tempTable, $prevNext ); + if ($session || $tempTable || $prevNext) { + CRM_Core_BAO_Cache::cleanup($session, $tempTable, $prevNext); } - if ( $jobLog ) { - CRM_Core_BAO_Job::cleanup( ); + if ($jobLog) { + CRM_Core_BAO_Job::cleanup(); } - if ( $dbCache ) { - CRM_Core_Config::clearDBCache( ); + if ($dbCache) { + CRM_Core_Config::clearDBCache(); } - if ( $memCache ) { - CRM_Utils_System::flushCache( ); + if ($memCache) { + CRM_Utils_System::flushCache(); } } @@ -581,36 +575,38 @@ function civicrm_api3_job_cleanup( $params ) { * @param array $params * * @return array + * @throws \API_Exception */ function civicrm_api3_job_disable_expired_relationships($params) { $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships(); - if ($result) { - return civicrm_api3_create_success(); - } - else { - return civicrm_api3_create_error('Failed to disable all expired relationships.'); + if (!$result) { + throw new API_Exception('Failed to disable all expired relationships.'); } + return civicrm_api3_create_success(1, $params); } /** - * This api reloads all the smart groups. If the org has a large number of smart groups - * it is recommended that they use the limit clause to limit the number of smart groups - * evaluated on a per job basis. Might also help to increase the smartGroupCacheTimeout - * and use the cache + * This api reloads all the smart groups. + * + * If the org has a large number of smart groups it is recommended that they use the limit clause + * to limit the number of smart groups evaluated on a per job basis. + * + * Might also help to increase the smartGroupCacheTimeout and use the cache. * * @param array $params * * @return array + * @throws \API_Exception */ function civicrm_api3_job_group_rebuild($params) { $lock = new CRM_Core_Lock('civimail.job.groupRebuild'); if (!$lock->isAcquired()) { - return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running'); + throw new API_Exception('Could not acquire lock, another EmailProcessor process is running'); } - $limit = CRM_Utils_Array::value( 'limit', $params, 0 ); + $limit = CRM_Utils_Array::value('limit', $params, 0); - CRM_Contact_BAO_GroupContactCache::loadAll(null, $limit); + CRM_Contact_BAO_GroupContactCache::loadAll(NULL, $limit); $lock->release(); return civicrm_api3_create_success();