5 +--------------------------------------------------------------------+
6 | CiviCRM version 4.5 |
7 +--------------------------------------------------------------------+
8 | Copyright CiviCRM LLC (c) 2004-2014 |
9 +--------------------------------------------------------------------+
10 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
31 * File for the CiviCRM APIv3 activity functions
33 * @package CiviCRM_APIv3
34 * @subpackage API_Activity
35 * @copyright CiviCRM LLC (c) 2004-2014
36 * @version $Id: Activity.php 30486 2010-11-02 16:12:09Z shot $
42 * Creates or updates an Activity. See the example for usage
44 * @param array $params Associative array of property name/value
45 * pairs for the activity.
46 * {@getfields activity_create}
48 * @return array Array containing 'is_error' to denote success or failure and details of the created activity
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}
55 function civicrm_api3_activity_create($params) {
57 if (empty($params['id'])) {
58 // an update does not require any mandatory parameters
59 civicrm_api3_verify_one_mandatory($params,
62 'activity_name', 'activity_type_id', 'activity_label',
67 // check for various error and required conditions
68 // note that almost all the processing in there should be managed by the wrapper layer
69 // & should be removed - needs testing
70 $errors = _civicrm_api3_activity_check_params($params);
72 // this should not be required as should throw exception rather than return errors -
74 if (!empty($errors)) {
79 // processing for custom data
80 $values = $activityArray = array();
81 _civicrm_api3_custom_format_params($params, $values, 'Activity');
83 if (!empty($values['custom'])) {
84 $params['custom'] = $values['custom'];
87 // this should be set as a default rather than hard coded
89 $params['skipRecentView'] = TRUE;
91 // If this is a case activity, see if there is an existing activity
92 // and set it as an old revision. Also retrieve details we'll need.
93 // this handling should all be moved to the BAO layer
95 $createRevision = FALSE;
96 $oldActivityValues = array();
97 if (!empty($params['case_id'])) {
98 $case_id = $params['case_id'];
99 if (!empty($params['id'])) {
100 $oldActivityParams = array('id' => $params['id']);
101 if (!$oldActivityValues) {
102 CRM_Activity_BAO_Activity
::retrieve($oldActivityParams, $oldActivityValues);
104 if (empty($oldActivityValues)) {
105 throw new API_Exception(ts("Unable to locate existing activity."));
108 $activityDAO = new CRM_Activity_DAO_Activity();
109 $activityDAO->id
= $params['id'];
110 $activityDAO->is_current_revision
= 0;
111 if (!$activityDAO->save()) {
112 if (is_object($activityDAO)) {
113 $activityDAO->free();
115 throw new API_Exception(ts("Unable to revision existing case activity."));
117 $createRevision = TRUE;
122 $deleteActivityAssignment = FALSE;
123 if (isset($params['assignee_contact_id'])) {
124 $deleteActivityAssignment = TRUE;
127 $deleteActivityTarget = FALSE;
128 if (isset($params['target_contact_id'])) {
129 $deleteActivityTarget = TRUE;
132 // this should all be handled at the BAO layer
133 $params['deleteActivityAssignment'] = CRM_Utils_Array
::value('deleteActivityAssignment', $params, $deleteActivityAssignment);
134 $params['deleteActivityTarget'] = CRM_Utils_Array
::value('deleteActivityTarget', $params, $deleteActivityTarget);
136 if ($case_id && $createRevision) {
137 // This is very similar to the copy-to-case action.
138 if (!CRM_Utils_Array
::crmIsEmptyArray($oldActivityValues['target_contact'])) {
139 $oldActivityValues['targetContactIds'] = implode(',', array_unique($oldActivityValues['target_contact']));
141 if (!CRM_Utils_Array
::crmIsEmptyArray($oldActivityValues['assignee_contact'])) {
142 $oldActivityValues['assigneeContactIds'] = implode(',', array_unique($oldActivityValues['assignee_contact']));
144 $oldActivityValues['mode'] = 'copy';
145 $oldActivityValues['caseID'] = $case_id;
146 $oldActivityValues['activityID'] = $oldActivityValues['id'];
147 $oldActivityValues['contactID'] = $oldActivityValues['source_contact_id'];
149 $copyToCase = CRM_Activity_Page_AJAX
::_convertToCaseActivity($oldActivityValues);
150 if (empty($copyToCase['error_msg'])) {
151 // now fix some things that are different from copy-to-case
152 // then fall through to the create below to update with the passed in params
153 $params['id'] = $copyToCase['newId'];
154 $params['is_auto'] = 0;
155 $params['original_id'] = empty($oldActivityValues['original_id']) ?
$oldActivityValues['id'] : $oldActivityValues['original_id'];
158 throw new API_Exception(ts("Unable to create new revision of case activity."));
163 $activityBAO = CRM_Activity_BAO_Activity
::create($params);
165 if (isset($activityBAO->id
)) {
166 if ($case_id && !$createRevision) {
167 // If this is a brand new case activity we need to add this
168 $caseActivityParams = array('activity_id' => $activityBAO->id
, 'case_id' => $case_id);
169 CRM_Case_BAO_Case
::processCaseActivity($caseActivityParams);
172 _civicrm_api3_object_to_array($activityBAO, $activityArray[$activityBAO->id
]);
173 return civicrm_api3_create_success($activityArray, $params, 'activity', 'get', $activityBAO);
178 * Specify Meta data for create. Note that this data is retrievable via the getfields function
179 * and is used for pre-filling defaults and ensuring mandatory requirements are met.
180 * @param array $params (reference) array of parameters determined by getfields
182 function _civicrm_api3_activity_create_spec(&$params) {
184 //default for source_contact_id = currently logged in user
185 $params['source_contact_id']['api.default'] = 'user_contact_id';
187 $params['status_id']['api.aliases'] = array('activity_status');
189 $params['assignee_contact_id'] = array(
190 'name' => 'assignee_id',
191 'title' => 'assigned to',
193 'FKClassName' => 'CRM_Activity_DAO_ActivityContact',
195 $params['target_contact_id'] = array(
196 'name' => 'target_id',
197 'title' => 'Activity Target',
199 'FKClassName' => 'CRM_Activity_DAO_ActivityContact',
202 $params['source_contact_id'] = array(
203 'name' => 'source_contact_id',
204 'title' => 'Activity Source Contact',
206 'FKClassName' => 'CRM_Activity_DAO_ActivityContact',
207 'api.default' => 'user_contact_id',
213 * Gets a CiviCRM activity according to parameters
215 * @param array $params Associative array of property name/value
216 * pairs for the activity.
220 * {@getfields activity_get}
221 * @example ActivityGet.php Basic example
222 * @example Activity/DateTimeHigh.php Example get with date filtering
223 * {@example ActivityGet.php 0}
225 function civicrm_api3_activity_get($params) {
226 if (!empty($params['contact_id'])) {
227 $activities = CRM_Activity_BAO_Activity
::getContactActivity($params['contact_id']);
228 //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
229 foreach ($activities as $key => $activityArray) {
230 $activities[$key]['id'] = $key;
234 $activities = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params, FALSE);
236 $options = _civicrm_api3_get_options_from_params($params, FALSE,'activity','get');
237 if($options['is_count']) {
238 return civicrm_api3_create_success($activities, $params, 'activity', 'get');
241 $activities = _civicrm_api3_activity_get_formatResult($params, $activities);
242 //legacy custom data get - so previous formatted response is still returned too
243 return civicrm_api3_create_success($activities, $params, 'activity', 'get');
247 * Given a list of activities, append any extra data requested about the activities
249 * NOTE: Called by civicrm-core and CiviHR
251 * @param array $params API request parameters
252 * @param array $activities
253 * @return array new activities list
255 function _civicrm_api3_activity_get_formatResult($params, $activities) {
256 $returns = CRM_Utils_Array
::value('return', $params, array());
257 if (!is_array($returns)) {
258 $returns = str_replace(' ', '', $returns);
259 $returns = explode(',', $returns);
261 $returns = array_fill_keys($returns, 1);
263 foreach ($params as $n => $v) {
264 if (substr($n, 0, 7) == 'return.') {
265 $returnkey = substr($n, 7);
266 $returns[$returnkey] = $v;
269 $returns['source_contact_id'] = 1;
270 foreach ($returns as $n => $v) {
272 case 'assignee_contact_id':
273 foreach ($activities as $key => $activityArray) {
274 $activities[$key]['assignee_contact_id'] = CRM_Activity_BAO_ActivityAssignment
::retrieveAssigneeIdsByActivityId($activityArray['id']);
277 case 'target_contact_id':
278 foreach ($activities as $key => $activityArray) {
279 $activities[$key]['target_contact_id'] = CRM_Activity_BAO_ActivityTarget
::retrieveTargetIdsByActivityId($activityArray['id']);
282 case 'source_contact_id':
283 foreach ($activities as $key => $activityArray) {
284 $activities[$key]['source_contact_id'] = CRM_Activity_BAO_Activity
::getSourceContactID($activityArray['id']);
288 if (substr($n, 0, 6) == 'custom') {
289 $returnProperties[$n] = $v;
293 if (!empty($activities) && (!empty($returnProperties) ||
!empty($params['contact_id']))) {
294 foreach ($activities as $activityId => $values) {
295 //@todo - should possibly load activity type id if not loaded (update with id)
296 _civicrm_api3_custom_data_get($activities[$activityId], 'Activity', $activityId, NULL, CRM_Utils_Array
::value('activity_type_id', $values));
304 * Delete a specified Activity.
306 * @param array $params array holding 'id' of activity to be deleted
307 * {@getfields activity_delete}
309 * @throws API_Exception
310 * @return void|CRM_Core_Error An error if 'activityName or ID' is invalid,
311 * permissions are insufficient, etc. or CiviCRM success array
315 * @example ActivityDelete.php Standard Delete Example
318 function civicrm_api3_activity_delete($params) {
320 if (CRM_Activity_BAO_Activity
::deleteActivity($params)) {
321 return civicrm_api3_create_success(1, $params, 'activity', 'delete');
324 throw new API_Exception('Could not delete activity');
329 * Function to check for required params
331 * @param array $params associated array of fields
333 * @throws API_Exception
335 * @internal param bool $addMode true for add mode
337 * @return array $error array with errors
339 function _civicrm_api3_activity_check_params(&$params) {
341 $contactIDFields = array_intersect_key($params,
343 'source_contact_id' => 1,
344 'assignee_contact_id' => 1,
345 'target_contact_id' => 1,
349 // this should be handled by wrapper layer & probably the api would already manage it
350 //correctly by doing post validation - ie. a failure should result in a roll-back = an error
352 if (!empty($contactIDFields)) {
353 $contactIds = array();
354 foreach ($contactIDFields as $fieldname => $contactfield) {
355 if (empty($contactfield)) {
358 if (is_array($contactfield)) {
359 foreach ($contactfield as $contactkey => $contactvalue) {
360 $contactIds[$contactvalue] = $contactvalue;
364 $contactIds[$contactfield] = $contactfield;
372 WHERE id IN (' . implode(', ', $contactIds) . ' )';
373 if (count($contactIds) != CRM_Core_DAO
::singleValueQuery($sql)) {
374 throw new API_Exception('Invalid ' . ' Contact Id');
379 $activityIds = array('activity' => CRM_Utils_Array
::value('id', $params),
380 'parent' => CRM_Utils_Array
::value('parent_id', $params),
381 'original' => CRM_Utils_Array
::value('original_id', $params),
384 foreach ($activityIds as $id => $value) {
386 !CRM_Core_DAO
::getFieldValue('CRM_Activity_DAO_Activity', $value, 'id')
388 throw new API_Exception('Invalid ' . ucfirst($id) . ' Id');
391 // this should be handled by wrapper layer & probably the api would already manage it
392 //correctly by doing pseudoconstant validation
394 $activityTypes = CRM_Activity_BAO_Activity
::buildOptions('activity_type_id', 'validate');
395 $activityName = CRM_Utils_Array
::value('activity_name', $params);
396 $activityName = ucfirst($activityName);
397 $activityLabel = CRM_Utils_Array
::value('activity_label', $params);
398 if ($activityLabel) {
399 $activityTypes = CRM_Activity_BAO_Activity
::buildOptions('activity_type_id', 'create');
402 $activityTypeId = CRM_Utils_Array
::value('activity_type_id', $params);
404 if ($activityName ||
$activityLabel) {
405 $activityTypeIdInList = array_search(($activityName ?
$activityName : $activityLabel), $activityTypes);
407 if (!$activityTypeIdInList) {
408 $errorString = $activityName ?
"Invalid Activity Name : $activityName" : "Invalid Activity Type Label";
409 throw new Exception($errorString);
411 elseif ($activityTypeId && ($activityTypeId != $activityTypeIdInList)) {
412 throw new API_Exception('Mismatch in Activity');
414 $params['activity_type_id'] = $activityTypeIdInList;
416 elseif ($activityTypeId &&
417 !array_key_exists($activityTypeId, $activityTypes)
419 throw new API_Exception('Invalid Activity Type ID');
422 // check for activity duration minutes
423 // this should be validated @ the wrapper layer not here
425 if (isset($params['duration_minutes']) && !is_numeric($params['duration_minutes'])) {
426 throw new API_Exception('Invalid Activity Duration (in minutes)');
430 //if adding a new activity & date_time not set make it now
431 // this should be managed by the wrapper layer & setting ['api.default'] in speces
433 if (empty($params['id']) && empty($params['activity_date_time'])) {
434 $params['activity_date_time'] = CRM_Utils_Date
::processDate(date('Y-m-d H:i:s'));