* @param array $params
*
* @code
- * //REQUIRED:
+ * //REQUIRED for create:
* 'case_type_id' => int OR
* 'case_type' => str (provide one or the other)
* 'contact_id' => int // case client
* 'subject' => str
+ * //REQUIRED for update:
+ * 'id' => case Id
*
* //OPTIONAL
* 'medium_id' => int // see civicrm option values for possibilities
* api result array
*/
function civicrm_api3_case_create($params) {
+ _civicrm_api3_case_format_params($params);
- if (!empty($params['id'])) {
- return civicrm_api3_case_update($params);
+ if (empty($params['id'])) {
+ // Creating a new case, so make sure we have the necessary parameters
+ civicrm_api3_verify_mandatory($params, NULL, array(
+ 'contact_id',
+ 'subject',
+ array('case_type', 'case_type_id'),
+ )
+ );
}
+ else {
+ // Update an existing case
+ // FIXME: Some of this logic should move to the BAO object?
+ // FIXME: Should we check if case with ID actually exists?
+ if (!isset($params['case_id']) && isset($params['id'])) {
+ $params['case_id'] = $params['id'];
+ }
- civicrm_api3_verify_mandatory($params, NULL, array(
- 'contact_id',
- 'subject',
- array('case_type', 'case_type_id'))
- );
- _civicrm_api3_case_format_params($params);
+ if (array_key_exists('creator_id', $params)) {
+ throw new API_Exception('You cannot update creator id');
+ }
- // If format_params didn't find what it was looking for, return error
- if (empty($params['case_type_id'])) {
- throw new API_Exception('Invalid case_type. No such case type exists.');
- }
- if (empty($params['case_type'])) {
- throw new API_Exception('Invalid case_type_id. No such case type exists.');
- }
+ $mergedCaseId = $origContactIds = array();
- // Fixme: can we safely pass raw params to the BAO?
- $newParams = array(
- 'case_type_id' => $params['case_type_id'],
- 'creator_id' => $params['creator_id'],
- 'status_id' => $params['status_id'],
- 'start_date' => $params['start_date'],
- 'end_date' => CRM_Utils_Array::value('end_date', $params),
- 'subject' => $params['subject'],
- );
+ // get original contact id and creator id of case
+ if (!empty($params['contact_id'])) {
+ $origContactIds = CRM_Case_BAO_Case::retrieveContactIdsByCaseId($params['id']);
+ $origContactId = CRM_Utils_Array::first($origContactIds);
+ }
- $caseBAO = CRM_Case_BAO_Case::create($newParams);
+ // FIXME: Refactor as separate method to get contactId
+ if (count($origContactIds) > 1) {
+ // check valid orig contact id
+ if (empty($params['orig_contact_id'])) {
+ throw new API_Exception('Case is linked with more than one contact id. Provide the required params orig_contact_id to be replaced');
+ }
+ if (!empty($params['orig_contact_id']) && !in_array($params['orig_contact_id'], $origContactIds)) {
+ throw new API_Exception('Invalid case contact id (orig_contact_id)');
+ }
+ $origContactId = $params['orig_contact_id'];
+ }
+
+ // check for same contact id for edit Client
+ if (!empty($params['contact_id']) && !in_array($params['contact_id'], $origContactIds)) {
+ $mergedCaseId = CRM_Case_BAO_Case::mergeCases($params['contact_id'], $params['case_id'], $origContactId, NULL, TRUE);
+ }
+
+ // If we merged cases then update the merged case
+ if (!empty($mergedCaseId[0])) {
+ $params['id'] = $mergedCaseId[0];
+ }
+ }
+
+ // Create/update the case
+ $caseBAO = CRM_Case_BAO_Case::create($params);
if (!$caseBAO) {
throw new API_Exception('Case not created. Please check input params.');
}
- foreach ((array) $params['contact_id'] as $cid) {
- $contactParams = array('case_id' => $caseBAO->id, 'contact_id' => $cid);
- CRM_Case_BAO_CaseContact::create($contactParams);
+ if (isset($params['contact_id'])) {
+ foreach ((array) $params['contact_id'] as $cid) {
+ $contactParams = array('case_id' => $caseBAO->id, 'contact_id' => $cid);
+ CRM_Case_BAO_CaseContact::create($contactParams);
+ }
+ }
+
+ if (!isset($params['id'])) {
+ // As the API was not passed an id we have created a new case.
+ // Only run the xmlProcessor for new cases to get all configuration for the new case.
+ _civicrm_api3_case_create_xmlProcessor($params, $caseBAO);
+ }
+
+ // return case
+ $values = array();
+ _civicrm_api3_object_to_array($caseBAO, $values[$caseBAO->id]);
+
+ return civicrm_api3_create_success($values, $params, 'Case', 'create', $caseBAO);
+}
+
+/**
+ * When creating a new case, run the xmlProcessor to get all necessary params/configuration
+ * for the new case, as cases use an xml file to store their configuration.
+ * @param $params
+ * @param $caseBAO
+ */
+function _civicrm_api3_case_create_xmlProcessor($params, $caseBAO) {
+ // Format params for xmlProcessor
+ if (isset($caseBAO->id)) {
+ $params['id'] = $caseBAO->id;
}
// Initialize XML processor with $params
$xmlProcessor = new CRM_Case_XMLProcessor_Process();
$xmlProcessorParams = array(
- 'clientID' => $params['contact_id'],
- 'creatorID' => $params['creator_id'],
+ 'clientID' => CRM_Utils_Array::value('contact_id', $params),
+ 'creatorID' => CRM_Utils_Array::value('creator_id', $params),
'standardTimeline' => 1,
'activityTypeName' => 'Open Case',
- 'caseID' => $caseBAO->id,
- 'subject' => $params['subject'],
+ 'caseID' => CRM_Utils_Array::value('id', $params),
+ 'subject' => CRM_Utils_Array::value('subject', $params),
'location' => CRM_Utils_Array::value('location', $params),
- 'activity_date_time' => $params['start_date'],
+ 'activity_date_time' => CRM_Utils_Array::value('start_date', $params),
'duration' => CRM_Utils_Array::value('duration', $params),
'medium_id' => CRM_Utils_Array::value('medium_id', $params),
'details' => CRM_Utils_Array::value('details', $params),
// Do it! :-D
$xmlProcessor->run($params['case_type'], $xmlProcessorParams);
-
- // return case
- $values = array();
- _civicrm_api3_object_to_array($caseBAO, $values[$caseBAO->id]);
-
- return civicrm_api3_create_success($values, $params, 'Case', 'create', $caseBAO);
}
/**
'description' => 'Id of an activity in the case',
'type' => CRM_Utils_Type::T_INT,
);
+ $params['tag_id'] = array(
+ 'title' => 'Tags',
+ 'description' => 'Find activities with specified tags.',
+ 'type' => 1,
+ 'FKClassName' => 'CRM_Core_DAO_Tag',
+ 'FKApiName' => 'Tag',
+ 'supports_joins' => TRUE,
+ );
}
/**
* 'client_id' => finds all cases with a specific client
* 'activity_id' => returns the case containing a specific activity
* 'contact_id' => finds all cases associated with a contact (in any role, not just client)
+ * $params CRM_Utils_SQL_Select $sql
+ * Other apis wishing to wrap & extend this one can pass in a $sql object with extra clauses
*
* @throws API_Exception
* @return array
* (get mode, case_id provided): Array with case details, case roles, case activity ids, (search mode, case_id not provided): Array of cases found
*/
-function civicrm_api3_case_get($params) {
+function civicrm_api3_case_get($params, $sql = NULL) {
$options = _civicrm_api3_get_options_from_params($params);
- $sql = CRM_Utils_SQL_Select::fragment();
+ if (!is_a($sql, 'CRM_Utils_SQL_Select')) {
+ $sql = CRM_Utils_SQL_Select::fragment();
+ }
// Add clause to search by client
if (!empty($params['contact_id'])) {
$sql->where("a.id IN (SELECT case_id FROM civicrm_case_contact WHERE $clause)");
}
+ // Order by case contact (primary client)
+ // Ex: "contact_id", "contact_id.display_name", "contact_id.sort_name DESC".
+ if (!empty($options['sort']) && strpos($options['sort'], 'contact_id') !== FALSE) {
+ $sort = explode(', ', $options['sort']);
+ $contactSort = NULL;
+ foreach ($sort as $index => &$sortString) {
+ if (strpos($sortString, 'contact_id') === 0) {
+ $contactSort = $sortString;
+ $sortString = '(1)';
+ // Get sort field and direction
+ list($sortField, $dir) = array_pad(explode(' ', $contactSort), 2, 'ASC');
+ list(, $sortField) = array_pad(explode('.', $sortField), 2, 'id');
+ // Validate inputs
+ if (!array_key_exists($sortField, CRM_Contact_DAO_Contact::fieldKeys()) || ($dir != 'ASC' && $dir != 'DESC')) {
+ throw new API_Exception("Unknown field specified for sort. Cannot order by '$contactSort'");
+ }
+ $sql->orderBy("case_contact.$sortField $dir", NULL, $index);
+ }
+ }
+ // Remove contact sort params so the basic_get function doesn't see them
+ $params['options']['sort'] = implode(', ', $sort);
+ unset($params['option_sort'], $params['option.sort'], $params['sort']);
+ // Add necessary joins to the first case client
+ if ($contactSort) {
+ $sql->join('ccc', 'LEFT JOIN (SELECT * FROM civicrm_case_contact WHERE id IN (SELECT MIN(id) FROM civicrm_case_contact GROUP BY case_id)) AS ccc ON ccc.case_id = a.id');
+ $sql->join('case_contact', 'LEFT JOIN civicrm_contact AS case_contact ON ccc.contact_id = case_contact.id AND case_contact.is_deleted <> 1');
+ }
+ }
+
// Add clause to search by activity
if (!empty($params['activity_id'])) {
if (!CRM_Utils_Rule::positiveInteger($params['activity_id'])) {
->where("civicrm_case_activity.activity_id IN ($activityId)");
}
- $foundcases = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, TRUE, 'Case', $sql);
+ // Clause to search by tag
+ if (!empty($params['tag_id'])) {
+ $dummySpec = array();
+ _civicrm_api3_validate_integer($params, 'tag_id', $dummySpec, 'Case');
+ if (!is_array($params['tag_id'])) {
+ $params['tag_id'] = array('=' => $params['tag_id']);
+ }
+ $clause = \CRM_Core_DAO::createSQLFilter('tag_id', $params['tag_id']);
+ if ($clause) {
+ $sql->where('a.id IN (SELECT entity_id FROM civicrm_entity_tag WHERE entity_table = "civicrm_case" AND !clause)', array('!clause' => $clause));
+ }
+ }
+
+ $cases = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), array('sequential' => 0) + $params, TRUE, 'Case', $sql);
- if (empty($options['is_count'])) {
+ if (empty($options['is_count']) && !empty($cases['values'])) {
// For historic reasons we return these by default only when fetching a case by id
- if (!empty($params['id']) && empty($options['return'])) {
+ if (!empty($params['id']) && is_numeric($params['id']) && empty($options['return'])) {
$options['return'] = array(
'contacts' => 1,
'activities' => 1,
);
}
- foreach ($foundcases['values'] as &$case) {
- _civicrm_api3_case_read($case, $options);
+ _civicrm_api3_case_read($cases['values'], $options);
+
+ // We disabled sequential to keep the list indexed for case_read(). Now add it back.
+ if (!empty($params['sequential'])) {
+ $cases['values'] = array_values($cases['values']);
}
}
- return $foundcases;
+ return $cases;
}
/**
);
}
+/**
+ * Add a timeline to a case.
+ *
+ * @param array $params
+ *
+ * @throws API_Exception
+ * @return array
+ */
+function civicrm_api3_case_addtimeline($params) {
+ $caseType = CRM_Case_BAO_Case::getCaseType($params['case_id'], 'name');
+ $xmlProcessor = new CRM_Case_XMLProcessor_Process();
+ $xmlProcessorParams = array(
+ 'clientID' => CRM_Case_BAO_Case::getCaseClients($params['case_id']),
+ 'creatorID' => $params['creator_id'],
+ 'standardTimeline' => 0,
+ 'activity_date_time' => $params['activity_date_time'],
+ 'caseID' => $params['case_id'],
+ 'caseType' => $caseType,
+ 'activitySetName' => $params['timeline'],
+ );
+ $xmlProcessor->run($caseType, $xmlProcessorParams);
+ return civicrm_api3_create_success();
+}
+
+/**
+ * Adjust Metadata for addtimeline action.
+ *
+ * @param array $params
+ * Array of parameters determined by getfields.
+ */
+function _civicrm_api3_case_addtimeline_spec(&$params) {
+ $params['case_id'] = array(
+ 'title' => 'Case ID',
+ 'description' => 'Id of case to update',
+ 'type' => CRM_Utils_Type::T_INT,
+ 'api.required' => 1,
+ );
+ $params['timeline'] = array(
+ 'title' => 'Timeline',
+ 'description' => 'Name of activity set',
+ 'type' => CRM_Utils_Type::T_STRING,
+ 'api.required' => 1,
+ );
+ $params['activity_date_time'] = array(
+ 'api.default' => 'now',
+ 'title' => 'Activity date time',
+ 'description' => 'Timeline start date',
+ 'type' => CRM_Utils_Type::T_DATE,
+ );
+ $params['creator_id'] = array(
+ 'api.default' => 'user_contact_id',
+ 'title' => 'Activity creator',
+ 'description' => 'Contact id of timeline creator',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+}
+
+/**
+ * Merge 2 cases.
+ *
+ * @param array $params
+ *
+ * @throws API_Exception
+ * @return array
+ */
+function civicrm_api3_case_merge($params) {
+ $clients1 = CRM_Case_BAO_Case::getCaseClients($params['case_id_1']);
+ $clients2 = CRM_Case_BAO_Case::getCaseClients($params['case_id_2']);
+ CRM_Case_BAO_Case::mergeCases($clients1[0], $params['case_id_1'], $clients2[0], $params['case_id_2']);
+ return civicrm_api3_create_success();
+}
+
+/**
+ * Adjust Metadata for merge action.
+ *
+ * @param array $params
+ * Array of parameters determined by getfields.
+ */
+function _civicrm_api3_case_merge_spec(&$params) {
+ $params['case_id_1'] = array(
+ 'title' => 'Case ID 1',
+ 'description' => 'Id of main case',
+ 'type' => CRM_Utils_Type::T_INT,
+ 'api.required' => 1,
+ );
+ $params['case_id_2'] = array(
+ 'title' => 'Case ID 2',
+ 'description' => 'Id of second case',
+ 'type' => CRM_Utils_Type::T_INT,
+ 'api.required' => 1,
+ );
+}
+
/**
* Declare deprecated api functions.
*
}
/**
- * Update a specified case.
+ * @deprecated Update a specified case. Use civicrm_api3_case_create() instead.
*
* @param array $params
* //REQUIRED:
// get original contact id and creator id of case
if (!empty($params['contact_id'])) {
$origContactIds = CRM_Case_BAO_Case::retrieveContactIdsByCaseId($params['id']);
- $origContactId = $origContactIds[1];
+ $origContactId = CRM_Utils_Array::first($origContactIds);
}
if (count($origContactIds) > 1) {
* @endcode
*
* @throws API_Exception
- * @return bool
- * true if success, else false
+ * @return mixed
*/
function civicrm_api3_case_delete($params) {
//check parameters
}
/**
- * Augment a case with extra data.
+ * Case.restore API specification
*
- * @param array $case
- * @param array $options
+ * @param array $spec description of fields supported by this API call
+ * @return void
*/
-function _civicrm_api3_case_read(&$case, $options) {
- if (empty($options['return']) || !empty($options['return']['contact_id'])) {
- // Legacy support for client_id - TODO: in apiv4 remove 'client_id'
- $case['client_id'] = $case['contact_id'] = CRM_Case_BAO_Case::retrieveContactIdsByCaseId($case['id']);
+function _civicrm_api3_case_restore_spec(&$spec) {
+ $result = civicrm_api3('Case', 'getfields', array('api_action' => 'delete'));
+ $spec = array('id' => $result['values']['id']);
+}
+
+/**
+ * Restore a specified case from the trash.
+ *
+ * @param array $params
+ * @throws API_Exception
+ * @return mixed
+ */
+function civicrm_api3_case_restore($params) {
+ if (CRM_Case_BAO_Case::restoreCase($params['id'])) {
+ return civicrm_api3_create_success($params, $params, 'Case', 'restore');
+ }
+ else {
+ throw new API_Exception('Could not restore case.');
}
- if (!empty($options['return']['contacts'])) {
- //get case contacts
- $contacts = CRM_Case_BAO_Case::getcontactNames($case['id']);
- $relations = CRM_Case_BAO_Case::getRelatedContacts($case['id']);
- $case['contacts'] = array_merge($contacts, $relations);
+}
+
+/**
+ * Augment case results with extra data.
+ *
+ * @param array $cases
+ * @param array $options
+ */
+function _civicrm_api3_case_read(&$cases, $options) {
+ foreach ($cases as &$case) {
+ if (empty($options['return']) || !empty($options['return']['contact_id'])) {
+ // Legacy support for client_id - TODO: in apiv4 remove 'client_id'
+ $case['client_id'] = $case['contact_id'] = CRM_Case_BAO_Case::retrieveContactIdsByCaseId($case['id']);
+ }
+ if (!empty($options['return']['contacts'])) {
+ //get case contacts
+ $contacts = CRM_Case_BAO_Case::getcontactNames($case['id']);
+ $relations = CRM_Case_BAO_Case::getRelatedContacts($case['id']);
+ $case['contacts'] = array_unique(array_merge($contacts, $relations), SORT_REGULAR);
+ }
+ if (!empty($options['return']['activities'])) {
+ // add case activities array - we'll populate them in bulk below
+ $case['activities'] = array();
+ }
+ // Properly render this joined field
+ if (!empty($options['return']['case_type_id.definition'])) {
+ if (!empty($case['case_type_id.definition'])) {
+ list($xml) = CRM_Utils_XML::parseString($case['case_type_id.definition']);
+ }
+ else {
+ $caseTypeId = !empty($case['case_type_id']) ? $case['case_type_id'] : CRM_Core_DAO::getFieldValue('CRM_Case_DAO_Case', $case['id'], 'case_type_id');
+ $caseTypeName = !empty($case['case_type_id.name']) ? $case['case_type_id.name'] : CRM_Core_DAO::getFieldValue('CRM_Case_DAO_CaseType', $caseTypeId, 'name');
+ $xml = CRM_Case_XMLRepository::singleton()->retrieve($caseTypeName);
+ }
+ $case['case_type_id.definition'] = array();
+ if ($xml) {
+ $case['case_type_id.definition'] = CRM_Case_BAO_CaseType::convertXmlToDefinition($xml);
+ }
+ }
}
+ // Bulk-load activities
if (!empty($options['return']['activities'])) {
- //get case activities
- $case['activities'] = array();
- $query = "SELECT activity_id FROM civicrm_case_activity WHERE case_id = %1";
- $dao = CRM_Core_DAO::executeQuery($query, array(1 => array($case['id'], 'Integer')));
+ $query = "SELECT case_id, activity_id FROM civicrm_case_activity WHERE case_id IN (%1)";
+ $params = array(1 => array(implode(',', array_keys($cases)), 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES));
+ $dao = CRM_Core_DAO::executeQuery($query, $params);
while ($dao->fetch()) {
- $case['activities'][] = $dao->activity_id;
+ $cases[$dao->case_id]['activities'][] = $dao->activity_id;
}
}
- // Properly render this joined field
- if (!empty($options['return']['case_type_id.definition'])) {
- if (!empty($case['case_type_id.definition'])) {
- list($xml) = CRM_Utils_XML::parseString($case['case_type_id.definition']);
+ // Bulk-load tags. Supports joins onto the tag entity.
+ $tagGet = array('tag_id', 'entity_id');
+ foreach (array_keys($options['return']) as $key) {
+ if (strpos($key, 'tag_id.') === 0) {
+ $tagGet[] = $key;
+ $options['return']['tag_id'] = 1;
}
- else {
- $caseTypeId = !empty($case['case_type_id']) ? $case['case_type_id'] : CRM_Core_DAO::getFieldValue('CRM_Case_DAO_Case', $case['id'], 'case_type_id');
- $caseTypeName = !empty($case['case_type_id.name']) ? $case['case_type_id.name'] : CRM_Core_DAO::getFieldValue('CRM_Case_DAO_CaseType', $caseTypeId, 'name');
- $xml = CRM_Case_XMLRepository::singleton()->retrieve($caseTypeName);
- }
- $case['case_type_id.definition'] = array();
- if ($xml) {
- $case['case_type_id.definition'] = CRM_Case_BAO_CaseType::convertXmlToDefinition($xml);
+ }
+ if (!empty($options['return']['tag_id'])) {
+ $tags = civicrm_api3('EntityTag', 'get', array(
+ 'entity_table' => 'civicrm_case',
+ 'entity_id' => array('IN' => array_keys($cases)),
+ 'return' => $tagGet,
+ 'options' => array('limit' => 0),
+ ));
+ foreach ($tags['values'] as $tag) {
+ $key = (int) $tag['entity_id'];
+ unset($tag['entity_id'], $tag['id']);
+ $cases[$key]['tag_id'][$tag['tag_id']] = $tag;
}
}
}
* @param array $params
*/
function _civicrm_api3_case_format_params(&$params) {
- // figure out case type id from case type and vice-versa
+ // Format/include custom params
+ $values = array();
+ _civicrm_api3_custom_format_params($params, $values, 'Case');
+ $params = array_merge($params, $values);
+
+ if (empty($params['case_type_id']) && empty($params['case_type'])) {
+ return;
+ }
+
+ // figure out case_type_id from case_type and vice-versa
$caseTypes = CRM_Case_PseudoConstant::caseType('name', FALSE);
if (empty($params['case_type_id'])) {
$params['case_type_id'] = array_search($params['case_type'], $caseTypes);
}
}
+
/**
* It actually works a lot better to use the CaseContact api instead of the Case api
* for entityRef fields so we can perform the necessary joins,
projects / civicrm-core.git / blobdiff