CRM/Case/BAO/CaseType.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17
  18 /**
  19  * This class contains the functions for Case Type management.
  20  */
  21 class CRM_Case_BAO_CaseType extends CRM_Case_DAO_CaseType {
  22
  23   /**
  24    * Static field for all the case information that we can potentially export.
  25    *
  26    * @var array
  27    */
  28   public static $_exportableFields = NULL;
  29
  30   /**
  31    * Takes an associative array and creates a Case Type object.
  32    *
  33    * the function extract all the params it needs to initialize the create a
  34    * case type object. the params array could contain additional unused name/value
  35    * pairs
  36    *
  37    * @param array $params
  38    *   (reference ) an assoc array of name/value pairs.
  39    *
  40    * @throws CRM_Core_Exception
  41    *
  42    * @return CRM_Case_BAO_CaseType
  43    */
  44   public static function add(&$params) {
  45     $caseTypeDAO = new CRM_Case_DAO_CaseType();
  46
  47     // form the name only if missing: CRM-627
  48     $nameParam = $params['name'] ?? NULL;
  49     if (!$nameParam && empty($params['id'])) {
  50       $params['name'] = CRM_Utils_String::titleToVar($params['title']);
  51     }
  52
  53     // Old case-types (pre-4.5) may keep their ucky names, but new case-types must satisfy isValidName()
  54     if (empty($params['id']) && !empty($params['name']) && !CRM_Case_BAO_CaseType::isValidName($params['name'])) {
  55       throw new CRM_Core_Exception("Cannot create new case-type with malformed name [{$params['name']}]");
  56     }
  57
  58     $caseTypeName = (isset($params['name'])) ? $params['name'] : CRM_Core_DAO::getFieldValue('CRM_Case_DAO_CaseType', $params['id'], 'name', 'id', TRUE);
  59
  60     // function to format definition column
  61     if (isset($params['definition']) && is_array($params['definition'])) {
  62       $params['definition'] = self::convertDefinitionToXML($caseTypeName, $params['definition']);
  63       CRM_Core_ManagedEntities::scheduleReconciliation();
  64     }
  65
  66     $caseTypeDAO->copyValues($params);
  67     $result = $caseTypeDAO->save();
  68     CRM_Case_XMLRepository::singleton()->flush();
  69     return $result;
  70   }
  71
  72   /**
  73    * Generate and assign an arbitrary value to a field of a test object.
  74    *
  75    * @param string $fieldName
  76    * @param array $fieldDef
  77    * @param int $counter
  78    *   The globally-unique ID of the test object.
  79    */
  80   protected function assignTestValue($fieldName, &$fieldDef, $counter) {
  81     if ($fieldName == 'definition') {
  82       $this->{$fieldName} = "<CaseType><name>TestCaseType{$counter}</name></CaseType>";
  83     }
  84     else {
  85       parent::assignTestValue($fieldName, $fieldDef, $counter);
  86     }
  87   }
  88
  89   /**
  90    * Format / convert submitted array to xml for case type definition
  91    *
  92    * @param string $name
  93    * @param array $definition
  94    *   The case-type definition expressed as an array-tree.
  95    * @return string
  96    *   XML
  97    */
  98   public static function convertDefinitionToXML($name, $definition) {
  99
 100     $xw = new XMLWriter();
 101     $xw->openMemory();
 102     $xw->setIndent(TRUE);
 103     $xw->setIndentString(' ');
 104     $xw->startDocument("1.0", 'UTF-8');
 105
 106     $xw->startElement('CaseType');
 107
 108     $xw->startElement('name');
 109     $xw->text($name);
 110     $xw->fullEndElement();
 111
 112     if (array_key_exists('forkable', $definition)) {
 113       $xw->startElement('forkable');
 114       $xw->text((int) $definition['forkable']);
 115       $xw->fullEndElement();
 116     }
 117
 118     if (isset($definition['activityTypes'])) {
 119       $xw->startElement('ActivityTypes');
 120
 121       foreach ($definition['activityTypes'] as $values) {
 122         $xw->startElement('ActivityType');
 123         foreach ($values as $key => $value) {
 124           $xw->startElement($key);
 125           $xw->text($value);
 126           $xw->fullEndElement();
 127         }
 128         // ActivityType
 129         $xw->fullEndElement();
 130       }
 131       // ActivityTypes
 132       $xw->fullEndElement();
 133     }
 134
 135     if (!empty($definition['statuses'])) {
 136       $xw->startElement('Statuses');
 137
 138       foreach ($definition['statuses'] as $value) {
 139         $xw->startElement('Status');
 140         $xw->text($value);
 141         $xw->fullEndElement();
 142       }
 143       // Statuses
 144       $xw->fullEndElement();
 145     }
 146
 147     if (isset($definition['activitySets'])) {
 148
 149       $xw->startElement('ActivitySets');
 150       foreach ($definition['activitySets'] as $k => $val) {
 151
 152         $xw->startElement('ActivitySet');
 153         foreach ($val as $index => $setVal) {
 154           switch ($index) {
 155             case 'activityTypes':
 156               if (!empty($setVal)) {
 157                 $xw->startElement('ActivityTypes');
 158                 foreach ($setVal as $values) {
 159                   $xw->startElement('ActivityType');
 160                   foreach ($values as $key => $value) {
 161                     // Some parameters here may be arrays of values.
 162                     // Also, the tests expect an empty array to be represented as an empty value.
 163                     $value = (array) $value;
 164                     if (count($value) === 0) {
 165                       // Create an empty value.
 166                       $value[] = '';
 167                     }
 168
 169                     foreach ($value as $val) {
 170                       $xw->startElement($key);
 171                       $xw->text($val);
 172                       $xw->fullEndElement();
 173                     }
 174                   }
 175                   // ActivityType
 176                   $xw->fullEndElement();
 177                 }
 178                 // ActivityTypes
 179                 $xw->fullEndElement();
 180               }
 181               break;
 182
 183             // passthrough
 184             case 'sequence':
 185             case 'timeline':
 186               if ($setVal) {
 187                 $xw->startElement($index);
 188                 $xw->text('true');
 189                 $xw->fullEndElement();
 190               }
 191               break;
 192
 193             default:
 194               $xw->startElement($index);
 195               $xw->text($setVal);
 196               $xw->fullEndElement();
 197           }
 198         }
 199         // ActivitySet
 200         $xw->fullEndElement();
 201       }
 202       // ActivitySets
 203       $xw->fullEndElement();
 204     }
 205
 206     if (isset($definition['caseRoles'])) {
 207       $xw->startElement('CaseRoles');
 208       foreach ($definition['caseRoles'] as $values) {
 209         $xw->startElement('RelationshipType');
 210         foreach ($values as $key => $value) {
 211           $xw->startElement($key);
 212           if ($key == 'groups') {
 213             $xw->text(implode(',', (array) $value));
 214           }
 215           else {
 216             $xw->text($value);
 217           }
 218           // $key
 219           $xw->fullEndElement();
 220         }
 221         // RelationshipType
 222         $xw->fullEndElement();
 223       }
 224       // CaseRoles
 225       $xw->fullEndElement();
 226     }
 227
 228     if (array_key_exists('restrictActivityAsgmtToCmsUser', $definition)) {
 229       $xw->startElement('RestrictActivityAsgmtToCmsUser');
 230       $xw->text($definition['restrictActivityAsgmtToCmsUser']);
 231       $xw->fullEndElement();
 232     }
 233     if (!empty($definition['activityAsgmtGrps'])) {
 234       $xw->startElement('ActivityAsgmtGrps');
 235       foreach ((array) $definition['activityAsgmtGrps'] as $value) {
 236         $xw->startElement('Group');
 237         $xw->text($value);
 238         $xw->fullEndElement();
 239       }
 240       // ActivityAsgmtGrps
 241       $xw->fullEndElement();
 242     }
 243
 244     // CaseType
 245     $xw->fullEndElement();
 246     $xw->endDocument();
 247
 248     return $xw->outputMemory();
 249   }
 250
 251   /**
 252    * Get the case definition either from db or read from xml file.
 253    *
 254    * @param SimpleXmlElement $xml
 255    *   A single case-type record.
 256    *
 257    * @return array
 258    *   the definition of the case-type, expressed as PHP array-tree
 259    */
 260   public static function convertXmlToDefinition($xml) {
 261     // build PHP array based on definition
 262     $definition = [];
 263
 264     if (isset($xml->forkable)) {
 265       $definition['forkable'] = (int) $xml->forkable;
 266     }
 267
 268     if (isset($xml->RestrictActivityAsgmtToCmsUser)) {
 269       $definition['restrictActivityAsgmtToCmsUser'] = (int) $xml->RestrictActivityAsgmtToCmsUser;
 270     }
 271
 272     if (isset($xml->ActivityAsgmtGrps)) {
 273       $definition['activityAsgmtGrps'] = (array) $xml->ActivityAsgmtGrps->Group;
 274       // Backwards compat - convert group ids to group names if ids are supplied
 275       if (array_filter($definition['activityAsgmtGrps'], ['\CRM_Utils_Rule', 'integer']) === $definition['activityAsgmtGrps']) {
 276         foreach ($definition['activityAsgmtGrps'] as $idx => $group) {
 277           $definition['activityAsgmtGrps'][$idx] = CRM_Core_DAO::getFieldValue('CRM_Contact_BAO_Group', $group);
 278         }
 279       }
 280     }
 281
 282     // set activity types
 283     if (isset($xml->ActivityTypes)) {
 284       $definition['activityTypes'] = [];
 285       foreach ($xml->ActivityTypes->ActivityType as $activityTypeXML) {
 286         $definition['activityTypes'][] = json_decode(json_encode($activityTypeXML), TRUE);
 287       }
 288     }
 289
 290     // set statuses
 291     if (isset($xml->Statuses)) {
 292       $definition['statuses'] = (array) $xml->Statuses->Status;
 293     }
 294
 295     // set activity sets
 296     if (isset($xml->ActivitySets)) {
 297       $definition['activitySets'] = [];
 298       $definition['timelineActivityTypes'] = [];
 299
 300       foreach ($xml->ActivitySets->ActivitySet as $activitySetXML) {
 301         // parse basic properties
 302         $activitySet = [];
 303         $activitySet['name'] = (string) $activitySetXML->name;
 304         $activitySet['label'] = (string) $activitySetXML->label;
 305         if ('true' == (string) $activitySetXML->timeline) {
 306           $activitySet['timeline'] = 1;
 307         }
 308         if ('true' == (string) $activitySetXML->sequence) {
 309           $activitySet['sequence'] = 1;
 310         }
 311
 312         if (isset($activitySetXML->ActivityTypes)) {
 313           $activitySet['activityTypes'] = [];
 314           foreach ($activitySetXML->ActivityTypes->ActivityType as $activityTypeXML) {
 315             $activityType = json_decode(json_encode($activityTypeXML), TRUE);
 316             $activitySet['activityTypes'][] = $activityType;
 317             if ($activitySetXML->timeline) {
 318               $definition['timelineActivityTypes'][] = $activityType;
 319             }
 320           }
 321         }
 322         $definition['activitySets'][] = $activitySet;
 323       }
 324     }
 325
 326     // set case roles
 327     if (isset($xml->CaseRoles)) {
 328       $definition['caseRoles'] = [];
 329       foreach ($xml->CaseRoles->RelationshipType as $caseRoleXml) {
 330         $caseRole = json_decode(json_encode($caseRoleXml), TRUE);
 331         if (!empty($caseRole['groups'])) {
 332           $caseRole['groups'] = explode(',', $caseRole['groups']);
 333         }
 334         $definition['caseRoles'][] = $caseRole;
 335       }
 336     }
 337
 338     return $definition;
 339   }
 340
 341   /**
 342    * Given the list of params in the params array, fetch the object
 343    * and store the values in the values array
 344    *
 345    * @param array $params
 346    *   Input parameters to find object.
 347    * @param array $values
 348    *   Output values of the object.
 349    *
 350    * @return CRM_Case_BAO_CaseType|null the found object or null
 351    */
 352   public static function &getValues(&$params, &$values) {
 353     $caseType = new CRM_Case_BAO_CaseType();
 354
 355     $caseType->copyValues($params);
 356
 357     if ($caseType->find(TRUE)) {
 358       CRM_Core_DAO::storeValues($caseType, $values);
 359       return $caseType;
 360     }
 361     return NULL;
 362   }
 363
 364   /**
 365    * Takes an associative array and creates a case type object.
 366    *
 367    * @param array $params
 368    *   (reference ) an assoc array of name/value pairs.
 369    *
 370    * @return CRM_Case_BAO_CaseType
 371    */
 372   public static function &create(&$params) {
 373     $transaction = new CRM_Core_Transaction();
 374
 375     if (!empty($params['id'])) {
 376       CRM_Utils_Hook::pre('edit', 'CaseType', $params['id'], $params);
 377     }
 378     else {
 379       CRM_Utils_Hook::pre('create', 'CaseType', NULL, $params);
 380     }
 381
 382     $caseType = self::add($params);
 383
 384     if (is_a($caseType, 'CRM_Core_Error')) {
 385       $transaction->rollback();
 386       return $caseType;
 387     }
 388
 389     if (!empty($params['id'])) {
 390       CRM_Utils_Hook::post('edit', 'CaseType', $caseType->id, $case);
 391     }
 392     else {
 393       CRM_Utils_Hook::post('create', 'CaseType', $caseType->id, $case);
 394     }
 395     $transaction->commit();
 396     CRM_Case_XMLRepository::singleton(TRUE);
 397     CRM_Core_OptionGroup::flushAll();
 398
 399     return $caseType;
 400   }
 401
 402   /**
 403    * Retrieve DB object based on input parameters.
 404    *
 405    * It also stores all the retrieved values in the default array.
 406    *
 407    * @param array $params
 408    *   (reference ) an assoc array of name/value pairs.
 409    * @param array $defaults
 410    *   (reference ) an assoc array to hold the name / value pairs.
 411    *                        in a hierarchical manner
 412    *
 413    * @return CRM_Case_BAO_CaseType
 414    */
 415   public static function retrieve(&$params, &$defaults) {
 416     $caseType = CRM_Case_BAO_CaseType::getValues($params, $defaults);
 417     return $caseType;
 418   }
 419
 420   /**
 421    * @param int $caseTypeId
 422    *
 423    * @throws CRM_Core_Exception
 424    * @return mixed
 425    */
 426   public static function del($caseTypeId) {
 427     $caseType = new CRM_Case_DAO_CaseType();
 428     $caseType->id = $caseTypeId;
 429     $refCounts = $caseType->getReferenceCounts();
 430     $total = array_sum(CRM_Utils_Array::collect('count', $refCounts));
 431     if ($total) {
 432       throw new CRM_Core_Exception(ts("You can not delete this case type -- it is assigned to %1 existing case record(s). If you do not want this case type to be used going forward, consider disabling it instead.", [1 => $total]));
 433     }
 434     $result = $caseType->delete();
 435     CRM_Case_XMLRepository::singleton(TRUE);
 436     return $result;
 437   }
 438
 439   /**
 440    * Determine if a case-type name is well-formed
 441    *
 442    * @param string $caseType
 443    * @return bool
 444    */
 445   public static function isValidName($caseType) {
 446     return preg_match('/^[a-zA-Z0-9_]+$/', $caseType);
 447   }
 448
 449   /**
 450    * Determine if the case-type has *both* DB and file-based definitions.
 451    *
 452    * @param int $caseTypeId
 453    * @return bool|null
 454    *   TRUE if there are *both* DB and file-based definitions
 455    */
 456   public static function isForked($caseTypeId) {
 457     $caseTypeName = CRM_Core_DAO::getFieldValue('CRM_Case_DAO_CaseType', $caseTypeId, 'name', 'id', TRUE);
 458     if ($caseTypeName) {
 459       $dbDefinition = CRM_Core_DAO::getFieldValue('CRM_Case_DAO_CaseType', $caseTypeId, 'definition', 'id', TRUE);
 460       $fileDefinition = CRM_Case_XMLRepository::singleton()->retrieveFile($caseTypeName);
 461       return $fileDefinition && $dbDefinition;
 462     }
 463     return NULL;
 464   }
 465
 466   /**
 467    * Determine if modifications are allowed on the case-type
 468    *
 469    * @param int $caseTypeId
 470    * @return bool
 471    *   TRUE if the definition can be modified
 472    */
 473   public static function isForkable($caseTypeId) {
 474     $caseTypeName = CRM_Core_DAO::getFieldValue('CRM_Case_DAO_CaseType', $caseTypeId, 'name', 'id', TRUE);
 475     if ($caseTypeName) {
 476       // if file-based definition explicitly disables "forkable" option, then don't allow changes to definition
 477       $fileDefinition = CRM_Case_XMLRepository::singleton()->retrieveFile($caseTypeName);
 478       if ($fileDefinition && isset($fileDefinition->forkable)) {
 479         return CRM_Utils_String::strtobool((string) $fileDefinition->forkable);
 480       }
 481     }
 482     return TRUE;
 483   }
 484
 485 }