X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FJob.php;h=c22003c6b4a819c7b8cf0878a540d15261f4af0a;hb=af3775b322b9e4f11d097067367f0ea7763f5f10;hp=65436f8d4850bb44e635ae0ff4538abe494a7684;hpb=cd5823ae452708e6d0a5fb899b2c3eb3f63be640;p=civicrm-core.git

diff --git a/api/v3/Job.php b/api/v3/Job.php
index 65436f8d48..c22003c6b4 100644
--- a/api/v3/Job.php
+++ b/api/v3/Job.php
@@ -1,6 +1,4 @@
 <?php
-// $Id$
-
 /*
  +--------------------------------------------------------------------+
  | CiviCRM version 4.6                                                |
@@ -28,22 +26,18 @@
  */
 
 /**
- * new version of civicrm APIs. See blog post at
- * http://civicrm.org/node/131
+ * This api is used for working with scheduled "cron" jobs.
  *
  * @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.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_job_create_spec(&$params) {
   $params['run_frequency']['api.required'] = 1;
@@ -56,46 +50,42 @@ 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.
  *
  * @return array
- *
- *   {@getfields Job_create}
  */
 function civicrm_api3_job_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 }
 
 /**
- * Retrieve one or more job
+ * Retrieve one or more job.
  *
  * @param array $params
  *   input parameters
- * @return array
  *
- *   {@getfields email_get}
+ * @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
- *
- * {@getfields Job_delete}
  */
 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.
+ *
+ * Always creates success - errors and results are handled in the job log.
  *
  * @param array $params
  *   input parameters (unused).
@@ -104,26 +94,25 @@ function civicrm_api3_job_delete($params) {
  *   API Result Array
  */
 function civicrm_api3_job_execute($params) {
-  // @noinspection PhpUnusedParameterInspection
 
   $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, '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
  *   input parameters.
@@ -145,7 +134,7 @@ function civicrm_api3_job_geocode($params) {
 }
 
 /**
- * First check on Code documentation
+ * First check on Code documentation.
  *
  * @param array $params
  */
@@ -158,7 +147,7 @@ function _civicrm_api3_job_geocode_spec(&$params) {
 }
 
 /**
- * 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.
@@ -189,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
@@ -204,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.
@@ -227,12 +217,12 @@ 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
  *
@@ -257,11 +247,12 @@ function civicrm_api3_job_update_greeting($params) {
 }
 
 /**
- * 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(
@@ -277,9 +268,10 @@ function _civicrm_api3_job_update_greeting_spec(&$params) {
 }
 
 /**
- * Mass update pledge statuses
+ * Mass update pledge statuses.
  *
  * @param array $params
+ *
  * @return array
  */
 function civicrm_api3_job_process_pledge($params) {
@@ -297,7 +289,7 @@ function civicrm_api3_job_process_pledge($params) {
 }
 
 /**
- * Process mail queue
+ * Process mail queue.
  *
  * @param array $params
  *
@@ -310,7 +302,7 @@ 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');
   }
 }
 
@@ -327,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
  *
@@ -351,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
  *
@@ -371,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();
@@ -380,10 +372,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
@@ -401,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.
@@ -423,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']);
@@ -458,7 +451,6 @@ function civicrm_api3_job_process_respondent($params) {
  *
  * @return array
  *   API Result Array
- *
  */
 function civicrm_api3_job_process_batch_merge($params) {
   $rgid = CRM_Utils_Array::value('rgid', $params);
@@ -478,6 +470,8 @@ function civicrm_api3_job_process_batch_merge($params) {
 }
 
 /**
+ * Metadata for batch merge function.
+ *
  * @param $params
  */
 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
@@ -502,14 +496,14 @@ function _civicrm_api3_job_process_batch_merge_spec(&$params) {
 }
 
 /**
- * Runs handlePaymentCron method in the specified payment processor
+ * 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) {
 
@@ -537,7 +531,9 @@ 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.
+ *
+ * We recommend that sites run this on an hourly basis.
  *
  * @param array $params
  *   Sends in various config parameters to decide what needs to be cleaned.
@@ -569,26 +565,30 @@ function civicrm_api3_job_cleanup($params) {
 
 /**
  * Set expired relationships to disabled.
- * @param $params
+ *
+ * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
 function civicrm_api3_job_disable_expired_relationships($params) {
-  /** @noinspection PhpUnusedParameterInspection */
   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
   if (!$result) {
     throw new API_Exception('Failed to disable all expired relationships.');
   }
-  return civicrm_api3_create_success();
+  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
  */