api/v3/Activity.php

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