Update SQL requirements & Code overloads

Author: cornehoskam

17/umbraco-engage/developers/personalization/custom-scoring.md

@@ -14,7 +14,11 @@ This might be difficult to accomplish through the Content Scoring UI in Umbraco,
 
 To manage scoring for personas, we need to get a reference to `IPersonaService`. For the customer journey, we will need the `ICustomerJourneyService`. Both services can be found under the namespace `Umbraco.Engage.Infrastructure.Personalization.Services`.
 
-To implement our example above, we will be using the `ICustomerJourneyService`. To modify the customer journey step scoring, we need to know the ID of the step we are trying to score. For your implementation you could hardcode the IDs (since they are unlikely to change), we can also fetch them by name through the `ICustomerJourneyGroupRepository`.
+Both services support two ways to identify entities:
+- **Numeric IDs** (e.g., `personaId`, `customerJourneyStepId`) - Legacy approach using database IDs
+- **GUID Keys** (e.g., `personaKey`, `stepKey`) - Preferred approach using Umbraco's GUID-based identifiers
+
+To implement our example above, we will be using the `ICustomerJourneyService`. To modify the customer journey step scoring, we need to know the ID or Key of the step we are trying to score. For your implementation you could hardcode the IDs/Keys (since they are unlikely to change), we can also fetch them by name through the `ICustomerJourneyGroupRepository`.
 
 To resolve the required services, we will use Dependency Injection:
 
@@ -46,23 +50,28 @@ var stepDo = customerJourneyGroup.Steps.FirstOrDefault(step => step.Title == "Do
 ```
 {% endcode %}
 
-We can now inspect the step **Do** variable and find its `ID`. To score the step, we provide the `ID` and the score to the `CustomerJourneyService`:
+We can now inspect the step **Do** variable and find its `Id` or `Key`. To score the step, we provide either the numeric ID or GUID Key and the score to the `CustomerJourneyService`:
 
 ```csharp
+// Using numeric ID (legacy approach)
 _customerJourneyService.ScoreCustomerJourneyStep(stepDo.Id, 100);
+
+// Using GUID Key (preferred approach)
+_customerJourneyService.ScoreCustomerJourneyStep(stepDo.Key, 100);
 ```
 
 We have now added a **score of 100** to the Customer Journey step "**Do**". It is also possible to add negative scores. In our example, we can decrease the scores for "**See**" and "**Think**".
 
 Since the user is no longer (shifting away) from that step of the Customer Journey the implementation strategy is the same for personas.
 
-Another, more advanced, example could be on how to reset the score of a persona for a given visitor. We can use the same approach as above to fetch the **persona** instead of the Customer Journey for the current visitor. We can get the visitor's current score based on the Persona ID, and subtract that exact score from said visitor.
+Another, more advanced, example could be on how to reset the score of a persona for a given visitor. We can use the same approach as above to fetch the **persona** instead of the Customer Journey for the current visitor. We can get the visitor's current score based on the Persona ID or Key, and subtract that exact score from said visitor.
 
 {% hint style="info" %}
 When scoring outside of a regular HttpContext request (e.g., in background jobs or external integrations), you must use the overload that includes `PersonalizationScoreType`. The `PersonalizationScoreType` enum specifies whether the score is `Implicit` (behavior-based) or `Explicit` (direct assignment).
 {% endhint %}
 
 ```csharp
+// Using numeric ID
 public IActionResult ResetPersonaScoreToZero(long personaId)
 {
     var visitorId = _visitorContext.GetVisitorExternalId();
@@ -81,8 +90,48 @@ public IActionResult ResetPersonaScoreToZero(long personaId)
 
     return Ok("OK");
 }
+
+// Using GUID Key (preferred approach)
+public IActionResult ResetPersonaScoreToZero(Guid personaKey)
+{
+    var visitorId = _visitorContext.GetVisitorExternalId();
+
+    if (visitorId.HasValue)
+    {
+        var personaGroups = _personaGroupRepository.GetPersonaScoresByVisitor(visitorId.Value);
+        var personaGroup = personaGroups.FirstOrDefault(x => x.Personas.Any(y => y.Key == personaKey));
+        var persona = personaGroup?.Personas.FirstOrDefault(x => x.Key == personaKey);
+        if (persona != null)
+        {
+            _personaService.ScorePersona(visitorId.Value, personaKey, persona.Score * -1, PersonalizationScoreType.Explicit);
+            return Ok($"Subtracted {persona.Score} from visitor {visitorId}");
+        }
+    }
+
+    return Ok("OK");
+}
 ```
 
 {% hint style="info" %}
-The simpler overloads `ScorePersona(long personaId, int score)` and `ScoreCustomerJourneyStep(long customerJourneyStepId, int score)` should only be used within the context of a regular HttpContext request, as they automatically resolve the current visitor.
+The simpler overloads `ScorePersona(long personaId, int score)`, `ScorePersona(Guid personaKey, int score)`, `ScoreCustomerJourneyStep(long customerJourneyStepId, int score)`, and `ScoreCustomerJourneyStep(Guid stepKey, int score)` should only be used within the context of a regular HttpContext request, as they automatically resolve the current visitor.
 {% endhint %}
+
+## Available Method Overloads
+
+### IPersonaService
+
+| Method | Parameters | Use Case |
+|--------|------------|----------|
+| `ScorePersona` | `(long personaId, int score)` | Within HttpContext, using numeric ID |
+| `ScorePersona` | `(Guid personaKey, int score)` | Within HttpContext, using GUID key (preferred) |
+| `ScorePersona` | `(Guid visitorExternalId, long personaId, int score, PersonalizationScoreType scoreType)` | Outside HttpContext, using numeric ID |
+| `ScorePersona` | `(Guid visitorExternalId, Guid personaKey, int score, PersonalizationScoreType scoreType)` | Outside HttpContext, using GUID key (preferred) |
+
+### ICustomerJourneyService
+
+| Method | Parameters | Use Case |
+|--------|------------|----------|
+| `ScoreCustomerJourneyStep` | `(long customerJourneyStepId, int score)` | Within HttpContext, using numeric ID |
+| `ScoreCustomerJourneyStep` | `(Guid stepKey, int score)` | Within HttpContext, using GUID key (preferred) |
+| `ScoreCustomerJourneyStep` | `(Guid visitorExternalId, long customerJourneyStepId, int score, PersonalizationScoreType scoreType)` | Outside HttpContext, using numeric ID |
+| `ScoreCustomerJourneyStep` | `(Guid visitorExternalId, Guid stepKey, int score, PersonalizationScoreType scoreType)` | Outside HttpContext, using GUID key (preferred) |

17/umbraco-engage/developers/settings/custom-goals-scoring.md

@@ -20,7 +20,12 @@ Creating the goal is similar to creating a page view or page event goal. The **g
 
 ## Trigger goal in C\#
 
-To trigger the goal, execute C# code during the visitor's pageview. Inject `Umbraco.Engage.Infrastructure.Analytics.Goals.IGoalService`, which has a `TriggerGoal(long goalId, int value)` method. An implementation looks like:
+To trigger the goal, execute C# code during the visitor's pageview. Inject `Umbraco.Engage.Infrastructure.Analytics.Goals.IGoalService`, which provides multiple overloads to trigger goals:
+
+- `TriggerGoal(long goalId, int value)` - Using numeric ID
+- `TriggerGoal(Guid goalKey, int value)` - Using GUID key (preferred)
+
+An implementation looks like:
 
 ```cs
 using Umbraco.Engage.Infrastructure.Analytics.Goals;
@@ -31,11 +36,17 @@ public class YourService
 
     public YourService(IGoalService goalService) => _goalService = goalService;
 
-    public void TriggerGoal()
+    public void TriggerGoalById()
     {
-        // Use the goalId from the code snippet above
+        // Using numeric ID (legacy approach)
         _goalService.TriggerGoal(goalId: 37, value: 42);
     }
+
+    public void TriggerGoalByKey()
+    {
+        // Using GUID key (preferred approach)
+        _goalService.TriggerGoal(goalKey: new Guid("a1b2c3d4-e5f6-7890-abcd-ef1234567890"), value: 42);
+    }
 }
 ```
 
@@ -48,7 +59,20 @@ To trigger a goal outside of an HTTP request or a valid pageview, use the overlo
 Retrieve the pageview GUID in the original request using `Umbraco.Engage.Infrastructure.Analytics.Common.IPageviewGuidManager.GetPageviewGuid()`. You will need to store this pageview GUID for later use when invoking:
 
 ```cs
+// Using numeric goal ID
 _goalService.TriggerGoal(pageviewGuid, goalId, value);
+
+// Using GUID goal key (preferred)
+_goalService.TriggerGoal(pageviewGuid, goalKey, value);
 ```
 
 This custom goal can now be used like other goals and will show up in any statistics related to goals.
+
+## Available Method Overloads
+
+| Method | Parameters | Use Case |
+|--------|------------|----------|
+| `TriggerGoal` | `(long goalId, int value = 0)` | Within HttpContext/pageview, using numeric ID |
+| `TriggerGoal` | `(Guid goalKey, int value = 0)` | Within HttpContext/pageview, using GUID key (preferred) |
+| `TriggerGoal` | `(Guid pageviewGuid, long goalId, int value = 0)` | Outside HttpContext, using numeric ID |
+| `TriggerGoal` | `(Guid pageviewGuid, Guid goalKey, int value = 0)` | Outside HttpContext, using GUID key (preferred) |

17/umbraco-engage/getting-started/for-developers/infrastructure-sizing.md

@@ -24,9 +24,13 @@ Due to the wide variety of cloud providers, we recommend using the appropriate s
 
 ### **Microsoft Azure**
 
-For Azure SQL, use at least a S3 instance with 100 Data Transport Utility (DTU).
+For Azure SQL, use at least a **S3 tier (100 DTUs)** or higher.
 
-Umbraco Engage depends on features that aren’t available in the lower tiers and will fail to boot if they are used.
+{% hint style="warning" %}
+Umbraco Engage requires **columnstore index support** for optimal performance. Azure SQL tiers lower than S3 (such as S0, S1, S2) do not support **creating** columnstore indexes. The initial installation will fail on these lower tiers.
+
+**Workaround:** You can temporarily scale up to S3 for the initial installation, then scale back down. Lower tiers can still **query** columnstore indexes once created. However, this configuration is not recommended for production due to potential performance issues. See [Troubleshooting Installations](troubleshooting-installations.md) for details.
+{% endhint %}
 
 ## Non-cloud
 

17/umbraco-engage/getting-started/for-developers/system-requirements.md

@@ -8,16 +8,41 @@ Umbraco Engage has the following requirements:
 
 * Umbraco version 17
 * .NET 10.0
-* SQL Server 2014+, LocalDB, or Azure SQL.
+* SQL Server 2014+, LocalDB, or Azure SQL
   * **SQL CE & SQLite are not supported.**
 
 {% hint style="info" %}
 It is recommended to upgrade your Umbraco installation to the latest version of Umbraco 17.
 {% endhint %}
 
+## Database Requirements
+
+Umbraco Engage uses **columnstore indexes** for optimal query performance on analytics data. This has implications for your database choice:
+
+### SQL Server (On-Premises / Self-Hosted)
+
+* **SQL Server 2014 or higher** is required
+* Columnstore index support varies by edition - Enterprise Edition is recommended for older SQL Server versions
+
+### Azure SQL
+
+* **S3 tier (100 DTUs) or higher** is required to **create** columnstore indexes during installation
+* Lower tiers (S0, S1, S2) can **query** existing columnstore indexes but cannot create them
+* See [Infrastructure Sizing](infrastructure-sizing.md) for detailed Azure SQL recommendations
+
+{% hint style="warning" %}
+If you attempt to install Umbraco Engage on an Azure SQL tier lower than S3, the initial migration will fail. See [Troubleshooting Installations](troubleshooting-installations.md) for workarounds.
+{% endhint %}
+
+### LocalDB
+
+LocalDB supports columnstore indexes and can be used for local development.
+
 See the [Troubleshooting](../../installation/troubleshooting-installs.md) section if you need to upgrade from SQL CE to SQL Server.
 
-Umbraco Engage is compatible with Umbraco Cloud (Standard, Professional and Enterprise plan). 
+## Umbraco Cloud Compatibility
+
+Umbraco Engage is compatible with Umbraco Cloud (Standard, Professional and Enterprise plan).
 
 {% hint style="info" %}
 If you want to run an Umbraco Cloud site locally, point the connection string to a (local) SQL Server database. SQLite is not supported.

17/umbraco-engage/getting-started/for-developers/troubleshooting-installations.md

@@ -15,8 +15,8 @@ After installing Umbraco Engage and booting for the first time, an SQL exception
 The most common reasons for this are:
 
 * Database connectivity issues.
-* Incompatible SQL Server version.
-* No columnstore index support on Azure SQL lower than S3.
+* Incompatible SQL Server version or edition (columnstore index support required).
+* No columnstore index support on Azure SQL tiers lower than S3 (S0, S1, S2).
 
 ### Exception
 
@@ -58,3 +58,9 @@ Azure SQL lower than S3 doesn't support creating columnstore indexes. To work ar
 3. Scale back to your initial Azure SQL tier.
 
 The columnstore indexes are created and can be used in a lower tier.
+
+#### When running on an incompatible SQL Server version or edition
+
+SQL Server 2014 or higher is required. Columnstore index support varies by SQL Server version and edition. If you encounter issues, consider upgrading to a newer SQL Server version or using Enterprise Edition.
+
+See [System Requirements](system-requirements.md) for the full list of supported database configurations.