Civi/ActionSchedule/MappingInterface.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 namespace Civi\ActionSchedule;
  29
  30 /**
  31  * Interface MappingInterface
  32  * @package Civi\ActionSchedule
  33  */
  34 interface MappingInterface {
  35
  36   /**
  37    * @return mixed
  38    */
  39   public function getId();
  40
  41   /**
  42    * @return string
  43    */
  44   public function getEntity();
  45
  46   /**
  47    * Get a printable label for this mapping type.
  48    *
  49    * @return string
  50    */
  51   public function getLabel();
  52
  53   /**
  54    * Get a printable label to use as the header on the 'value' filter.
  55    *
  56    * @return string
  57    */
  58   public function getValueHeader();
  59
  60   /**
  61    * Get a printable label to use as the header on the 'status' filter.
  62    *
  63    * @return string
  64    */
  65   public function getStatusHeader();
  66
  67   /**
  68    * Get a list of value options.
  69    *
  70    * @return array
  71    *   Array(string $value => string $label).
  72    *   Ex: array(123 => 'Phone Call', 456 => 'Meeting').
  73    */
  74   public function getValueLabels();
  75
  76   /**
  77    * Get a list of status options.
  78    *
  79    * @param string|int $value
  80    *   The list of status options may be contingent upon the selected filter value.
  81    *   This is the selected filter value.
  82    * @return array
  83    *   Array(string $value => string $label).
  84    *   Ex: Array(123 => 'Completed', 456 => 'Scheduled').
  85    */
  86   public function getStatusLabels($value);
  87
  88   /**
  89    * Get a list of available date fields.
  90    *
  91    * @return array
  92    *   Array(string $fieldName => string $fieldLabel).
  93    */
  94   public function getDateFields();
  95
  96   /**
  97    * Get a list of recipient types.
  98    *
  99    * Note: A single schedule may filter on *zero* or *one* recipient types.
 100    * When an admin chooses a value, it's stored in $schedule->recipient.
 101    *
 102    * @return array
 103    *   array(string $value => string $label).
 104    *   Ex: array('assignee' => 'Activity Assignee').
 105    */
 106   public function getRecipientTypes();
 107
 108   /**
 109    * Get a list of recipients which match the given type.
 110    *
 111    * Note: A single schedule may filter on *multiple* recipients.
 112    * When an admin chooses value(s), it's stored in $schedule->recipient_listing.
 113    *
 114    * @param string $recipientType
 115    *   Ex: 'participant_role'.
 116    * @return array
 117    *   Array(mixed $name => string $label).
 118    *   Ex: array(1 => 'Attendee', 2 => 'Volunteer').
 119    * @see getRecipientTypes
 120    */
 121   public function getRecipientListing($recipientType);
 122
 123   /**
 124    * Determine whether a schedule based on this mapping is sufficiently
 125    * complete.
 126    *
 127    * @param \CRM_Core_DAO_ActionSchedule $schedule
 128    * @return array
 129    *   Array (string $code => string $message).
 130    *   List of error messages.
 131    */
 132   public function validateSchedule($schedule);
 133
 134   /**
 135    * Generate a query to locate contacts who match the given
 136    * schedule.
 137    *
 138    * @param \CRM_Core_DAO_ActionSchedule $schedule
 139    * @param string $phase
 140    *   See, e.g., RecipientBuilder::PHASE_RELATION_FIRST.
 141    * @param array $defaultParams
 142    *   Default parameters that should be included with query.
 143    * @return \CRM_Utils_SQL_Select
 144    * @see RecipientBuilder
 145    */
 146   public function createQuery($schedule, $phase, $defaultParams);
 147
 148   /**
 149    * Determine whether a schedule based on this mapping should
 150    * reset the reminder state if the trigger date changes.
 151    *
 152    * @return bool
 153    *
 154    * @param \CRM_Core_DAO_ActionSchedule $schedule
 155    */
 156   public function resetOnTriggerDateChange($schedule);
 157
 158 }