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