Civi/ActionSchedule/MappingInterface.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 namespace Civi\ActionSchedule;
  13
  14 /**
  15  * Interface MappingInterface
  16  * @package Civi\ActionSchedule
  17  */
  18 interface MappingInterface {
  19
  20   /**
  21    * @return mixed
  22    */
  23   public function getId();
  24
  25   /**
  26    * @return string
  27    */
  28   public function getEntity();
  29
  30   /**
  31    * Get a printable label for this mapping type.
  32    *
  33    * @return string
  34    */
  35   public function getLabel();
  36
  37   /**
  38    * Get a printable label to use as the header on the 'value' filter.
  39    *
  40    * @return string
  41    */
  42   public function getValueHeader();
  43
  44   /**
  45    * Get a printable label to use as the header on the 'status' filter.
  46    *
  47    * @return string
  48    */
  49   public function getStatusHeader();
  50
  51   /**
  52    * Get a list of value options.
  53    *
  54    * @return array
  55    *   Array(string $value => string $label).
  56    *   Ex: array(123 => 'Phone Call', 456 => 'Meeting').
  57    */
  58   public function getValueLabels();
  59
  60   /**
  61    * Get a list of status options.
  62    *
  63    * @param string|int $value
  64    *   The list of status options may be contingent upon the selected filter value.
  65    *   This is the selected filter value.
  66    * @return array
  67    *   Array(string $value => string $label).
  68    *   Ex: Array(123 => 'Completed', 456 => 'Scheduled').
  69    */
  70   public function getStatusLabels($value);
  71
  72   /**
  73    * Get a list of available date fields.
  74    *
  75    * @return array
  76    *   Array(string $fieldName => string $fieldLabel).
  77    */
  78   public function getDateFields();
  79
  80   /**
  81    * Get a list of recipient types.
  82    *
  83    * Note: A single schedule may filter on *zero* or *one* recipient types.
  84    * When an admin chooses a value, it's stored in $schedule->recipient.
  85    *
  86    * @return array
  87    *   array(string $value => string $label).
  88    *   Ex: array('assignee' => 'Activity Assignee').
  89    */
  90   public function getRecipientTypes();
  91
  92   /**
  93    * Get a list of recipients which match the given type.
  94    *
  95    * Note: A single schedule may filter on *multiple* recipients.
  96    * When an admin chooses value(s), it's stored in $schedule->recipient_listing.
  97    *
  98    * @param string $recipientType
  99    *   Ex: 'participant_role'.
 100    * @return array
 101    *   Array(mixed $name => string $label).
 102    *   Ex: array(1 => 'Attendee', 2 => 'Volunteer').
 103    * @see getRecipientTypes
 104    */
 105   public function getRecipientListing($recipientType);
 106
 107   /**
 108    * Determine whether a schedule based on this mapping is sufficiently
 109    * complete.
 110    *
 111    * @param \CRM_Core_DAO_ActionSchedule $schedule
 112    * @return array
 113    *   Array (string $code => string $message).
 114    *   List of error messages.
 115    */
 116   public function validateSchedule($schedule);
 117
 118   /**
 119    * Generate a query to locate contacts who match the given
 120    * schedule.
 121    *
 122    * @param \CRM_Core_DAO_ActionSchedule $schedule
 123    * @param string $phase
 124    *   See, e.g., RecipientBuilder::PHASE_RELATION_FIRST.
 125    * @param array $defaultParams
 126    *   Default parameters that should be included with query.
 127    * @return \CRM_Utils_SQL_Select
 128    * @see RecipientBuilder
 129    */
 130   public function createQuery($schedule, $phase, $defaultParams);
 131
 132   /**
 133    * Determine whether a schedule based on this mapping should
 134    * reset the reminder state if the trigger date changes.
 135    *
 136    * @return bool
 137    *
 138    * @param \CRM_Core_DAO_ActionSchedule $schedule
 139    */
 140   public function resetOnTriggerDateChange($schedule);
 141
 142   /**
 143    * Determine whether a schedule based on this mapping should
 144    * send to additional contacts.
 145    */
 146   public function sendToAdditional($entityId): bool;
 147
 148 }