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     $activities = civicrm_api3('Activity', 'get', [
 104       'id' => ['IN' => $entityIds],
 105       'options' => ['limit' => 0],
 106       'return' => self::getReturnFields($this->activeTokens),
 107     ]);
 108     $prefetch['activity'] = $activities['values'];
 109
 110     // Store the activity types if needed
 111     if (in_array('activity_type', $this->activeTokens)) {
 112       $this->activityTypes = \CRM_Core_OptionGroup::values('activity_type');
 113     }
 114
 115     // Store the activity statuses if needed
 116     if (in_array('status', $this->activeTokens)) {
 117       $this->activityStatuses = \CRM_Core_OptionGroup::values('activity_status');
 118     }
 119
 120     // Store the campaigns if needed
 121     if (in_array('campaign', $this->activeTokens)) {
 122       $this->campaigns = \CRM_Campaign_BAO_Campaign::getCampaigns();
 123     }
 124
 125     return $prefetch;
 126   }
 127
 128   /**
 129    * @inheritDoc
 130    */
 131   public function evaluateToken(TokenRow $row, $entity, $field, $prefetch = NULL) {
 132     // maps token name to api field
 133     $mapping = [
 134       'activity_id' => 'id',
 135     ];
 136
 137     // Get ActivityID either from actionSearchResult (for scheduled reminders) if exists
 138     $activityId = $row->context['actionSearchResult']->entityID ?? $row->context[$this->getEntityContextSchema()];
 139
 140     $activity = $prefetch['activity'][$activityId];
 141
 142     if (in_array($field, ['activity_date_time', 'created_date', 'modified_date'])) {
 143       $row->tokens($entity, $field, \CRM_Utils_Date::customFormat($activity[$field]));
 144     }
 145     elseif (isset($mapping[$field]) and (isset($activity[$mapping[$field]]))) {
 146       $row->tokens($entity, $field, $activity[$mapping[$field]]);
 147     }
 148     elseif (in_array($field, ['activity_type'])) {
 149       $row->tokens($entity, $field, $this->activityTypes[$activity['activity_type_id']]);
 150     }
 151     elseif (in_array($field, ['status'])) {
 152       $row->tokens($entity, $field, $this->activityStatuses[$activity['status_id']]);
 153     }
 154     elseif (in_array($field, ['campaign'])) {
 155       $row->tokens($entity, $field, $this->campaigns[$activity['campaign_id']]);
 156     }
 157     elseif (in_array($field, ['case_id'])) {
 158       // An activity can be linked to multiple cases so case_id is always an array.
 159       // We just return the first case ID for the token.
 160       $row->tokens($entity, $field, is_array($activity['case_id']) ? reset($activity['case_id']) : $activity['case_id']);
 161     }
 162     elseif (array_key_exists($field, $this->customFieldTokens)) {
 163       $row->tokens($entity, $field,
 164         isset($activity[$field])
 165           ? \CRM_Core_BAO_CustomField::displayValue($activity[$field], $field)
 166           : ''
 167       );
 168     }
 169     elseif (isset($activity[$field])) {
 170       $row->tokens($entity, $field, $activity[$field]);
 171     }
 172   }
 173
 174   /**
 175    * Get the basic tokens provided.
 176    *
 177    * @return array token name => token label
 178    */
 179   protected function getBasicTokens(): array {
 180     if (!isset($this->basicTokens)) {
 181       $this->basicTokens = [
 182         'activity_id' => ts('Activity ID'),
 183         'activity_type' => ts('Activity Type'),
 184         'subject' => ts('Activity Subject'),
 185         'details' => ts('Activity Details'),
 186         'activity_date_time' => ts('Activity Date-Time'),
 187         'created_date' => ts('Activity Created Date'),
 188         'modified_date' => ts('Activity Modified Date'),
 189         'activity_type_id' => ts('Activity Type ID'),
 190         'status' => ts('Activity Status'),
 191         'status_id' => ts('Activity Status ID'),
 192         'location' => ts('Activity Location'),
 193         'duration' => ts('Activity Duration'),
 194         'campaign' => ts('Activity Campaign'),
 195         'campaign_id' => ts('Activity Campaign ID'),
 196       ];
 197       if (array_key_exists('CiviCase', CRM_Core_Component::getEnabledComponents())) {
 198         $this->basicTokens['case_id'] = ts('Activity Case ID');
 199       }
 200     }
 201     return $this->basicTokens;
 202   }
 203
 204 }