api/v3/Activity.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  * This api exposes CiviCRM Activity records.
  30  *
  31  * @package CiviCRM_APIv3
  32  */
  33
  34
  35 /**
  36  * Creates or updates an Activity.
  37  *
  38  * @param array $params
  39  *   Array per getfields documentation.
  40  *
  41  * @throws API_Exception
  42  * @return array
  43  *   Array containing 'is_error' to denote success or failure and details of the created activity.
  44  */
  45 function civicrm_api3_activity_create($params) {
  46
  47   if (empty($params['id'])) {
  48     // an update does not require any mandatory parameters
  49     civicrm_api3_verify_one_mandatory($params,
  50       NULL,
  51       array(
  52         'activity_name',
  53         'activity_type_id',
  54         'activity_label',
  55       )
  56     );
  57   }
  58
  59   // check for various error and required conditions
  60   // note that almost all the processing in there should be managed by the wrapper layer
  61   // & should be removed - needs testing
  62   $errors = _civicrm_api3_activity_check_params($params);
  63
  64   // this should not be required as should throw exception rather than return errors -
  65   //needs testing
  66   if (!empty($errors)) {
  67     return $errors;
  68   }
  69
  70   // processing for custom data
  71   $values = $activityArray = array();
  72   _civicrm_api3_custom_format_params($params, $values, 'Activity');
  73
  74   if (!empty($values['custom'])) {
  75     $params['custom'] = $values['custom'];
  76   }
  77
  78   // this should be set as a default rather than hard coded
  79   // needs testing
  80   $params['skipRecentView'] = TRUE;
  81
  82   // If this is a case activity, see if there is an existing activity
  83   // and set it as an old revision. Also retrieve details we'll need.
  84   // this handling should all be moved to the BAO layer
  85   $case_id = '';
  86   $createRevision = FALSE;
  87   $oldActivityValues = array();
  88   // Lookup case id if not supplied
  89   if (!isset($params['case_id']) && !empty($params['id'])) {
  90     $params['case_id'] = CRM_Core_DAO::singleValueQuery("SELECT case_id FROM civicrm_case_activity WHERE activity_id = " . (int) $params['id']);
  91   }
  92   if (!empty($params['case_id'])) {
  93     $case_id = $params['case_id'];
  94     if (!empty($params['id'])) {
  95       $oldActivityParams = array('id' => $params['id']);
  96       if (!$oldActivityValues) {
  97         CRM_Activity_BAO_Activity::retrieve($oldActivityParams, $oldActivityValues);
  98       }
  99       if (empty($oldActivityValues)) {
 100         throw new API_Exception(ts("Unable to locate existing activity."));
 101       }
 102       else {
 103         $activityDAO = new CRM_Activity_DAO_Activity();
 104         $activityDAO->id = $params['id'];
 105         $activityDAO->is_current_revision = 0;
 106         if (!$activityDAO->save()) {
 107           if (is_object($activityDAO)) {
 108             $activityDAO->free();
 109           }
 110           throw new API_Exception(ts("Unable to revision existing case activity."));
 111         }
 112         $createRevision = TRUE;
 113       }
 114     }
 115   }
 116
 117   $deleteActivityAssignment = FALSE;
 118   if (isset($params['assignee_contact_id'])) {
 119     $deleteActivityAssignment = TRUE;
 120   }
 121
 122   $deleteActivityTarget = FALSE;
 123   if (isset($params['target_contact_id'])) {
 124     $deleteActivityTarget = TRUE;
 125   }
 126
 127   // this should all be handled at the BAO layer
 128   $params['deleteActivityAssignment'] = CRM_Utils_Array::value('deleteActivityAssignment', $params, $deleteActivityAssignment);
 129   $params['deleteActivityTarget'] = CRM_Utils_Array::value('deleteActivityTarget', $params, $deleteActivityTarget);
 130
 131   if ($case_id && $createRevision) {
 132     // This is very similar to the copy-to-case action.
 133     if (!CRM_Utils_Array::crmIsEmptyArray($oldActivityValues['target_contact'])) {
 134       $oldActivityValues['targetContactIds'] = implode(',', array_unique($oldActivityValues['target_contact']));
 135     }
 136     if (!CRM_Utils_Array::crmIsEmptyArray($oldActivityValues['assignee_contact'])) {
 137       $oldActivityValues['assigneeContactIds'] = implode(',', array_unique($oldActivityValues['assignee_contact']));
 138     }
 139     $oldActivityValues['mode'] = 'copy';
 140     $oldActivityValues['caseID'] = $case_id;
 141     $oldActivityValues['activityID'] = $oldActivityValues['id'];
 142     $oldActivityValues['contactID'] = $oldActivityValues['source_contact_id'];
 143
 144     $copyToCase = CRM_Activity_Page_AJAX::_convertToCaseActivity($oldActivityValues);
 145     if (empty($copyToCase['error_msg'])) {
 146       // now fix some things that are different from copy-to-case
 147       // then fall through to the create below to update with the passed in params
 148       $params['id'] = $copyToCase['newId'];
 149       $params['is_auto'] = 0;
 150       $params['original_id'] = empty($oldActivityValues['original_id']) ? $oldActivityValues['id'] : $oldActivityValues['original_id'];
 151     }
 152     else {
 153       throw new API_Exception(ts("Unable to create new revision of case activity."));
 154     }
 155   }
 156
 157   // create activity
 158   $activityBAO = CRM_Activity_BAO_Activity::create($params);
 159
 160   if (isset($activityBAO->id)) {
 161     if ($case_id && !$createRevision) {
 162       // If this is a brand new case activity we need to add this
 163       $caseActivityParams = array('activity_id' => $activityBAO->id, 'case_id' => $case_id);
 164       CRM_Case_BAO_Case::processCaseActivity($caseActivityParams);
 165     }
 166
 167     _civicrm_api3_object_to_array($activityBAO, $activityArray[$activityBAO->id]);
 168     return civicrm_api3_create_success($activityArray, $params, 'Activity', 'get', $activityBAO);
 169   }
 170 }
 171
 172 /**
 173  * Specify Meta data for create.
 174  *
 175  * Note that this data is retrievable via the getfields function and is used for pre-filling defaults and
 176  * ensuring mandatory requirements are met.
 177  *
 178  * @param array $params
 179  *   Array of parameters determined by getfields.
 180  */
 181 function _civicrm_api3_activity_create_spec(&$params) {
 182
 183   // Default for source_contact_id = currently logged in user.
 184   $params['source_contact_id']['api.default'] = 'user_contact_id';
 185
 186   $params['status_id']['api.aliases'] = array('activity_status');
 187
 188   $params['assignee_contact_id'] = array(
 189     'name' => 'assignee_id',
 190     'title' => 'assigned to',
 191     'type' => 1,
 192     'FKClassName' => 'CRM_Activity_DAO_ActivityContact',
 193   );
 194   $params['target_contact_id'] = array(
 195     'name' => 'target_id',
 196     'title' => 'Activity Target',
 197     'type' => 1,
 198     'FKClassName' => 'CRM_Activity_DAO_ActivityContact',
 199   );
 200
 201   $params['source_contact_id'] = array(
 202     'name' => 'source_contact_id',
 203     'title' => 'Activity Source Contact',
 204     'type' => 1,
 205     'FKClassName' => 'CRM_Activity_DAO_ActivityContact',
 206     'api.default' => 'user_contact_id',
 207   );
 208
 209 }
 210
 211 /**
 212  * Gets a CiviCRM activity according to parameters.
 213  *
 214  * @param array $params
 215  *   Array per getfields documentation.
 216  *
 217  * @return array
 218  */
 219 function civicrm_api3_activity_get($params) {
 220   if (!empty($params['contact_id'])) {
 221     $activities = CRM_Activity_BAO_Activity::getContactActivity($params['contact_id']);
 222     // BAO function doesn't actually return a contact ID - hack api for now & add to test so when api re-write
 223     // happens it won't get missed.
 224     foreach ($activities as $key => $activityArray) {
 225       $activities[$key]['id'] = $key;
 226     }
 227   }
 228   else {
 229     $activities = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, FALSE);
 230   }
 231   $options = _civicrm_api3_get_options_from_params($params, FALSE, 'Activity', 'get');
 232   if ($options['is_count']) {
 233     return civicrm_api3_create_success($activities, $params, 'Activity', 'get');
 234   }
 235
 236   $activities = _civicrm_api3_activity_get_formatResult($params, $activities);
 237   //legacy custom data get - so previous formatted response is still returned too
 238   return civicrm_api3_create_success($activities, $params, 'Activity', 'get');
 239 }
 240
 241 /**
 242  * Given a list of activities, append any extra data requested about the activities.
 243  *
 244  * @note Called by civicrm-core and CiviHR
 245  *
 246  * @param array $params
 247  *   API request parameters.
 248  * @param array $activities
 249  *
 250  * @return array
 251  *   new activities list
 252  */
 253 function _civicrm_api3_activity_get_formatResult($params, $activities) {
 254   $returns = CRM_Utils_Array::value('return', $params, array());
 255   if (!is_array($returns)) {
 256     $returns = str_replace(' ', '', $returns);
 257     $returns = explode(',', $returns);
 258   }
 259   $returns = array_fill_keys($returns, 1);
 260
 261   foreach ($params as $n => $v) {
 262     if (substr($n, 0, 7) == 'return.') {
 263       $returnkey = substr($n, 7);
 264       $returns[$returnkey] = $v;
 265     }
 266   }
 267   $returns['source_contact_id'] = 1;
 268   foreach ($returns as $n => $v) {
 269     switch ($n) {
 270       case 'assignee_contact_id':
 271         foreach ($activities as $key => $activityArray) {
 272           $activities[$key]['assignee_contact_id'] = CRM_Activity_BAO_ActivityAssignment::retrieveAssigneeIdsByActivityId($activityArray['id']);
 273         }
 274         break;
 275
 276       case 'target_contact_id':
 277         foreach ($activities as $key => $activityArray) {
 278           $activities[$key]['target_contact_id'] = CRM_Activity_BAO_ActivityTarget::retrieveTargetIdsByActivityId($activityArray['id']);
 279         }
 280         break;
 281
 282       case 'source_contact_id':
 283         foreach ($activities as $key => $activityArray) {
 284           $activities[$key]['source_contact_id'] = CRM_Activity_BAO_Activity::getSourceContactID($activityArray['id']);
 285         }
 286         break;
 287
 288       default:
 289         if (substr($n, 0, 6) == 'custom') {
 290           $returnProperties[$n] = $v;
 291         }
 292     }
 293   }
 294   if (!empty($activities) && (!empty($returnProperties) || !empty($params['contact_id']))) {
 295     foreach ($activities as $activityId => $values) {
 296       //@todo - should possibly load activity type id if not loaded (update with id)
 297       _civicrm_api3_custom_data_get($activities[$activityId], 'Activity', $activityId, NULL, CRM_Utils_Array::value('activity_type_id', $values));
 298     }
 299   }
 300   return $activities;
 301 }
 302
 303
 304 /**
 305  * Delete a specified Activity.
 306  *
 307  * @param array $params
 308  *   Array holding 'id' of activity to be deleted.
 309  *
 310  * @throws API_Exception
 311  *
 312  * @return array
 313  */
 314 function civicrm_api3_activity_delete($params) {
 315
 316   if (CRM_Activity_BAO_Activity::deleteActivity($params)) {
 317     return civicrm_api3_create_success(1, $params, 'Activity', 'delete');
 318   }
 319   else {
 320     throw new API_Exception('Could not delete Activity');
 321   }
 322 }
 323
 324 /**
 325  * Check for required params.
 326  *
 327  * @param array $params
 328  *   Associated array of fields.
 329  *
 330  * @throws API_Exception
 331  * @throws Exception
 332  * @return array
 333  *   array with errors
 334  */
 335 function _civicrm_api3_activity_check_params(&$params) {
 336
 337   $contactIDFields = array_intersect_key($params,
 338     array(
 339       'source_contact_id' => 1,
 340       'assignee_contact_id' => 1,
 341       'target_contact_id' => 1,
 342     )
 343   );
 344
 345   // this should be handled by wrapper layer & probably the api would already manage it
 346   //correctly by doing post validation - ie. a failure should result in a roll-back = an error
 347   // needs testing
 348   if (!empty($contactIDFields)) {
 349     $contactIds = array();
 350     foreach ($contactIDFields as $fieldname => $contactfield) {
 351       if (empty($contactfield)) {
 352         continue;
 353       }
 354       if (is_array($contactfield)) {
 355         foreach ($contactfield as $contactkey => $contactvalue) {
 356           $contactIds[$contactvalue] = $contactvalue;
 357         }
 358       }
 359       else {
 360         $contactIds[$contactfield] = $contactfield;
 361       }
 362     }
 363
 364     $sql = '
 365 SELECT  count(*)
 366   FROM  civicrm_contact
 367  WHERE  id IN (' . implode(', ', $contactIds) . ' )';
 368     if (count($contactIds) != CRM_Core_DAO::singleValueQuery($sql)) {
 369       throw new API_Exception('Invalid Contact Id');
 370     }
 371   }
 372
 373   $activityIds = array(
 374     'activity' => CRM_Utils_Array::value('id', $params),
 375     'parent' => CRM_Utils_Array::value('parent_id', $params),
 376     'original' => CRM_Utils_Array::value('original_id', $params),
 377   );
 378
 379   foreach ($activityIds as $id => $value) {
 380     if ($value &&
 381       !CRM_Core_DAO::getFieldValue('CRM_Activity_DAO_Activity', $value, 'id')
 382     ) {
 383       throw new API_Exception('Invalid ' . ucfirst($id) . ' Id');
 384     }
 385   }
 386   // this should be handled by wrapper layer & probably the api would already manage it
 387   //correctly by doing pseudoconstant validation
 388   // needs testing
 389   $activityTypes = CRM_Activity_BAO_Activity::buildOptions('activity_type_id', 'validate');
 390   $activityName = CRM_Utils_Array::value('activity_name', $params);
 391   $activityName = ucfirst($activityName);
 392   $activityLabel = CRM_Utils_Array::value('activity_label', $params);
 393   if ($activityLabel) {
 394     $activityTypes = CRM_Activity_BAO_Activity::buildOptions('activity_type_id', 'create');
 395   }
 396
 397   $activityTypeId = CRM_Utils_Array::value('activity_type_id', $params);
 398
 399   if ($activityName || $activityLabel) {
 400     $activityTypeIdInList = array_search(($activityName ? $activityName : $activityLabel), $activityTypes);
 401
 402     if (!$activityTypeIdInList) {
 403       $errorString = $activityName ? "Invalid Activity Name : $activityName" : "Invalid Activity Type Label";
 404       throw new Exception($errorString);
 405     }
 406     elseif ($activityTypeId && ($activityTypeId != $activityTypeIdInList)) {
 407       throw new API_Exception('Mismatch in Activity');
 408     }
 409     $params['activity_type_id'] = $activityTypeIdInList;
 410   }
 411   elseif ($activityTypeId &&
 412     !array_key_exists($activityTypeId, $activityTypes)
 413   ) {
 414     throw new API_Exception('Invalid Activity Type ID');
 415   }
 416
 417   // check for activity duration minutes
 418   // this should be validated @ the wrapper layer not here
 419   // needs testing
 420   if (isset($params['duration_minutes']) && !is_numeric($params['duration_minutes'])) {
 421     throw new API_Exception('Invalid Activity Duration (in minutes)');
 422   }
 423
 424   //if adding a new activity & date_time not set make it now
 425   // this should be managed by the wrapper layer & setting ['api.default'] in speces
 426   // needs testing
 427   if (empty($params['id']) && empty($params['activity_date_time'])) {
 428     $params['activity_date_time'] = CRM_Utils_Date::processDate(date('Y-m-d H:i:s'));
 429   }
 430
 431   return NULL;
 432 }
 433
 434 /**
 435  * Get parameters for activity list.
 436  *
 437  * @see _civicrm_api3_generic_getlist_params
 438  *
 439  * @param array $request
 440  *   API request.
 441  */
 442 function _civicrm_api3_activity_getlist_params(&$request) {
 443   $fieldsToReturn = array(
 444     'activity_date_time',
 445     'activity_type_id',
 446     'subject',
 447     'source_contact_id',
 448   );
 449   $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
 450   $request['params']['options']['sort'] = 'activity_date_time DESC';
 451   $request['params'] += array(
 452     'is_current_revision' => 1,
 453     'is_deleted' => 0,
 454   );
 455 }
 456
 457 /**
 458  * Get output for activity list.
 459  *
 460  * @see _civicrm_api3_generic_getlist_output
 461  *
 462  * @param array $result
 463  * @param array $request
 464  *
 465  * @return array
 466  */
 467 function _civicrm_api3_activity_getlist_output($result, $request) {
 468   $output = array();
 469   if (!empty($result['values'])) {
 470     foreach ($result['values'] as $row) {
 471       $data = array(
 472         'id' => $row[$request['id_field']],
 473         'label' => $row[$request['label_field']] ? $row[$request['label_field']] : ts('(no subject)'),
 474         'description' => array(
 475           CRM_Core_Pseudoconstant::getLabel('CRM_Activity_BAO_Activity', 'activity_type_id', $row['activity_type_id']),
 476         ),
 477       );
 478       if (!empty($row['activity_date_time'])) {
 479         $data['description'][0] .= ': ' . CRM_Utils_Date::customFormat($row['activity_date_time']);
 480       }
 481       if (!empty($row['source_contact_id'])) {
 482         $data['description'][] = ts('By %1', array(
 483           1 => CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $row['source_contact_id'], 'display_name'),
 484         ));
 485       }
 486       foreach ($request['extra'] as $field) {
 487         $data['extra'][$field] = isset($row[$field]) ? $row[$field] : NULL;
 488       }
 489       $output[] = $data;
 490     }
 491   }
 492   return $output;
 493 }