Preps release updates

docs/configuration/updates.md

@@ -11,13 +11,13 @@ The guides below provide details for noteworthy upgrades such as breaking change
 
 ### Craft 4
 
-| Upgrading to Plugin      | Update Guides                             | Notes                                                                           | 
-|:-------------------------|:------------------------------------------|:--------------------------------------------------------------------------------|
-| Transactional 4.44.444   | [Transactional][#444444-transactional] ⚠️ | Email Types, Notification Event Condition Builder, Audiences. **Major update!** |
-| Data Studio 4.5.0        | [Data Studio][#450-data-studio] ⚠️        | Removes Custom Sources                                                          |
-| Data Studio 4.44.444 | [Data Studio][#444444-data-studio] ⚠️     | New Lite version. **Major update!**                                             |
-| Redirects 4.44.444       | [Redirects][#444444-redirects]            | Improved workflow options.                                                      |
-| Framework 4.0.0          | [All Modules][#400-framework] ⚠️          | Added Craft 4 Support. **Major update!**                                        |
+| Upgrading to Plugin            | Update Guides                                  | Notes                                                                           | 
+|:-------------------------------|:-----------------------------------------------|:--------------------------------------------------------------------------------|
+| Transactional 4.44.444    | [Transactional][#444444-transactional] ⚠️ | Email Types, Notification Event Condition Builder, Audiences. **Major update!** |
+| Data Studio 4.46.0             | [Data Studio][#4460-data-studio] ⚠️            | Removes Custom Sources                                                          |
+| Data Studio 4.44.444 | [Data Studio][#444444-data-studio] ⚠️          | New Lite version. **Major update!**                                             |
+| Redirects 4.44.444             | [Redirects][#444444-redirects]                 | Improved workflow options.                                                      |
+| Framework 4.0.0                | [All Modules][#400-framework] ⚠️               | Added Craft 4 Support. **Major update!**                                        |
 
 #### Craft 3 Migration Path
 
@@ -37,7 +37,7 @@ To upgrade Craft and Sprout to a version earlier than Craft `3.7.x` and Sprout `
 
 [#444444-transactional]: ../updates/4.44.444-transactional.md
 
-[#450-data-studio]: ../updates/4.5.0-data-studio.md
+[#4460-data-studio]: ../updates/4.46.0-data-studio.md
 
 [#444444-data-studio]: ../updates/4.44.444-data-studio.md
 

docs/updates/4.44.444-transactional.md

@@ -5,91 +5,119 @@ description: Upgrade Sprout Transactional module 4.44.444
 
 # Upgrading to Transactional v4.44.444
 
-The Transactional Email Module no manages the core notification email functionality.
+The Transactional Email Module manages Sprout's core notification email functionality and in this major release adds significant features such as Audiences, Email Types, and the Notification Event Condition Builder.
 
-Email Types can now be configured and allow you to create transactional emails with custom Field Layouts, Templates, and Mailer Settings.
+## Breaking Changes
 
-Notification Events have been rebuilt to use Craft's new Condition Builder, for more flexibility when creating your Notification Events.
+### Email Types
 
-Review all rules and test notifications after upgrade. We've tried to migrate all settings but the condition builder can handle much more advanced use cases with Drafts/Revisions/Sites and you should test and confirm it behaves the way you expect.
+Email Templates have been refactored into Email Types, giving you the ability to customize your email workflows in much greater detail. When a new email is created, a content author must now select which Email Type they wish to create.
 
-## Breaking Changes
+Beyond email templates, Email Types can also be configured with custom fields, field layouts, and mailer settings.
+
+#### Review all migrated Email Types
+
+In Craft 3, Email Template settings only stored the template path of the email template for a given email and these paths could be managed in two places:
+
+1. Globally
+2. On an per-email basis
+
+In Craft 4, Email Types are more advanced so many of the settings for the Email Types created in the migration are using default settings. Also, things like the Email Type name may not end up being too user friendly as they are based on the template path (i.e. "_Custom Templates \_email/path_"). In the migration, each unique template found creates a new Email Type.
+
+After the migration, we recommend reviewing all Email Type settings to ensure they match your needs.
+
+### Notification Event Condition Builder
+
+Notification Events have been refactored to use Craft's powerful and extensible Condition Builder. Authors can now manage notifications using Craft's familiar condition builder UI, the same UI used for conditional field logic and customizing element sources.
+
+We recommend you review all Notification Event settings and test your notifications after upgrade.
+
+While we've tried to migrate all settings correctly, there were a few instances (noted below) where we had to make a judgement call, and the Condition Builder can now handle much more advanced use cases with Drafts, Revisions, and Sites logic and you should test and and confirm your Transactional email are being sent as intended. 
+
+Below we review a few situations where you may need to manually update your settings:
+
+#### When New and When Updated Element Events are now separate
+
+In Craft 3, the "When an Entry is Saved" Notification Event allowed you to select if the notification was sent "When New", "When Updated", or both.
+
+In Craft 4, this single event has become two events: "When an entry is created" and "When an entry is updated". In the case you had a Transactional Email that had both "When New" and "When updated" selected, you will now need to create a second Transactional Email to trigger an email for both scenarios.
+
+The same is true for the "When a user is saved" Notification Event. If you have a Transactional Email with both the "When New" and "When Updated" scenarios selected, only one will get migrated and you'll have to create the second email manually after the migration. 
+
+#### On Save User Event handles Admin users differently
+
+In Craft 3, the "When a user is saved" Notification Event allowed you to select if you wanted to include "Admins" as a User Group. Admins are not a default User Group in Craft and with the new Condition Builder must be handled separately.
+
+If your Transactional Email was only being sent to Admins, we can migrate that correctly. Or if it was only sent to User Groups, that should be migrated correctly as well. But if you had both checked, you'll need to manually create a new Transactional Email to handle the Admins use case after the migration.
+
+#### Send Method is retired. All emails will be sent as Lists.
+
+In Craft 3, you could select the "Send Method" for an email, which gave you the option to send emails to each person on the list individually, or to alternatively send a single email to everyone. 
+
+In Craft 4, we've retired this setting and all emails will be sent to each person on the list individually.
+
+#### Send Rules have been migrated to use Twig Expression Condition Rule
+
+In Craft 3, the "Send Rule" setting allowed you to use a Twig Expression to limit when your email was sent to only when the event triggered matched your Twig Expression.
+
+In Craft 4, this setting has been moved and is now available as the "Twig Expression" Condition Rule in the Condition Builder. 
+
+_Note: The Twig Expression Condition Rule is also available wherever you see the Condition Builder in Craft, however it can only be used for Element Match behavior, such as with Conditional Field Layout Logic, and it will not work to modify an Element Query, such as with Element Sources and Search filtering. We've reached out to Craft with a feature request to help us limit where this appears to only the Condition Builder scenarios where it works._
+
+### Custom Notification Events
+
+Custom Notification Events will need to be updated. See the base class `BarrelStrength\Sprout\transactional\notificationevents\NotificationEvent` for details and review the Sprout Notification Events for examples under `BarrelStrength\Sprout\transactional\components\notificationevents\...`
+
+A few things you'll need to update:
 
-### When New and When Updated Events are now separate
+Event Object method can now return any variables they want instead of just an `object` variable:
 
-NOTIFICATION EVENT BREAKING CHANGE: Only "When New" OR "When Updated" can be selected now, so we've migrated "When Updated" and you will have to duplicate and add a second notification for "When New".
+- `NotificationEvent::getEventObject()` => `NotificationEvent::getEventVariables()`
+- `NotificationEvent::getMockEventObject()` => `NotificationEvent::getMockEventVariables()`
 
-Code comment say that the Entry Save Notification Event
-// Does not match the scenario where a new entry is disabled
-// or where a new entry has a future publish date.
-Or have info message say "To capture the scenario where a publish date in the future automatically converts an entry to "live" without an event, you will need to set the
-email event to "none" and trigger those emails via a cron job that manually sends the appropriate email.
-Or just add this to the DOCS.
+Element-based Notification Events can lean on two helper classes to implement the Condition Builder:
 
-Changed Notification Event class names and broke out SaveUser and SaveEntry into TWO events, which both handle their event specific logic.
+- `BarrelStrength\Sprout\transactional\notificationevents\ElementEventInterface`
+- `BarrelStrength\Sprout\transactional\notificationevents\ElementEventTrait`
 
-- ENTRY When NEW and When UPDATED events
-- USER When NEW and When UPDATED events
+Any conditional logic that the Condition Builder can't handle should probably take place in the `NotificationEvent::matchNotificationEvent()` method. If this logic takes precedence over any other Condition Builder rules, you can hide rules you don't want to appear by implementing `ElementEventInterface::getExclusiveQueryParams()`. 
 
-### Send Method is retired. All emails will be sent as Lists.
+Reach out if you have any additional questions. A lot has changed here and these features are now leaning on a lot of more recent Craft 4 functionality that isn't widely documented.
 
-### Send Rules have been migrated to use Twig Expression Condition Rule
+#### Mailer settings columns have been changed to a JSON column
 
-Send Rule => Twig Expression Condition Rule
-And now instead of $emailType->getAdditionalTemplateVariables()
-it's just the $element that gets evaluated as the object variable.
-BREAKING CHANGE: If your custom Events use Send Rule for anything other
-than an Element that the event is triggered by, you'll need to move that
-logic into you custom event settings or handle it manually in the matchNotificationEvent
-method.
+Any custom email queries that touch these fields will need to now target the JSON blob stored in the `sprout_email.mailerInstructionsSettings` column:
 
-** Remove Send Rule and make it Twig Expression condition Rule
-** "Twig Expression is True". (may need to indicate what it does in the name)
-    can always just evaluate
+- `sprout_email.fromName` => `sprout_email.mailerInstructionsSettings.fromName`
+- `sprout_email.fromEmail` => `sprout_email.mailerInstructionsSettings.fromEmail`
+- `sprout_email.replyToEmail` => `sprout_email.mailerInstructionsSettings.replyToEmail`
+- `sprout_email.recipients` => `sprout_email.mailerInstructionsSettings.recipients`
 
-### On Save User Event handles Admin users differently
+### Audiences
 
-// On Save User Event: Only migrate admin setting if no $sectionIds are selected
-Need to manually create new event if you were sending to both admins and groups
-Or place your Admins in a group and send to that group too.
+Sprout Lists has been retired as a general list management plugin and Subscriber and Mailing List specific features have been rolled into Sprout's Mailer module. The Audience Element along with it's Audience Type establish the ruleset around how a given Audience is defined and managed.
 
-### Mailer settings columns have been changed to a JSON column
+#### Subscribers are now Craft Users
 
-Any custom email queries that touch these fields will need to now target JSON::mailerInstructionsSettings
-These Email field columns are deleted and moved to mailerInstructionsSettings
-'fromName' => $this->string(),
-'fromEmail' => $this->string(),
-'replyToEmail' => $this->string(),
-'recipients' => $this->text(),
+In Craft 3, the Sprout Lists Subscriber list included a Subscriber Element and allowed you to sync Subscribers with the Craft User Element.
 
-### Custom Notification Event
+In Craft 4, the Subscriber Element has been retired and Subscribers now default to non-credentialed Craft Users. Enabling the Subscriber List Audience Type adds layer on top of Craft Users which includes a Subscriber Lists field, Subscriber List Audience Type, and Subscriber List sources in the sources sidebar of the Users Element Index page.
 
-Custom Notification Events will need to update several things. See the base class for details.
+The only lists that will be migrated into Audiences are User Lists, where the Element ID referenced is a `craft\elements\User`. Any other uses of Lists need to be manually migrated. See the next section for some additional thoughts.
 
-- `getEventObject` => `getEventVariables`
-- `getMockEventObject` => `getMockEventVariables`
-- These methods can now return any variables they want instead of just an `object` variable
+Subscriber Lists now support settings around which User Statuses will trigger emails so be sure to review any Subscriber Lists and make sure that the settings fit your needs.
 
-If your custom Events use Send Rule for anything other
-than an Element that the event is triggered by, you'll need to move that
-logic into you custom event settings or handle it manually in the matchNotificationEvent
-method.
+#### Use the Data Set Audience Type for unconventional uses of Lists
 
-### Sprout Lists has been retired and replaced with the Audiences module
+As of the initial release, there is no upgrade path for migrating non-User Element Lists so you'll want to prepare a migration of any data in this category ahead of upgrading to Sprout.
 
-Sprout List Elements have been converted into AudienceElement
-Manually review them and confirm settings are what you want. New settings that don't match old now.
-Also, template updates needed => sprout.audiences.all() etc.
+The Sprout Lists plugin was a general purpose list plugin and allowed too much flexibility in allowing any Element to be defined as a List, often creating the potential for redundant data in place of just using a custom query and creating too many edge cases to support.
 
-### Subscriber Lists will only migrate User lists
+Sprout, moving forward will only be handling Mailing List use cases so any other lists should probably find a different upgrade path. Data Studio may provide you additional ways to query data that can be used in list-like ways.
 
-Lists will ONLY MIGRATE users
-Any other uses of Lists need to be manually migrated.
-Other uses should now be handled via Audiences and Data Sets and may require a custom module.
-Focus now on Subscriber List use case only and other use caess handled by Audience integrations.
-Removed 'elementId' => $this->integer()->notNull(), from Audience table. ID is now the only Element ID.
+The recommended approach for non-standard User-focused lists is to create a Custom Query Data Set that defines a query to retrieve the relevant data from your old list tables and use that to create a new Audience using the Data Set Audience Type. The Data Set Audience Type integration with Sprout's Data Studio module gives you the ability to create Audiences from custom queries, from wherever you manage your data.
 
-            Subscriber Lists now support settings around which User Statuses will trigger emails.
+For any front-end code allowing users to subscribe or unsubscribe from lists, see the new [Audiences](../audiences) documentation for details on how to update your Twig code.
 
 ### Framework
 

docs/updates/4.5.0-data-studio.md → docs/updates/4.46.0-data-studio.md

@@ -1,11 +1,11 @@
 ---
 date: 2023-09-02
-description: Upgrade Sprout Data Studio module 4.5.0
+description: Upgrade Sprout Data Studio module 4.46.0
 ---
 
-# Upgrading to Data Studio v4.5.0
+# Upgrading to Data Studio v4.46.0
 
-This release includes a breaking change if you are using Source Groups to group your Data Sets. Sprout provided a method to group Data Sets in Craft 3 and due to some inconsistencies with multi-site functionality we have decided to remove this from Craft 4, effective immediately, in favor of using the new Data Studio Global Field Layout and Craft's native Custom Sources. 
+This release includes a breaking change if you are using Source Groups to group your Data Sets. Sprout provided a method to group Data Sets in Craft 3 and due to some inconsistencies with multi-site functionality we have decided to remove this from Craft 4, effective immediately, in favor of using the Data Studio Global Field Layout and Craft's native Custom Sources.
 
 As plugin migrations should only touch schema controlled by the plugin itself, you will need to manually implement this change if you desire to group your Data Sets in the sidebar of the element index page. No Data Set settings are changed in this update aside from the group metadata.