3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
12 namespace Civi\ActionSchedule
;
16 * @package Civi\ActionSchedule
18 * This is the initial implementation of MappingInterface; it was
19 * constructed by cutting out swaths from CRM_Core_BAO_ActionSchedule.
20 * New implementers should consider implementing MappingInterface on
23 * Background: The original designers of ActionMappings intended that
24 * one could create and configure new mappings through the database.
25 * To, e.g., define the filtering options for CiviEvent, you
26 * would insert a record in "civicrm_action_mapping" with fields like
27 * "entity" (a table name, eg "civicrm_event"), "entity_value" (an
28 * option-group name, eg "event_types").
30 * Unfortunately, the metadata in "civicrm_action_mapping" proved
31 * inadequate and was not updated to cope. Instead, a number
32 * of work-arounds for specific entities were hard-coded into
33 * the core action-scheduling code. Ultimately, to add a new
34 * mapping type, one needed to run around and patch a dozen
37 * The new MappingInterface makes no pretense of database-driven
38 * configuration. The dozen places have been consolidated and
39 * replaced with functions in MappingInterface.
41 * This "Mapping" implementation is a refactoring of the old
42 * hard-coded bits. Internally, it uses the concepts from
43 * "civicrm_action_mapping". The resulting code is more
44 * convoluted than a clean implementation of MappingInterface, but
45 * it strictly matches the old behavior (based on logging/comparing
46 * the queries produced through ActionScheduleTest).
48 abstract class Mapping
implements MappingInterface
{
50 private static $fields = [
57 'entity_status_label',
65 * @param array $params
69 public static function create($params) {
70 return new static($params);
76 * @param array $params
78 public function __construct($params) {
79 foreach (self
::$fields as $field) {
80 if (isset($params[$field])) {
81 $this->{$field} = $params[$field];
89 * The basic entity to query (table name).
92 * Ex: 'civicrm_activity', 'civicrm_event'.
97 * The basic entity to query (label).
100 * Ex: 'Activity', 'Event'
102 private $entity_label;
105 * Level 1 filter -- the field/option-list to filter on.
108 * Ex: 'activity_type', 'civicrm_event', 'event_template'.
110 private $entity_value;
113 * Level 1 filter -- The field label.
116 * Ex: 'Activity Type', 'Event Name', 'Event Template'.
118 private $entity_value_label;
121 * Level 2 filter -- the field/option-list to filter on.
123 * Ex: 'activity_status, 'civicrm_participant_status_type', 'auto_renew_options'.
125 private $entity_status;
128 * Level 2 filter -- the field label.
130 * Ex: 'Activity Status', 'Participant Status', 'Auto Rewnewal Options'.
132 private $entity_status_label;
135 * Date filter -- the field name.
137 * Ex: 'event_start_date'
139 private $entity_date_start;
142 * Date filter -- the field name.
144 * Ex: 'event_end_date'.
146 private $entity_date_end;
151 public function getId() {
158 public function getEntity() {
159 return $this->entity
;
163 * Get a printable label for this mapping type.
167 public function getLabel() {
168 return $this->entity_label
;
172 * Get a printable label to use a header on the 'value' filter.
176 public function getValueHeader() {
177 return $this->entity_value_label
;
181 * Get a printable label to use a header on the 'status' filter.
185 public function getStatusHeader() {
186 return $this->entity_status_label
;
190 * Get a list of value options.
193 * Array(string $value => string $label).
194 * Ex: array(123 => 'Phone Call', 456 => 'Meeting').
196 public function getValueLabels() {
197 return self
::getValueLabelMap($this->entity_value
);
201 * Get a list of status options.
203 * @param string|int $value
204 * The list of status options may be contingent upon the selected filter value.
205 * This is the selected filter value.
207 * Array(string $value => string $label).
208 * Ex: Array(123 => 'Completed', 456 => 'Scheduled').
210 public function getStatusLabels($value) {
211 if ($this->entity_status
=== 'auto_renew_options') {
212 if ($value && \CRM_Core_DAO
::getFieldValue('CRM_Member_DAO_MembershipType', $value, 'auto_renew')) {
213 return \CRM_Core_OptionGroup
::values('auto_renew_options');
219 return self
::getValueLabelMap($this->entity_status
);
223 * Get a list of available date fields.
226 * Array(string $fieldName => string $fieldLabel).
228 public function getDateFields() {
229 $dateFieldLabels = [];
230 if (!empty($this->entity_date_start
)) {
231 $dateFieldLabels[$this->entity_date_start
] = ucwords(str_replace('_', ' ', $this->entity_date_start
));
233 if (!empty($this->entity_date_end
)) {
234 $dateFieldLabels[$this->entity_date_end
] = ucwords(str_replace('_', ' ', $this->entity_date_end
));
236 return $dateFieldLabels;
240 * Get a list of recipient types.
242 * Note: A single schedule may filter on *zero* or *one* recipient types.
243 * When an admin chooses a value, it's stored in $schedule->recipient.
246 * array(string $value => string $label).
247 * Ex: array('assignee' => 'Activity Assignee').
249 public function getRecipientTypes() {
254 * Get a list of recipients which match the given type.
256 * Note: A single schedule may filter on *multiple* recipients.
257 * When an admin chooses value(s), it's stored in $schedule->recipient_listing.
259 * @param string $recipientType
260 * Ex: 'participant_role'.
262 * Array(mixed $name => string $label).
263 * Ex: array(1 => 'Attendee', 2 => 'Volunteer').
264 * @see getRecipientTypes
266 public function getRecipientListing($recipientType) {
270 protected static function getValueLabelMap($name) {
271 static $valueLabelMap = NULL;
272 if ($valueLabelMap === NULL) {
273 // CRM-20510: Include CiviCampaign activity types along with CiviCase IF component is enabled
274 $valueLabelMap['activity_type'] = \CRM_Core_PseudoConstant
::activityType(TRUE, TRUE, FALSE, 'label', TRUE);
275 asort($valueLabelMap['activity_type']);
277 $valueLabelMap['activity_status'] = \CRM_Core_PseudoConstant
::activityStatus();
278 $valueLabelMap['event_type'] = \CRM_Event_PseudoConstant
::eventType();
279 $valueLabelMap['civicrm_event'] = \CRM_Event_PseudoConstant
::event(NULL, FALSE, "( is_template IS NULL OR is_template != 1 )");
280 $valueLabelMap['civicrm_participant_status_type'] = \CRM_Event_PseudoConstant
::participantStatus(NULL, NULL, 'label');
281 $valueLabelMap['event_template'] = \CRM_Event_PseudoConstant
::eventTemplates();
282 $valueLabelMap['auto_renew_options'] = \CRM_Core_OptionGroup
::values('auto_renew_options');
283 $valueLabelMap['contact_date_reminder_options'] = \CRM_Core_OptionGroup
::values('contact_date_reminder_options');
284 $valueLabelMap['civicrm_membership_type'] = \CRM_Member_PseudoConstant
::membershipType();
286 $allCustomFields = \CRM_Core_BAO_CustomField
::getFields('');
288 'birth_date' => ts('Birth Date'),
289 'created_date' => ts('Created Date'),
290 'modified_date' => ts('Modified Date'),
292 foreach ($allCustomFields as $fieldID => $field) {
293 if ($field['data_type'] == 'Date') {
294 $dateFields["custom_$fieldID"] = $field['label'];
297 $valueLabelMap['civicrm_contact'] = $dateFields;
300 return $valueLabelMap[$name];
304 * Determine whether a schedule based on this mapping is sufficiently
307 * @param \CRM_Core_DAO_ActionSchedule $schedule
309 * Array (string $code => string $message).
310 * List of error messages.
312 public function validateSchedule($schedule) {
317 * Generate a query to locate contacts who match the given
320 * @param \CRM_Core_DAO_ActionSchedule $schedule
321 * @param string $phase
322 * See, e.g., RecipientBuilder::PHASE_RELATION_FIRST.
323 * @param array $defaultParams
324 * @return \CRM_Utils_SQL_Select
326 abstract public function createQuery($schedule, $phase, $defaultParams);
329 * Determine whether a schedule based on this mapping should
330 * reset the reminder state if the trigger date changes.
334 * @param \CRM_Core_DAO_ActionSchedule $schedule
336 public function resetOnTriggerDateChange($schedule) {
341 * Determine whether a schedule based on this mapping should
342 * send to additional contacts.
344 abstract public function sendToAdditional($entityId): bool;