X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FJob.php;h=9b56339c5006cd786a85f1fb8a0eddf621beaa40;hb=d142432b976440cc3ac9c52ce1e09a8e05c06017;hp=89aa49acb1b988749ca44c0aaa1e37e3d5c57514;hpb=1a4d747351c5963b20ad798f3bd0480eb772b13b;p=civicrm-core.git diff --git a/api/v3/Job.php b/api/v3/Job.php index 89aa49acb1..9b56339c50 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. + * input parameters. * * @return array * API Result Array @@ -132,7 +123,6 @@ function _civicrm_api3_job_execute_spec(&$params) { function civicrm_api3_job_geocode($params) { $gc = new CRM_Utils_Address_BatchUpdate($params); - $result = $gc->run(); if ($result['is_error'] == 0) { @@ -144,20 +134,36 @@ function civicrm_api3_job_geocode($params) { } /** - * First check on Code documentation + * First check on Code documentation. * * @param array $params */ function _civicrm_api3_job_geocode_spec(&$params) { - $params['start'] = array('title' => 'Start Date'); - $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['start'] = array( + 'title' => 'Start Date', + 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, + ); + $params['end'] = array( + 'title' => 'End Date', + 'type' => CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME, + ); + $params['geocoding'] = array( + 'title' => 'Geocode address?', + 'type' => CRM_Utils_Type::T_BOOLEAN, + ); + $params['parse'] = array( + 'title' => 'Parse street address?', + 'type' => CRM_Utils_Type::T_BOOLEAN, + ); + $params['throttle'] = array( + 'title' => 'Throttle?', + 'description' => 'If enabled, geo-codes at a slow rate', + 'type' => CRM_Utils_Type::T_BOOLEAN, + ); } /** - * 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. @@ -188,11 +194,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 @@ -203,7 +210,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. @@ -226,53 +233,42 @@ 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 + * @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 + * Adjust Metadata for Get 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_update_greeting_spec(&$params) { $params['ct'] = array( @@ -281,16 +277,17 @@ 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 + * * @return array */ function civicrm_api3_job_process_pledge($params) { @@ -308,7 +305,7 @@ function civicrm_api3_job_process_pledge($params) { } /** - * Process mail queue + * Process mail queue. * * @param array $params * @@ -321,12 +318,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 * @@ -338,12 +335,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 * @@ -362,11 +359,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 * @@ -382,7 +379,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(); @@ -391,10 +388,10 @@ function civicrm_api3_job_fetch_activities($params) { } /** - * Process participant statuses + * Process participant statuses. * * @param array $params - * (reference ) input parameters. + * Input parameters. * * @return array * array of properties, if error an array with an error id and error message @@ -412,8 +409,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. @@ -421,7 +419,7 @@ function civicrm_api3_job_process_participant($params) { * @param array $params * Input parameters NOT USED. * - * @return boolean + * @return bool * true if success, else false */ function civicrm_api3_job_process_membership($params) { @@ -434,7 +432,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']); @@ -442,12 +440,12 @@ 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 + * @return bool * true if success, else false */ function civicrm_api3_job_process_respondent($params) { @@ -467,16 +465,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 - * */ function civicrm_api3_job_process_batch_merge($params) { $rgid = CRM_Utils_Array::value('rgid', $params); @@ -496,14 +486,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} - * */ function civicrm_api3_job_run_payment_cron($params) { @@ -531,21 +547,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 + * @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); @@ -570,36 +585,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();