X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FJob.php;h=c22003c6b4a819c7b8cf0878a540d15261f4af0a;hb=af3775b322b9e4f11d097067367f0ea7763f5f10;hp=77d62255511dac3bc720227cdaccd5613774a305;hpb=79c0e11ec92e46b36336f7903a537c5fcc78efef;p=civicrm-core.git diff --git a/api/v3/Job.php b/api/v3/Job.php index 77d6225551..c22003c6b4 100644 --- a/api/v3/Job.php +++ b/api/v3/Job.php @@ -1,6 +1,4 @@ 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, 'Job'); } /** - * Adjust Metadata for Execute action + * Adjust Metadata for Execute action. * * @param array $params - * Array or parameters determined by getfields. + * Array of parameters determined by getfields. */ function _civicrm_api3_job_execute_spec(&$params) { } /** - * Geocode group of contacts based on given 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 - * + * 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) { @@ -155,7 +134,7 @@ function civicrm_api3_job_geocode($params) { } /** - * First check on Code documentation + * First check on Code documentation. * * @param array $params */ @@ -164,26 +143,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. * 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'); @@ -202,11 +178,12 @@ 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. * - * The metadata is used for setting defaults, documentation & validation * @param array $params - * Array or parameters determined by getfields. + * Array of parameters determined by getfields. */ function _civicrm_api3_job_send_reminder(&$params) { //@todo this function will now take all fields in action_schedule as params @@ -217,7 +194,7 @@ function _civicrm_api3_job_send_reminder(&$params) { ); } /** - * 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. @@ -225,10 +202,7 @@ function _civicrm_api3_job_send_reminder(&$params) { * 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); @@ -243,55 +217,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 of parameters determined by getfields. + */ function _civicrm_api3_job_update_greeting_spec(&$params) { $params['ct'] = array( 'api.required' => 1, @@ -299,22 +261,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 + * Mass update pledge statuses. * * @param array $params - * (reference ) input parameters. - * - * @return boolean true if success, else false - * @static - * @access public * + * @return array */ function civicrm_api3_job_process_pledge($params) { // *** Uncomment the next line if you want automated reminders to be sent @@ -331,7 +289,7 @@ function civicrm_api3_job_process_pledge($params) { } /** - * Process mail queue + * Process mail queue. * * @param array $params * @@ -344,12 +302,12 @@ function civicrm_api3_job_process_mailing($params) { } else { $values = array(); - return civicrm_api3_create_success($values, $params, 'mailing', 'process'); + return civicrm_api3_create_success($values, $params, 'Job', 'process_mailing'); } } /** - * Process sms queue + * Process sms queue. * * @param array $params * @@ -361,12 +319,12 @@ function civicrm_api3_job_process_sms($params) { } else { $values = array(); - return civicrm_api3_create_success($values, $params, 'mailing', 'process'); + return civicrm_api3_create_success($values, $params, 'Job', 'process_sms'); } } /** - * Job to get mail responses from civimailing + * Job to get mail responses from civiMailing. * * @param array $params * @@ -385,11 +343,11 @@ function civicrm_api3_job_fetch_bounces($params) { // FIXME: processBounces doesn't return true/false on success/failure $values = array(); - return civicrm_api3_create_success($values, $params, 'mailing', 'bounces'); + return civicrm_api3_create_success($values, $params, 'Job', 'fetch_bounces'); } /** - * Job to get mail and create activities + * Job to get mail and create activities. * * @param array $params * @@ -405,7 +363,7 @@ function civicrm_api3_job_fetch_activities($params) { CRM_Utils_Mail_EmailProcessor::processActivities(); $values = array(); $lock->release(); - return civicrm_api3_create_success($values, $params,'mailing','activities'); + return civicrm_api3_create_success($values, $params, 'Job', 'fetch_activities'); } catch (Exception $e) { $lock->release(); @@ -414,13 +372,13 @@ function civicrm_api3_job_fetch_activities($params) { } /** - * Process participant statuses + * Process participant statuses. * * @param array $params - * (reference ) input parameters. + * 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); @@ -435,8 +393,9 @@ 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. @@ -444,9 +403,8 @@ function civicrm_api3_job_process_participant($params) { * @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'); @@ -458,7 +416,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, 'Job', 'process_membership'); } else { return civicrm_api3_create_error($result['messages']); @@ -466,14 +424,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. * - * @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); @@ -492,17 +449,8 @@ function civicrm_api3_job_process_respondent($params) { * @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 - * - * @static void - * @access public + * @return array + * API Result Array */ function civicrm_api3_job_process_batch_merge($params) { $rgid = CRM_Utils_Array::value('rgid', $params); @@ -522,15 +470,40 @@ function civicrm_api3_job_process_batch_merge($params) { } /** - * Runs handlePaymentCron method in the specified payment processor + * Metadata for batch merge function. + * + * @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. * * @param array $params * Input parameters. * - * Expected @params array keys are: + * 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} - * - * @access public */ function civicrm_api3_job_run_payment_cron($params) { @@ -558,22 +531,20 @@ 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); + $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); @@ -598,36 +569,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, 'Job', 'disable_expired_relationships'); } /** - * 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); - CRM_Contact_BAO_GroupContactCache::loadAll(null, $limit); + CRM_Contact_BAO_GroupContactCache::loadAll(NULL, $limit); $lock->release(); return civicrm_api3_create_success();