civicrm · colemanw · Aug 17, 2022 · Jul 26, 2022
diff --git a/CRM/Campaign/BAO/Petition.php b/CRM/Campaign/BAO/Petition.php
@@ -571,7 +571,7 @@ public static function sendEmail($params, $sendEmailMode) {
           CRM_Core_BAO_MessageTemplate::sendTemplate(
             [
               'groupName' => 'msg_tpl_workflow_petition',
-              'valueName' => 'petition_sign',
+              'workflow' => 'petition_sign',
               'contactId' => $params['contactId'],
               'tplParams' => $tplParams,
               'from' => "\"{$domainEmailName}\" <{$domainEmailAddress}>",
@@ -628,7 +628,7 @@ public static function sendEmail($params, $sendEmailMode) {
           CRM_Core_BAO_MessageTemplate::sendTemplate(
             [
               'groupName' => 'msg_tpl_workflow_petition',
-              'valueName' => 'petition_confirmation_needed',
+              'workflow' => 'petition_confirmation_needed',
               'contactId' => $params['contactId'],
               'tplParams' => $tplParams,
               'from' => "\"{$domainEmailName}\" <{$domainEmailAddress}>",

diff --git a/CRM/Case/BAO/Case.php b/CRM/Case/BAO/Case.php
@@ -1340,7 +1340,7 @@ public static function sendActivityCopy($clientId, $activityId, $contacts, $atta
       list($result[CRM_Utils_Array::value('contact_id', $info)], $subject, $message, $html) = CRM_Core_BAO_MessageTemplate::sendTemplate(
         [
           'groupName' => 'msg_tpl_workflow_case',
-          'valueName' => 'case_activity',
+          'workflow' => 'case_activity',
           'contactId' => $info['contact_id'] ?? NULL,
           'tplParams' => $tplParams,
           'from' => $receiptFrom,

diff --git a/CRM/Contribute/BAO/ContributionPage.php b/CRM/Contribute/BAO/ContributionPage.php
@@ -454,7 +454,7 @@ public static function sendMail($contactID, $values, $isTest = FALSE, $returnMes
       // send duplicate alert, if dupe match found during on-behalf-of processing.
       if (!empty($values['onbehalf_dupe_alert'])) {
         $sendTemplateParams['groupName'] = 'msg_tpl_workflow_contribution';
-        $sendTemplateParams['valueName'] = 'contribution_dupalert';
+        $sendTemplateParams['workflow'] = 'contribution_dupalert';
         $sendTemplateParams['from'] = ts('Automatically Generated') . " <{$values['receipt_from_email']}>";
         $sendTemplateParams['toName'] = $values['receipt_from_name'] ?? NULL;
         $sendTemplateParams['toEmail'] = $values['receipt_from_email'] ?? NULL;
@@ -554,7 +554,7 @@ public static function recurringNotify($contributionID, $type, $recur): void {
       [$displayName, $email] = CRM_Contact_BAO_Contact_Location::getEmailDetails($contribution['contact_id'], FALSE);
       $templatesParams = [
         'groupName' => 'msg_tpl_workflow_contribution',
-        'valueName' => 'contribution_recurring_notify',
+        'workflow' => 'contribution_recurring_notify',
         'contactId' => $contribution['contact_id'],
         'tplParams' => [
           'recur_frequency_interval' => $recur->frequency_interval,

diff --git a/CRM/Contribute/BAO/ContributionSoft.php b/CRM/Contribute/BAO/ContributionSoft.php
@@ -666,7 +666,7 @@ public static function pcpNotifyOwner(int $contributionID, array $contributionSo
       $domainValues = CRM_Core_BAO_Domain::getNameAndEmail();
       $sendTemplateParams = [
         'groupName' => 'msg_tpl_workflow_contribution',
-        'valueName' => 'pcp_owner_notify',
+        'workflow' => 'pcp_owner_notify',
         'contactId' => $contributionSoft['contact_id'],
         'toEmail' => $ownerEmail,
         'toName' => $ownerName,

diff --git a/CRM/Contribute/Form/CancelSubscription.php b/CRM/Contribute/Form/CancelSubscription.php
@@ -263,7 +263,7 @@ public function postProcess() {
         $sendTemplateParams
           = [
             'groupName' => $this->_mode == 'auto_renew' ? 'msg_tpl_workflow_membership' : 'msg_tpl_workflow_contribution',
-            'valueName' => $this->_mode == 'auto_renew' ? 'membership_autorenew_cancelled' : 'contribution_recurring_cancelled',
+            'workflow' => $this->_mode == 'auto_renew' ? 'membership_autorenew_cancelled' : 'contribution_recurring_cancelled',
             'contactId' => $this->getSubscriptionDetails()->contact_id,
             'tplParams' => $tplParams,
             'tokenContext' => ['contribution_recurId' => $this->getContributionRecurID()],

diff --git a/CRM/Contribute/Form/UpdateBilling.php b/CRM/Contribute/Form/UpdateBilling.php
@@ -323,7 +323,7 @@ public function postProcess() {
 
       $sendTemplateParams = array(
         'groupName' => $this->getSubscriptionDetails()->membership_id ? 'msg_tpl_workflow_membership' : 'msg_tpl_workflow_contribution',
-        'valueName' => $this->getSubscriptionDetails()->membership_id ? 'membership_autorenew_billing' : 'contribution_recurring_billing',
+        'workflow' => $this->getSubscriptionDetails()->membership_id ? 'membership_autorenew_billing' : 'contribution_recurring_billing',
         'contactId' => $this->getSubscriptionDetails()->contact_id,
         'tplParams' => $tplParams,
         'isTest' => $this->getSubscriptionDetails()->is_test,

diff --git a/CRM/Contribute/Form/UpdateSubscription.php b/CRM/Contribute/Form/UpdateSubscription.php
@@ -303,7 +303,7 @@ public function postProcess() {
 
         $sendTemplateParams = [
           'groupName' => 'msg_tpl_workflow_contribution',
-          'valueName' => 'contribution_recurring_edit',
+          'workflow' => 'contribution_recurring_edit',
           'contactId' => $contactID,
           'tplParams' => ['receipt_from_email' => $receiptFrom],
           'isTest' => $this->_subscriptionDetails->is_test,

diff --git a/CRM/Core/BAO/MessageTemplate.php b/CRM/Core/BAO/MessageTemplate.php
@@ -287,8 +287,8 @@ protected static function renderTemplateRaw($params) {
     $modelDefaults = [
       // instance of WorkflowMessageInterface, containing a list of data to provide to the message-template
       'model' => NULL,
-      // Symbolic name of the workflow step. Matches the option-value-name of the template.
-      'valueName' => NULL,
+      // Symbolic name of the workflow step. Matches the value in civicrm_msg_template.workflow_name.
+      'workflow' => NULL,
       // additional template params (other than the ones already set in the template singleton)
       'tplParams' => [],
       // additional token params (passed to the TokenProcessor)
@@ -343,7 +343,7 @@ protected static function renderTemplateRaw($params) {
     $params = array_merge($modelDefaults, $viewDefaults, $envelopeDefaults, $params);
 
     CRM_Utils_Hook::alterMailParams($params, 'messageTemplate');
-    $mailContent = self::loadTemplate((string) $params['valueName'], $params['isTest'], $params['messageTemplateID'] ?? NULL, $params['groupName'] ?? '', $params['messageTemplate'], $params['subject'] ?? NULL);
+    $mailContent = self::loadTemplate((string) $params['workflow'], $params['isTest'], $params['messageTemplateID'] ?? NULL, $params['groupName'] ?? '', $params['messageTemplate'], $params['subject'] ?? NULL);
 
     self::synchronizeLegacyParameters($params);
     $rendered = CRM_Core_TokenSmarty::render(CRM_Utils_Array::subset($mailContent, ['text', 'html', 'subject']), $params['tokenContext'], $params['tplParams']);
@@ -363,6 +363,9 @@ protected static function renderTemplateRaw($params) {
    * @param array $params
    */
   private static function synchronizeLegacyParameters(&$params) {
+    // 'valueName' is deprecated, docs were updated some time back
+    // and people have been notified. Having it here means the
+    // hooks will still see it until we remove.
     CRM_Utils_Array::pathSync($params, ['workflow'], ['valueName']);
     CRM_Utils_Array::pathSync($params, ['tokenContext', 'contactId'], ['contactId']);
     CRM_Utils_Array::pathSync($params, ['tokenContext', 'smarty'], ['disableSmarty'], function ($v, bool $isCanon) {
@@ -505,7 +508,7 @@ protected static function loadTemplate(string $workflowName, bool $isTest, int $
       // Group name & valueName are deprecated parameters. At some point it will not be passed out.
       // https://github.com/civicrm/civicrm-core/pull/17180
       'groupName' => $groupName,
-      'valueName' => $workflowName,
+      'workflow' => $workflowName,
     ];
 
     CRM_Utils_Hook::alterMailContent($mailContent);

diff --git a/CRM/Core/BAO/UFGroup.php b/CRM/Core/BAO/UFGroup.php
@@ -2690,7 +2690,7 @@ public static function commonSendMail($contactID, &$values) {
       CRM_Core_BAO_MessageTemplate::sendTemplate(
         [
           'groupName' => 'msg_tpl_workflow_uf',
-          'valueName' => 'uf_notify',
+          'workflow' => 'uf_notify',
           'contactId' => $contactID,
           'tplParams' => [
             'displayName' => $displayName,

diff --git a/CRM/Event/BAO/Event.php b/CRM/Event/BAO/Event.php
@@ -1190,7 +1190,7 @@ public static function sendMail($contactID, $values, $participantId, $isTest = F
 
         $sendTemplateParams = [
           'groupName' => 'msg_tpl_workflow_event',
-          'valueName' => 'event_online_receipt',
+          'workflow' => 'event_online_receipt',
           'contactId' => $contactID,
           'isTest' => $isTest,
           'tplParams' => $tplParams,

diff --git a/CRM/Event/Form/SelfSvcTransfer.php b/CRM/Event/Form/SelfSvcTransfer.php
@@ -399,7 +399,7 @@ public function participantTransfer($participant): void {
 
       $sendTemplateParams = [
         'groupName' => 'msg_tpl_workflow_event',
-        'valueName' => 'event_online_receipt',
+        'workflow' => 'event_online_receipt',
         'contactId' => $participantDetails[$participant->id]['contact_id'],
         'tplParams' => $tplParams,
         'from' => $receiptFrom,

diff --git a/CRM/Financial/BAO/Payment.php b/CRM/Financial/BAO/Payment.php
@@ -281,7 +281,7 @@ public static function sendConfirmation($params) {
 
     $sendTemplateParams = [
       'groupName' => 'msg_tpl_workflow_contribution',
-      'valueName' => 'payment_or_refund_notification',
+      'workflow' => 'payment_or_refund_notification',
       'PDFFilename' => ts('notification') . '.pdf',
       'contactId' => $entities['contact']['id'],
       'toName' => $entities['contact']['display_name'],

diff --git a/CRM/Friend/BAO/Friend.php b/CRM/Friend/BAO/Friend.php
@@ -289,7 +289,7 @@ public static function sendMail($contactID, &$values) {
 
     $templateParams = [
       'groupName' => 'msg_tpl_workflow_friend',
-      'valueName' => 'friend',
+      'workflow' => 'friend',
       'contactId' => $contactID,
       'tplParams' => [
         $values['module'] => $values['module'],

diff --git a/CRM/PCP/BAO/PCP.php b/CRM/PCP/BAO/PCP.php
@@ -716,7 +716,7 @@ public static function sendStatusUpdate($pcpId, $newStatus, $isInitial = FALSE,
     list($sent, $subject, $message, $html) = CRM_Core_BAO_MessageTemplate::sendTemplate(
       [
         'groupName' => 'msg_tpl_workflow_contribution',
-        'valueName' => $tplName,
+        'workflow' => $tplName,
         'contactId' => $pcpInfo['contact_id'],
         'tplParams' => $tplParams,
         'from' => $receiptFrom,

diff --git a/CRM/PCP/Form/Campaign.php b/CRM/PCP/Form/Campaign.php
@@ -315,7 +315,7 @@ public function postProcess() {
       list($sent, $subject, $message, $html) = CRM_Core_BAO_MessageTemplate::sendTemplate(
         [
           'groupName' => 'msg_tpl_workflow_contribution',
-          'valueName' => 'pcp_notify',
+          'workflow' => 'pcp_notify',
           'contactId' => $contactID,
           'from' => "$domainEmailName <$domainEmailAddress>",
           'toEmail' => $to,

diff --git a/CRM/Pledge/BAO/Pledge.php b/CRM/Pledge/BAO/Pledge.php
@@ -595,7 +595,7 @@ public static function sendAcknowledgment(&$form, $params) {
     [$sent, $subject, $message, $html] = CRM_Core_BAO_MessageTemplate::sendTemplate(
       [
         'groupName' => 'msg_tpl_workflow_pledge',
-        'valueName' => 'pledge_acknowledge',
+        'workflow' => 'pledge_acknowledge',
         'contactId' => $params['contact_id'],
         'from' => $receiptFrom,
         'toName' => $pledgerDisplayName,
@@ -962,7 +962,7 @@ public static function updatePledgeStatus($params): array {
             ] = CRM_Core_BAO_MessageTemplate::sendTemplate(
               [
                 'groupName' => 'msg_tpl_workflow_pledge',
-                'valueName' => 'pledge_reminder',
+                'workflow' => 'pledge_reminder',
                 'contactId' => $contactId,
                 'from' => $receiptFrom,
                 'toName' => $pledgerName,

diff --git a/api/v3/MessageTemplate.php b/api/v3/MessageTemplate.php
@@ -93,18 +93,27 @@ function civicrm_api3_message_template_send($params) {
   _civicrm_api3_message_template_send_spec($fieldSpec);
 
   foreach ($fieldSpec as $field => $spec) {
-    if (isset($spec['api.aliases']) && array_key_exists($field, $params)) {
+    // There is some dark magic going on here.
+    // The point of the 'api.aliases' metadata is generally
+    // to ensure that old params can be passed in and they still work.
+    // However, in this case the api params don't match the BAO
+    // params so the names that have been determined as
+    // 'right' for the api are being transformed into
+    // the 'wrong' BAO ones. It works, it's tested &
+    // we can do better in apiv4 once we get a suitable
+    // api there.
+    if ($spec['name'] !== 'workflow' && isset($spec['api.aliases']) && array_key_exists($field, $params)) {
       $params[CRM_Utils_Array::first($spec['api.aliases'])] = $params[$field];
       unset($params[$field]);
     }
   }
   if (empty($params['messageTemplateID'])) {
-    if (empty($params['valueName'])) {
+    if (empty($params['workflow'])) {
       // Can't use civicrm_api3_verify_mandatory for this because it would give the wrong field names
       throw new API_Exception(
-        'Mandatory key(s) missing from params array: requires id or option_value_name',
+        'Mandatory key(s) missing from params array: requires id or workflow',
         'mandatory_missing',
-        ['fields' => ['id', 'option_value_name']]
+        ['fields' => ['id', 'workflow']]
       );
     }
   }
@@ -126,10 +135,11 @@ function _civicrm_api3_message_template_send_spec(&$params) {
   $params['id']['api.aliases'] = ['messageTemplateID', 'message_template_id'];
   $params['id']['type'] = CRM_Utils_Type::T_INT;
 
-  $params['option_value_name']['description'] = 'option value name of the template (required if no id supplied)';
-  $params['option_value_name']['title'] = 'Option Value Name';
-  $params['option_value_name']['api.aliases'] = ['valueName'];
-  $params['option_value_name']['type'] = CRM_Utils_Type::T_STRING;
+  $params['workflow']['description'] = 'option value name of the template (required if no id supplied)';
+  $params['workflow']['title'] = ts('Workflow');
+  $params['workflow']['api.aliases'] = ['option_value_name', 'valueName'];
+  $params['workflow']['type'] = CRM_Utils_Type::T_STRING;
+  $params['workflow']['name'] = 'workflow';
 
   $params['contact_id']['description'] = 'contact id if contact tokens are to be replaced';
   $params['contact_id']['title'] = 'Contact ID';

diff --git a/ext/eventcart/CRM/Event/Cart/Form/Checkout/Payment.php b/ext/eventcart/CRM/Event/Cart/Form/Checkout/Payment.php
@@ -341,7 +341,7 @@ public function emailReceipt($events_in_cart, $params) {
         'is_pay_later' => $this->is_pay_later,
         'pay_later_receipt' => $this->pay_later_receipt,
       ],
-      'valueName' => 'event_registration_receipt',
+      'workflow' => 'event_registration_receipt',
       'PDFFilename' => ts('confirmation') . '.pdf',
     ];
     $template_params_to_copy = [

diff --git a/tests/phpunit/CRM/Core/BAO/MessageTemplateTest.php b/tests/phpunit/CRM/Core/BAO/MessageTemplateTest.php
@@ -30,7 +30,7 @@ public function testRenderTemplate(): void {
       'suffix_id' => NULL,
     ]);
     $rendered = CRM_Core_BAO_MessageTemplate::renderTemplate([
-      'valueName' => 'case_activity',
+      'workflow' => 'case_activity',
       'tokenContext' => [
         'contactId' => $contactId,
       ],
@@ -58,7 +58,7 @@ public function testSendTemplate_RenderMode_OpenTemplate(): void {
     ]);
     [$sent, $subject, $messageText, $messageHtml] = CRM_Core_BAO_MessageTemplate::sendTemplate(
       [
-        'valueName' => 'case_activity',
+        'workflow' => 'case_activity',
         'contactId' => $contactId,
         'from' => 'admin@example.com',
         // No 'toEmail'/'toName' address => not sendable, but still returns rendered value.
@@ -99,7 +99,7 @@ public function testSendTemplate_RenderMode_DefaultTpl(): void {
 
       [$sent, $subject, $messageText, $messageHtml] = CRM_Core_BAO_MessageTemplate::sendTemplate(
         [
-          'valueName' => 'case_activity',
+          'workflow' => 'case_activity',
           'contactId' => $contactId,
           'from' => 'admin@example.com',
           // No 'toEmail'/'toName' address => not sendable, but still returns rendered value.
@@ -137,7 +137,7 @@ public function testSendTemplateRenderModeTokenContext(): void {
 
       [$sent, $subject, $messageText, $messageHtml] = CRM_Core_BAO_MessageTemplate::sendTemplate(
         [
-          'valueName' => 'case_activity',
+          'workflow' => 'case_activity',
           'tokenContext' => [
             'contactId' => $contactId,
             'activityId' => $activityId,
@@ -188,7 +188,7 @@ public function testCaseActivityCopyTemplate():void {
     $this->assertEquals([], \Civi\Test\Invasive::get([$msg, '_extras']));
 
     [, $subject, $message] = $msg->sendTemplate([
-      'valueName' => 'case_activity',
+      'workflow' => 'case_activity',
       'from' => 'admin@example.com',
       'toName' => 'Demo',
       'toEmail' => 'admin@example.com',
@@ -217,7 +217,7 @@ public function testDomainTokens(): void {
     $tokenString = '{domain.' . implode('} ~ {domain.', array_keys($values)) . '}';
 
     $messageContent = CRM_Core_BAO_MessageTemplate::renderTemplate([
-      'valueName' => 'dummy',
+      'workflow' => 'dummy',
       'messageTemplate' => [
         'msg_html' => $tokenString,
         // Check the space is stripped.
@@ -241,7 +241,7 @@ public function testDomainTokens(): void {
    */
   public function testRenderTemplateSmarty(): void {
     $messageContent = CRM_Core_BAO_MessageTemplate::renderTemplate([
-      'valueName' => 'dummy',
+      'workflow' => 'dummy',
       'messageTemplate' => [
         'msg_html' => '{$tokenString}',
         // Check the space is stripped.
@@ -261,7 +261,7 @@ public function testRenderTemplateSmarty(): void {
    */
   public function testRenderTemplateIgnoreSmarty(): void {
     $messageContent = CRM_Core_BAO_MessageTemplate::renderTemplate([
-      'valueName' => 'dummy',
+      'workflow' => 'dummy',
       'messageTemplate' => [
         'msg_html' => '{$tokenString}',
         // Check the space is stripped.
@@ -308,7 +308,7 @@ public function testContactTokens(): void {
       $tokenString .= "{$key}:{contact.{$key}}\n";
     }
     $messageContent = CRM_Core_BAO_MessageTemplate::renderTemplate([
-      'valueName' => 'dummy',
+      'workflow' => 'dummy',
       'messageTemplate' => [
         'msg_html' => $tokenString,
         // Check the space is stripped.