3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2017 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
29 * This api exposes CiviCRM Activity records.
31 * @package CiviCRM_APIv3
36 * Creates or updates an Activity.
38 * @param array $params
39 * Array per getfields documentation.
41 * @throws API_Exception
45 function civicrm_api3_activity_create($params) {
47 if (empty($params['id'])) {
48 // an update does not require any mandatory parameters
49 civicrm_api3_verify_one_mandatory($params,
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);
64 // this should not be required as should throw exception rather than return errors -
66 if (!empty($errors)) {
70 // processing for custom data
71 $values = $activityArray = array();
72 _civicrm_api3_custom_format_params($params, $values, 'Activity');
74 if (!empty($values['custom'])) {
75 $params['custom'] = $values['custom'];
78 // this should be set as a default rather than hard coded
80 $params['skipRecentView'] = TRUE;
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
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']);
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);
99 if (empty($oldActivityValues)) {
100 throw new API_Exception(ts("Unable to locate existing activity."));
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();
110 throw new API_Exception(ts("Unable to revision existing case activity."));
112 $createRevision = TRUE;
117 $deleteActivityAssignment = FALSE;
118 if (isset($params['assignee_contact_id'])) {
119 $deleteActivityAssignment = TRUE;
122 $deleteActivityTarget = FALSE;
123 if (isset($params['target_contact_id'])) {
124 $deleteActivityTarget = TRUE;
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);
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']));
136 if (!CRM_Utils_Array
::crmIsEmptyArray($oldActivityValues['assignee_contact'])) {
137 $oldActivityValues['assigneeContactIds'] = implode(',', array_unique($oldActivityValues['assignee_contact']));
139 $oldActivityValues['mode'] = 'copy';
140 $oldActivityValues['caseID'] = $case_id;
141 $oldActivityValues['activityID'] = $oldActivityValues['id'];
142 $oldActivityValues['contactID'] = $oldActivityValues['source_contact_id'];
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'];
153 throw new API_Exception(ts("Unable to create new revision of case activity."));
158 $activityBAO = CRM_Activity_BAO_Activity
::create($params);
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);
167 _civicrm_api3_object_to_array($activityBAO, $activityArray[$activityBAO->id
]);
168 return civicrm_api3_create_success($activityArray, $params, 'Activity', 'get', $activityBAO);
173 * Specify Meta data for create.
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.
178 * @param array $params
179 * Array of parameters determined by getfields.
181 function _civicrm_api3_activity_create_spec(&$params) {
183 // Default for source_contact_id = currently logged in user.
184 $params['source_contact_id']['api.default'] = 'user_contact_id';
186 $params['status_id']['api.aliases'] = array('activity_status');
188 $params['assignee_contact_id'] = array(
189 'name' => 'assignee_id',
190 'title' => 'Activity Assignee',
191 'description' => 'Contact(s) assigned to this activity.',
193 'FKClassName' => 'CRM_Contact_DAO_Contact',
194 'FKApiName' => 'Contact',
196 $params['target_contact_id'] = array(
197 'name' => 'target_id',
198 'title' => 'Activity Target',
199 'description' => 'Contact(s) participating in this activity.',
201 'FKClassName' => 'CRM_Contact_DAO_Contact',
202 'FKApiName' => 'Contact',
205 $params['source_contact_id'] = array(
206 'name' => 'source_contact_id',
207 'title' => 'Activity Source Contact',
208 'description' => 'Person who created this activity. Defaults to current user.',
210 'FKClassName' => 'CRM_Contact_DAO_Contact',
211 'api.default' => 'user_contact_id',
212 'FKApiName' => 'Contact',
215 $params['case_id'] = array(
217 'title' => 'Case ID',
218 'description' => 'For creating an activity as part of a case.',
220 'FKClassName' => 'CRM_Case_DAO_Case',
221 'FKApiName' => 'Case',
227 * Specify Metadata for get.
229 * @param array $params
231 function _civicrm_api3_activity_get_spec(&$params) {
232 $params['tag_id'] = array(
234 'description' => 'Find activities with specified tags.',
236 'FKClassName' => 'CRM_Core_DAO_Tag',
237 'FKApiName' => 'Tag',
238 'supports_joins' => TRUE,
240 $params['file_id'] = array(
241 'title' => 'Attached Files',
242 'description' => 'Find activities with attached files.',
244 'FKClassName' => 'CRM_Core_DAO_File',
245 'FKApiName' => 'File',
247 $params['case_id'] = array(
249 'description' => 'Find activities within specified cases.',
251 'FKClassName' => 'CRM_Case_DAO_Case',
252 'FKApiName' => 'Case',
254 $params['contact_id'] = array(
255 'title' => 'Activity Contact ID',
256 'description' => 'Find activities involving this contact (as target, source, OR assignee).',
258 'FKClassName' => 'CRM_Contact_DAO_Contact',
259 'FKApiName' => 'Contact',
261 $params['target_contact_id'] = array(
262 'title' => 'Target Contact ID',
263 'description' => 'Find activities with specified target contact.',
265 'FKClassName' => 'CRM_Contact_DAO_Contact',
266 'FKApiName' => 'Contact',
268 $params['source_contact_id'] = array(
269 'title' => 'Source Contact ID',
270 'description' => 'Find activities with specified source contact.',
272 'FKClassName' => 'CRM_Contact_DAO_Contact',
273 'FKApiName' => 'Contact',
275 $params['assignee_contact_id'] = array(
276 'title' => 'Assignee Contact ID',
277 'description' => 'Find activities with specified assignee contact.',
279 'FKClassName' => 'CRM_Contact_DAO_Contact',
280 'FKApiName' => 'Contact',
285 * Gets a CiviCRM activity according to parameters.
287 * @param array $params
288 * Array per getfields documentation.
290 * @return array API result array
293 * @throws \API_Exception
294 * @throws \CiviCRM_API3_Exception
295 * @throws \Civi\API\Exception\UnauthorizedException
297 function civicrm_api3_activity_get($params) {
298 if (!empty($params['check_permissions']) && !CRM_Core_Permission
::check('view all activities')) {
299 // In absence of view all activities permission it's possible to see a specific activity by ACL.
300 // Note still allowing view all activities to override ACLs is based on the 'don't change too much
301 // if you are not sure principle' and it could be argued that the ACLs should always be applied.
302 if (empty($params['id']) ||
!empty($params['contact_id'])) {
303 // We fall back to the original blunt permissions if we don't have an id to check or we are about
304 // to go to the weird place that the legacy 'contact_id' parameter takes us to.
305 throw new \Civi\API\Exception\
UnauthorizedException(
306 "Cannot access activities. Required permission: 'view all activities''"
310 if (!CRM_Activity_BAO_Activity
::checkPermission($params['id'], CRM_Core_Action
::VIEW
)) {
311 throw new \Civi\API\Exception\
UnauthorizedException(
312 'You do not have permission to view this activity'
317 $sql = CRM_Utils_SQL_Select
::fragment();
318 // Support search by activity_contact
319 $extraFieldSpecs = array();
320 _civicrm_api3_activity_create_spec($extraFieldSpecs);
321 $recordTypes = civicrm_api3('ActivityContact', 'getoptions', array('field' => 'record_type_id'));
322 $recordTypes = $recordTypes['values'];
323 $activityContactOptions = array(
324 'contact_id' => NULL,
325 'target_contact_id' => array_search('Activity Targets', $recordTypes),
326 'source_contact_id' => array_search('Activity Source', $recordTypes),
327 'assignee_contact_id' => array_search('Activity Assignees', $recordTypes),
329 foreach ($activityContactOptions as $activityContactName => $activityContactValue) {
330 if (!empty($params[$activityContactName])) {
331 _civicrm_api3_validate_integer($params, $activityContactName, $extraFieldSpecs[$activityContactName], 'Activity');
332 if (!is_array($params[$activityContactName])) {
333 $params[$activityContactName] = array('=' => $params[$activityContactName]);
335 $clause = \CRM_Core_DAO
::createSQLFilter('contact_id', $params[$activityContactName]);
336 $typeClause = $activityContactValue ?
'record_type_id = #typeId AND ' : '';
337 $sql->where("a.id IN (SELECT activity_id FROM civicrm_activity_contact WHERE $typeClause !clause)",
338 array('#typeId' => $activityContactValue, '!clause' => $clause)
342 if (!empty($params['tag_id'])) {
343 _civicrm_api3_validate_integer($params, 'tag_id', $extraFieldSpecs['tag_id'], 'Activity');
344 if (!is_array($params['tag_id'])) {
345 $params['tag_id'] = array('=' => $params['tag_id']);
347 $clause = \CRM_Core_DAO
::createSQLFilter('tag_id', $params['tag_id']);
349 $sql->where('a.id IN (SELECT entity_id FROM civicrm_entity_tag WHERE entity_table = "civicrm_activity" AND !clause)', array('!clause' => $clause));
352 if (!empty($params['file_id'])) {
353 _civicrm_api3_validate_integer($params, 'file_id', $extraFieldSpecs['file_id'], 'Activity');
354 if (!is_array($params['file_id'])) {
355 $params['file_id'] = array('=' => $params['file_id']);
357 $clause = \CRM_Core_DAO
::createSQLFilter('file_id', $params['file_id']);
359 $sql->where('a.id IN (SELECT entity_id FROM civicrm_entity_file WHERE entity_table = "civicrm_activity" AND !clause)', array('!clause' => $clause));
362 if (!empty($params['case_id'])) {
363 _civicrm_api3_validate_integer($params, 'case_id', $extraFieldSpecs['case_id'], 'Activity');
364 if (!is_array($params['case_id'])) {
365 $params['case_id'] = array('=' => $params['case_id']);
367 $clause = \CRM_Core_DAO
::createSQLFilter('case_id', $params['case_id']);
369 $sql->where('a.id IN (SELECT activity_id FROM civicrm_case_activity WHERE !clause)', array('!clause' => $clause));
372 $activities = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params, FALSE, 'Activity', $sql);
373 $options = _civicrm_api3_get_options_from_params($params, FALSE, 'Activity', 'get');
374 if ($options['is_count']) {
375 return civicrm_api3_create_success($activities, $params, 'Activity', 'get');
378 $activities = _civicrm_api3_activity_get_formatResult($params, $activities, $options);
379 //legacy custom data get - so previous formatted response is still returned too
380 return civicrm_api3_create_success($activities, $params, 'Activity', 'get');
384 * Given a list of activities, append any extra data requested about the activities.
386 * @note Called by civicrm-core and CiviHR
388 * @param array $params
389 * API request parameters.
390 * @param array $activities
393 * new activities list
395 function _civicrm_api3_activity_get_formatResult($params, $activities, $options) {
400 $returns = $options['return'];
401 foreach ($params as $n => $v) {
402 if (substr($n, 0, 7) == 'return.') {
403 $returnkey = substr($n, 7);
404 $returns[$returnkey] = $v;
408 $returns['source_contact_id'] = 1;
409 if (!empty($returns['target_contact_name'])) {
410 $returns['target_contact_id'] = 1;
412 if (!empty($returns['assignee_contact_name'])) {
413 $returns['assignee_contact_id'] = 1;
416 $tagGet = array('tag_id', 'entity_id');
417 foreach (array_keys($returns) as $key) {
418 if (strpos($key, 'tag_id.') === 0) {
420 $returns['tag_id'] = 1;
424 foreach ($returns as $n => $v) {
426 case 'assignee_contact_id':
427 foreach ($activities as $key => $activityArray) {
428 $cids = $activities[$key]['assignee_contact_id'] = CRM_Activity_BAO_ActivityAssignment
::retrieveAssigneeIdsByActivityId($activityArray['id']);
429 if ($cids && !empty($returns['assignee_contact_name'])) {
430 foreach ($cids as $cid) {
431 $activities[$key]['assignee_contact_name'][$cid] = CRM_Core_DAO
::getFieldValue('CRM_Contact_DAO_Contact', $cid, 'display_name');
437 case 'target_contact_id':
438 foreach ($activities as $key => $activityArray) {
439 $cids = $activities[$key]['target_contact_id'] = CRM_Activity_BAO_ActivityTarget
::retrieveTargetIdsByActivityId($activityArray['id']);
440 if ($cids && !empty($returns['target_contact_name'])) {
441 foreach ($cids as $cid) {
442 $activities[$key]['target_contact_name'][$cid] = CRM_Core_DAO
::getFieldValue('CRM_Contact_DAO_Contact', $cid, 'display_name');
448 case 'source_contact_id':
449 foreach ($activities as $key => $activityArray) {
450 $cid = $activities[$key]['source_contact_id'] = CRM_Activity_BAO_Activity
::getSourceContactID($activityArray['id']);
451 if ($cid && !empty($returns['source_contact_name'])) {
452 $activities[$key]['source_contact_name'] = CRM_Core_DAO
::getFieldValue('CRM_Contact_DAO_Contact', $cid, 'display_name');
458 $tags = civicrm_api3('EntityTag', 'get', array(
459 'entity_table' => 'civicrm_activity',
460 'entity_id' => array('IN' => array_keys($activities)),
462 'options' => array('limit' => 0),
464 foreach ($tags['values'] as $tag) {
465 $key = (int) $tag['entity_id'];
466 unset($tag['entity_id'], $tag['id']);
467 $activities[$key]['tag_id'][$tag['tag_id']] = $tag;
472 $dao = CRM_Core_DAO
::executeQuery("SELECT entity_id, file_id FROM civicrm_entity_file WHERE entity_table = 'civicrm_activity' AND entity_id IN (%1)",
473 array(1 => array(implode(',', array_keys($activities)), 'String', CRM_Core_DAO
::QUERY_FORMAT_NO_QUOTES
)));
474 while ($dao->fetch()) {
475 $activities[$dao->entity_id
]['file_id'][] = $dao->file_id
;
480 $dao = CRM_Core_DAO
::executeQuery("SELECT activity_id, case_id FROM civicrm_case_activity WHERE activity_id IN (%1)",
481 array(1 => array(implode(',', array_keys($activities)), 'String', CRM_Core_DAO
::QUERY_FORMAT_NO_QUOTES
)));
482 while ($dao->fetch()) {
483 $activities[$dao->activity_id
]['case_id'] = $dao->case_id
;
488 if (substr($n, 0, 6) == 'custom') {
489 $returnProperties[$n] = $v;
495 if (!empty($params['contact_id'])) {
496 $statusOptions = CRM_Activity_BAO_Activity
::buildOptions('status_id', 'get');
497 $typeOptions = CRM_Activity_BAO_Activity
::buildOptions('activity_type_id', 'validate');
498 foreach ($activities as $key => &$activityArray) {
499 if (!empty($activityArray['status_id'])) {
500 $activityArray['status'] = $statusOptions[$activityArray['status_id']];
502 if (!empty($activityArray['activity_type_id'])) {
503 $activityArray['activity_name'] = $typeOptions[$activityArray['activity_type_id']];
508 if (!empty($returnProperties) ||
!empty($params['contact_id'])) {
509 foreach ($activities as $activityId => $values) {
510 //@todo - should possibly load activity type id if not loaded (update with id)
511 _civicrm_api3_custom_data_get($activities[$activityId], CRM_Utils_Array
::value('check_permissions', $params), 'Activity', $activityId, NULL, CRM_Utils_Array
::value('activity_type_id', $values));
519 * Delete a specified Activity.
521 * @param array $params
522 * Array holding 'id' of activity to be deleted.
524 * @throws API_Exception
529 function civicrm_api3_activity_delete($params) {
531 if (CRM_Activity_BAO_Activity
::deleteActivity($params)) {
532 return civicrm_api3_create_success(1, $params, 'Activity', 'delete');
535 throw new API_Exception('Could not delete Activity');
540 * Check for required params.
542 * @param array $params
543 * Associated array of fields.
545 * @throws API_Exception
550 function _civicrm_api3_activity_check_params(&$params) {
552 $contactIDFields = array_intersect_key($params,
554 'source_contact_id' => 1,
555 'assignee_contact_id' => 1,
556 'target_contact_id' => 1,
560 // this should be handled by wrapper layer & probably the api would already manage it
561 //correctly by doing post validation - ie. a failure should result in a roll-back = an error
563 if (!empty($contactIDFields)) {
564 $contactIds = array();
565 foreach ($contactIDFields as $fieldname => $contactfield) {
566 if (empty($contactfield)) {
569 if (is_array($contactfield)) {
570 foreach ($contactfield as $contactkey => $contactvalue) {
571 $contactIds[$contactvalue] = $contactvalue;
575 $contactIds[$contactfield] = $contactfield;
582 WHERE id IN (' . implode(', ', $contactIds) . ' )';
583 if (count($contactIds) != CRM_Core_DAO
::singleValueQuery($sql)) {
584 throw new API_Exception('Invalid Contact Id');
588 $activityIds = array(
589 'activity' => CRM_Utils_Array
::value('id', $params),
590 'parent' => CRM_Utils_Array
::value('parent_id', $params),
591 'original' => CRM_Utils_Array
::value('original_id', $params),
594 foreach ($activityIds as $id => $value) {
596 !CRM_Core_DAO
::getFieldValue('CRM_Activity_DAO_Activity', $value, 'id')
598 throw new API_Exception('Invalid ' . ucfirst($id) . ' Id');
601 // this should be handled by wrapper layer & probably the api would already manage it
602 //correctly by doing pseudoconstant validation
604 $activityTypes = CRM_Activity_BAO_Activity
::buildOptions('activity_type_id', 'validate');
605 $activityName = CRM_Utils_Array
::value('activity_name', $params);
606 $activityName = ucfirst($activityName);
607 $activityLabel = CRM_Utils_Array
::value('activity_label', $params);
608 if ($activityLabel) {
609 $activityTypes = CRM_Activity_BAO_Activity
::buildOptions('activity_type_id', 'create');
612 $activityTypeId = CRM_Utils_Array
::value('activity_type_id', $params);
614 if ($activityName ||
$activityLabel) {
615 $activityTypeIdInList = array_search(($activityName ?
$activityName : $activityLabel), $activityTypes);
617 if (!$activityTypeIdInList) {
618 $errorString = $activityName ?
"Invalid Activity Name : $activityName" : "Invalid Activity Type Label";
619 throw new Exception($errorString);
621 elseif ($activityTypeId && ($activityTypeId != $activityTypeIdInList)) {
622 throw new API_Exception('Mismatch in Activity');
624 $params['activity_type_id'] = $activityTypeIdInList;
626 elseif ($activityTypeId &&
627 !array_key_exists($activityTypeId, $activityTypes)
629 throw new API_Exception('Invalid Activity Type ID');
632 // check for activity duration minutes
633 // this should be validated @ the wrapper layer not here
635 if (isset($params['duration_minutes']) && !is_numeric($params['duration_minutes'])) {
636 throw new API_Exception('Invalid Activity Duration (in minutes)');
639 //if adding a new activity & date_time not set make it now
640 // this should be managed by the wrapper layer & setting ['api.default'] in speces
642 if (empty($params['id']) && empty($params['activity_date_time'])) {
643 $params['activity_date_time'] = CRM_Utils_Date
::processDate(date('Y-m-d H:i:s'));
650 * Get parameters for activity list.
652 * @see _civicrm_api3_generic_getlist_params
654 * @param array $request
657 function _civicrm_api3_activity_getlist_params(&$request) {
658 $fieldsToReturn = array(
659 'activity_date_time',
664 $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
665 $request['params']['options']['sort'] = 'activity_date_time DESC';
666 $request['params'] +
= array(
667 'is_current_revision' => 1,
673 * Get output for activity list.
675 * @see _civicrm_api3_generic_getlist_output
677 * @param array $result
678 * @param array $request
682 function _civicrm_api3_activity_getlist_output($result, $request) {
684 if (!empty($result['values'])) {
685 foreach ($result['values'] as $row) {
687 'id' => $row[$request['id_field']],
688 'label' => $row[$request['label_field']] ?
$row[$request['label_field']] : ts('(no subject)'),
689 'description' => array(
690 CRM_Core_Pseudoconstant
::getLabel('CRM_Activity_BAO_Activity', 'activity_type_id', $row['activity_type_id']),
693 if (!empty($row['activity_date_time'])) {
694 $data['description'][0] .= ': ' . CRM_Utils_Date
::customFormat($row['activity_date_time']);
696 if (!empty($row['source_contact_id'])) {
697 $data['description'][] = ts('By %1', array(
698 1 => CRM_Core_DAO
::getFieldValue('CRM_Contact_DAO_Contact', $row['source_contact_id'], 'display_name'),
701 // Add repeating info
702 $repeat = CRM_Core_BAO_RecurringEntity
::getPositionAndCount($row['id'], 'civicrm_activity');
703 $data['extra']['is_recur'] = FALSE;
705 $data['suffix'] = ts('(%1 of %2)', array(1 => $repeat[0], 2 => $repeat[1]));
706 $data['extra']['is_recur'] = TRUE;