CRM/Activity/Tokens.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | Copyright CiviCRM LLC. All rights reserved.                        |
   6  |                                                                    |
   7  | This work is published under the GNU AGPLv3 license with some      |
   8  | permitted exceptions and without any warranty. For full license    |
   9  | and copyright information, see https://civicrm.org/licensing       |
  10  +--------------------------------------------------------------------+
  11  */
  12
  13 /**
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17
  18 use Civi\Token\AbstractTokenSubscriber;
  19 use Civi\Token\Event\TokenValueEvent;
  20 use Civi\Token\TokenRow;
  21
  22 /**
  23  * Class CRM_Member_Tokens
  24  *
  25  * Generate "activity.*" tokens.
  26  *
  27  * This TokenSubscriber was originally produced by refactoring the code from the
  28  * scheduled-reminder system with the goal of making that system
  29  * more flexible. The current implementation is still coupled to
  30  * scheduled-reminders. It would be good to figure out a more generic
  31  * implementation which is not tied to scheduled reminders, although
  32  * that is outside the current scope.
  33  *
  34  * This has been enhanced to work with PDF/letter merge
  35  */
  36 class CRM_Activity_Tokens extends AbstractTokenSubscriber {
  37
  38   use CRM_Core_TokenTrait;
  39
  40   /**
  41    * @return string
  42    */
  43   private function getEntityName(): string {
  44     return 'activity';
  45   }
  46
  47   /**
  48    * @return string
  49    */
  50   private function getEntityTableName(): string {
  51     return 'civicrm_activity';
  52   }
  53
  54   /**
  55    * @return string
  56    */
  57   private function getEntityContextSchema(): string {
  58     return 'activityId';
  59   }
  60
  61   /**
  62    * Mapping from tokenName to api return field
  63    * Using arrays allows more complex tokens to be handled that require more than one API field.
  64    * For example, an address token might want ['street_address', 'city', 'postal_code']
  65    *
  66    * @var array
  67    */
  68   private static $fieldMapping = [
  69     'activity_id' => ['id'],
  70     'activity_type' => ['activity_type_id'],
  71     'status' => ['status_id'],
  72     'campaign' => ['campaign_id'],
  73   ];
  74
  75   /**
  76    * @inheritDoc
  77    */
  78   public function alterActionScheduleQuery(\Civi\ActionSchedule\Event\MailingQueryEvent $e) {
  79     if ($e->mapping->getEntity() !== $this->getEntityTableName()) {
  80       return;
  81     }
  82
  83     // The joint expression for activities needs some extra nuance to handle.
  84     // Multiple revisions of the activity.
  85     // Q: Could we simplify & move the extra AND clauses into `where(...)`?
  86     $e->query->param('casEntityJoinExpr', 'e.id = reminder.entity_id AND e.is_current_revision = 1 AND e.is_deleted = 0');
  87   }
  88
  89   /**
  90    * @inheritDoc
  91    */
  92   public function prefetch(TokenValueEvent $e) {
  93     // Find all the entity IDs
  94     $entityIds
  95       = $e->getTokenProcessor()->getContextValues('actionSearchResult', 'entityID')
  96       + $e->getTokenProcessor()->getContextValues($this->getEntityContextSchema());
  97
  98     if (!$entityIds) {
  99       return NULL;
 100     }
 101
 102     // Get data on all activities for basic and customfield tokens
 103     $prefetch['activity'] = civicrm_api3('Activity', 'get', [
 104       'id' => ['IN' => $entityIds],
 105       'options' => ['limit' => 0],
 106       'return' => self::getReturnFields($this->activeTokens),
 107     ])['values'];
 108
 109     // Store the activity types if needed
 110     if (in_array('activity_type', $this->activeTokens, TRUE)) {
 111       $this->activityTypes = \CRM_Core_OptionGroup::values('activity_type');
 112     }
 113
 114     // Store the activity statuses if needed
 115     if (in_array('status', $this->activeTokens, TRUE)) {
 116       $this->activityStatuses = \CRM_Core_OptionGroup::values('activity_status');
 117     }
 118
 119     // Store the campaigns if needed
 120     if (in_array('campaign', $this->activeTokens, TRUE)) {
 121       $this->campaigns = \CRM_Campaign_BAO_Campaign::getCampaigns();
 122     }
 123
 124     return $prefetch;
 125   }
 126
 127   /**
 128    * Evaluate the content of a single token.
 129    *
 130    * @param \Civi\Token\TokenRow $row
 131    *   The record for which we want token values.
 132    * @param string $entity
 133    *   The name of the token entity.
 134    * @param string $field
 135    *   The name of the token field.
 136    * @param mixed $prefetch
 137    *   Any data that was returned by the prefetch().
 138    *
 139    * @throws \CRM_Core_Exception
 140    */
 141   public function evaluateToken(TokenRow $row, $entity, $field, $prefetch = NULL) {
 142     // maps token name to api field
 143     $mapping = [
 144       'activity_id' => 'id',
 145     ];
 146
 147     // Get ActivityID either from actionSearchResult (for scheduled reminders) if exists
 148     $activityId = $row->context['actionSearchResult']->entityID ?? $row->context[$this->getEntityContextSchema()];
 149
 150     $activity = $prefetch['activity'][$activityId];
 151
 152     if (in_array($field, ['activity_date_time', 'created_date', 'modified_date'])) {
 153       $row->tokens($entity, $field, \CRM_Utils_Date::customFormat($activity[$field]));
 154     }
 155     elseif (isset($mapping[$field]) and (isset($activity[$mapping[$field]]))) {
 156       $row->tokens($entity, $field, $activity[$mapping[$field]]);
 157     }
 158     elseif (in_array($field, ['activity_type'])) {
 159       $row->tokens($entity, $field, $this->activityTypes[$activity['activity_type_id']]);
 160     }
 161     elseif (in_array($field, ['status'])) {
 162       $row->tokens($entity, $field, $this->activityStatuses[$activity['status_id']]);
 163     }
 164     elseif (in_array($field, ['campaign'])) {
 165       $row->tokens($entity, $field, $this->campaigns[$activity['campaign_id']]);
 166     }
 167     elseif (in_array($field, ['case_id'])) {
 168       // An activity can be linked to multiple cases so case_id is always an array.
 169       // We just return the first case ID for the token.
 170       $row->tokens($entity, $field, is_array($activity['case_id']) ? reset($activity['case_id']) : $activity['case_id']);
 171     }
 172     elseif (array_key_exists($field, $this->customFieldTokens)) {
 173       $row->tokens($entity, $field,
 174         isset($activity[$field])
 175           ? \CRM_Core_BAO_CustomField::displayValue($activity[$field], $field)
 176           : ''
 177       );
 178     }
 179     elseif (isset($activity[$field])) {
 180       $row->tokens($entity, $field, $activity[$field]);
 181     }
 182   }
 183
 184   /**
 185    * Get the basic tokens provided.
 186    *
 187    * @return array token name => token label
 188    */
 189   protected function getBasicTokens(): array {
 190     if (!isset($this->basicTokens)) {
 191       $this->basicTokens = [
 192         'activity_id' => ts('Activity ID'),
 193         'activity_type' => ts('Activity Type'),
 194         'subject' => ts('Activity Subject'),
 195         'details' => ts('Activity Details'),
 196         'activity_date_time' => ts('Activity Date-Time'),
 197         'created_date' => ts('Activity Created Date'),
 198         'modified_date' => ts('Activity Modified Date'),
 199         'activity_type_id' => ts('Activity Type ID'),
 200         'status' => ts('Activity Status'),
 201         'status_id' => ts('Activity Status ID'),
 202         'location' => ts('Activity Location'),
 203         'duration' => ts('Activity Duration'),
 204         'campaign' => ts('Activity Campaign'),
 205         'campaign_id' => ts('Activity Campaign ID'),
 206       ];
 207       if (array_key_exists('CiviCase', CRM_Core_Component::getEnabledComponents())) {
 208         $this->basicTokens['case_id'] = ts('Activity Case ID');
 209       }
 210     }
 211     return $this->basicTokens;
 212   }
 213
 214 }