Add adaptive guided tours to the new UI

src/Exceptionless.Core/Models/Data/ProductTourProgress.cs

@@ -0,0 +1,13 @@
+namespace Exceptionless.Core.Models.Data;
+
+public record ProductTourProgress
+{
+    public ProductTourStatus Status { get; set; }
+    public int Version { get; set; }
+}
+
+public enum ProductTourStatus
+{
+    Completed = 1,
+    Dismissed = 2
+}

src/Exceptionless.Core/Models/Data/ProductTours.cs

@@ -0,0 +1,103 @@
+using System.Collections.Frozen;
+using System.Runtime.Serialization;
+using System.Text.Json.Serialization;
+
+namespace Exceptionless.Core.Models.Data;
+
+public static class ProductTours
+{
+    public const string AppOverview = "app-overview";
+    public const string AppWelcome = "app-welcome";
+    public const string ExieAnnouncement = "exie-announcement";
+    public const string ExieOverview = "exie-overview";
+    public const string EventInvestigate = "event-investigate";
+    public const string ProjectConfigure = "project-configure";
+    public const string SavedViewCreate = "saved-view-create";
+
+    public static FrozenDictionary<string, ProductTourDefinition> Definitions { get; } = new[]
+    {
+        new ProductTourDefinition(AppOverview, 1, ProductTourKind.Guide),
+        new ProductTourDefinition(AppWelcome, 1, ProductTourKind.Prompt),
+        new ProductTourDefinition(ExieAnnouncement, 1, ProductTourKind.Prompt),
+        new ProductTourDefinition(ExieOverview, 1, ProductTourKind.Guide),
+        new ProductTourDefinition(EventInvestigate, 1, ProductTourKind.Guide),
+        new ProductTourDefinition(ProjectConfigure, 1, ProductTourKind.Guide),
+        new ProductTourDefinition(SavedViewCreate, 1, ProductTourKind.Guide)
+    }.ToFrozenDictionary(definition => definition.Name, StringComparer.Ordinal);
+
+    public static bool IsKnown(string name) => Definitions.ContainsKey(name);
+
+    public static bool IsValid(string name, int version)
+    {
+        return Definitions.TryGetValue(name, out var definition) && version > 0 && version <= definition.CurrentVersion;
+    }
+
+    public static string CreateTelemetrySource(
+        ProductTourTelemetryEvent telemetryEvent,
+        string tourName,
+        int version,
+        ProductTourLaunchSource launchSource)
+    {
+        return $"product-tour.{GetTelemetryName(telemetryEvent)}.{tourName}.v{version}.{GetLaunchSourceName(launchSource)}";
+    }
+
+    private static string GetTelemetryName(ProductTourTelemetryEvent telemetryEvent) => telemetryEvent switch
+    {
+        ProductTourTelemetryEvent.Completed => "completed",
+        ProductTourTelemetryEvent.Dismissed => "dismissed",
+        ProductTourTelemetryEvent.Shown => "shown",
+        ProductTourTelemetryEvent.Started => "started",
+        _ => throw new ArgumentOutOfRangeException(nameof(telemetryEvent), telemetryEvent, "Unknown product tour telemetry event.")
+    };
+
+    private static string GetLaunchSourceName(ProductTourLaunchSource launchSource) => launchSource switch
+    {
+        ProductTourLaunchSource.Welcome => "welcome",
+        ProductTourLaunchSource.Catalog => "catalog",
+        ProductTourLaunchSource.CommandPalette => "command-palette",
+        ProductTourLaunchSource.FeatureAnnouncement => "feature-announcement",
+        ProductTourLaunchSource.HelpMenu => "help-menu",
+        _ => throw new ArgumentOutOfRangeException(nameof(launchSource), launchSource, "Unknown product tour launch source.")
+    };
+}
+
+public sealed record ProductTourDefinition(string Name, int CurrentVersion, ProductTourKind Kind);
+
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum ProductTourKind
+{
+    [JsonStringEnumMemberName("guide")]
+    [EnumMember(Value = "guide")]
+    Guide,
+    [JsonStringEnumMemberName("prompt")]
+    [EnumMember(Value = "prompt")]
+    Prompt
+}
+
+public enum ProductTourTelemetryEvent
+{
+    Completed,
+    Dismissed,
+    Shown,
+    Started
+}
+
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum ProductTourLaunchSource
+{
+    [JsonStringEnumMemberName("welcome")]
+    [EnumMember(Value = "welcome")]
+    Welcome,
+    [JsonStringEnumMemberName("catalog")]
+    [EnumMember(Value = "catalog")]
+    Catalog,
+    [JsonStringEnumMemberName("command-palette")]
+    [EnumMember(Value = "command-palette")]
+    CommandPalette,
+    [JsonStringEnumMemberName("feature-announcement")]
+    [EnumMember(Value = "feature-announcement")]
+    FeatureAnnouncement,
+    [JsonStringEnumMemberName("help-menu")]
+    [EnumMember(Value = "help-menu")]
+    HelpMenu
+}

src/Exceptionless.Core/Models/User.cs

@@ -1,6 +1,7 @@
 using System.Collections.ObjectModel;
 using System.ComponentModel.DataAnnotations;
 using Exceptionless.Core.Attributes;
+using Exceptionless.Core.Models.Data;
 using Foundatio.Repositories.Models;
 
 namespace Exceptionless.Core.Models;
@@ -25,6 +26,7 @@ public record User : IIdentity, IHaveDates, IValidatableObject
     public ICollection<OAuthAccount> OAuthAccounts { get; init; } = new Collection<OAuthAccount>();
     public ICollection<UserOrganizationPreference> OrganizationPreferences { get; init; } = new Collection<UserOrganizationPreference>();
     public ICollection<UserSavedViewOrderPreference> SavedViewOrders { get; init; } = new Collection<UserSavedViewOrderPreference>();
+    public IDictionary<string, ProductTourProgress> ProductTours { get; init; } = new Dictionary<string, ProductTourProgress>(StringComparer.Ordinal);
 
     /// <summary>
     /// Gets or sets the users Full Name.

src/Exceptionless.Core/Repositories/EventRepository.cs

@@ -1,10 +1,12 @@
 using Elastic.Clients.Elasticsearch.QueryDsl;
 using Exceptionless.Core.Models;
+using Exceptionless.Core.Models.Data;
 using Exceptionless.Core.Repositories.Configuration;
 using Exceptionless.Core.Repositories.Queries;
 using Exceptionless.Core.Validation;
 using Exceptionless.DateTimeExtensions;
 using Foundatio.Repositories;
+using Foundatio.Repositories.Elasticsearch.Extensions;
 using Foundatio.Repositories.Models;
 
 namespace Exceptionless.Core.Repositories;
@@ -82,6 +84,85 @@ public Task<FindResults<PersistentEvent>> GetByReferenceIdAsync(string projectId
         return FindAsync(q => q.Project(projectId).FieldEquals(e => e.ReferenceId, referenceId).SortDescending(e => e.Date), o => o.PageLimit(10));
     }
 
+    public async Task<ProductTourUsageResult> GetProductTourUsageAsync(string projectId, DateTime? utcStart, DateTime utcEnd)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(projectId);
+        if (utcStart.HasValue && utcEnd <= utcStart)
+            throw new ArgumentOutOfRangeException(nameof(utcEnd), "The end date must be later than the start date.");
+
+        var sourcesByName = ProductTours.Definitions.Values
+            .SelectMany(definition => CreateProductTourSources(definition.Name, definition.CurrentVersion))
+            .ToDictionary(source => source.Raw, StringComparer.Ordinal);
+        string[] allSources = sourcesByName.Keys.ToArray();
+        string sourceField = InferField(ev => ev.Source);
+        string countField = InferField(ev => ev.Count);
+        string dateField = InferField(ev => ev.Date);
+        if (!utcStart.HasValue)
+        {
+            DateTime? retainedStart = _options.MaximumRetentionDays > 0
+                ? _timeProvider.GetUtcNow().UtcDateTime.SubtractDays(_options.MaximumRetentionDays)
+                : null;
+            var bounds = await CountAsync(query => ApplyProductTourUsageFilter(query, projectId, retainedStart, utcEnd, allSources)
+                .AggregationsExpression($"min:{dateField}"));
+            utcStart = bounds.Aggregations.Min<DateTime>($"min_{dateField}")?.Value;
+            if (!utcStart.HasValue)
+            {
+                return new ProductTourUsageResult([]);
+            }
+        }
+
+        var aggregation = await CountAsync(query => ApplyProductTourUsageFilter(query, projectId, utcStart, utcEnd, allSources)
+            .AggregationsExpression($"terms:({sourceField}~{allSources.Length} sum:{countField}~1 max:{dateField} date:({dateField} sum:{countField}~1))"));
+
+        var sourceBuckets = aggregation.Aggregations.Terms<string>($"terms_{sourceField}")?.Buckets ?? [];
+        var usage = sourceBuckets
+            .Select(bucket => sourcesByName.TryGetValue(bucket.Key, out var source)
+                ? new ProductTourUsageBucket(
+                    source,
+                    Convert.ToInt64(bucket.Aggregations.Sum($"sum_{countField}")?.Value ?? bucket.Total.GetValueOrDefault()),
+                    bucket.Aggregations.Max<DateTime>($"max_{dateField}")?.Value,
+                    (bucket.Aggregations.DateHistogram($"date_{dateField}")?.Buckets ?? [])
+                        .Where(period => period.Date < utcEnd)
+                        .Select(period => new ProductTourUsagePeriod(period.Date, Convert.ToInt64(period.Aggregations.Sum($"sum_{countField}")?.Value ?? period.Total.GetValueOrDefault())))
+                        .ToArray())
+                : null)
+            .OfType<ProductTourUsageBucket>()
+            .ToArray();
+        return new ProductTourUsageResult(usage);
+    }
+
+    private static IRepositoryQuery<PersistentEvent> ApplyProductTourUsageFilter(
+        IRepositoryQuery<PersistentEvent> query,
+        string projectId,
+        DateTime? utcStart,
+        DateTime utcEnd,
+        string[] sources)
+    {
+        query = query
+            .Project(projectId)
+            .FieldEquals(ev => ev.Type, Event.KnownTypes.FeatureUsage)
+            .FieldEquals(ev => ev.Source, sources)
+            .FieldLessThan(ev => ev.Date, utcEnd);
+
+        if (utcStart.HasValue)
+            return query.DateRange(utcStart, utcEnd, (PersistentEvent ev) => ev.Date).Index(utcStart, utcEnd);
+
+        return query.DateRange(null, utcEnd, (PersistentEvent ev) => ev.Date);
+    }
+
+    private static ProductTourUsageSource[] CreateProductTourSources(string tourName, int currentVersion)
+    {
+        return Enumerable.Range(1, currentVersion)
+            .SelectMany(version => Enum.GetValues<ProductTourTelemetryEvent>().SelectMany(telemetryEvent => Enum.GetValues<ProductTourLaunchSource>().Select(launchSource =>
+                new ProductTourUsageSource(
+                    ProductTours.CreateTelemetrySource(telemetryEvent, tourName, version, launchSource),
+                    telemetryEvent,
+                    tourName,
+                    version,
+                    launchSource))))
+            .ToArray();
+    }
+
     public async Task<PreviousAndNextEventIdResult> GetPreviousAndNextEventIdsAsync(PersistentEvent ev, AppFilter? systemFilter = null, DateTime? utcStart = null, DateTime? utcEnd = null)
     {
         var previous = GetPreviousEventIdAsync(ev, systemFilter, utcStart, utcEnd);

src/Exceptionless.Core/Repositories/Interfaces/IEventRepository.cs

@@ -13,6 +13,7 @@ public interface IEventRepository : IRepositoryOwnedByOrganizationAndProject<Per
     Task<bool> UpdateSessionStartLastActivityAsync(string id, DateTime lastActivityUtc, bool isSessionEnd = false, bool hasError = false, bool sendNotifications = true);
     Task<long> RemoveAllAsync(string organizationId, string? clientIpAddress, DateTime? utcStart, DateTime? utcEnd, CommandOptionsDescriptor<PersistentEvent>? options = null);
     Task<long> RemoveAllByStackIdsAsync(string[] stackIds);
+    Task<ProductTourUsageResult> GetProductTourUsageAsync(string projectId, DateTime? utcStart, DateTime utcEnd);
 }
 
 public static class EventRepositoryExtensions

src/Exceptionless.Core/Repositories/Interfaces/IUserRepository.cs

@@ -1,4 +1,5 @@
 using Exceptionless.Core.Models;
+using Exceptionless.Core.Models.Data;
 using Foundatio.Repositories;
 using Foundatio.Repositories.Models;
 
@@ -12,4 +13,5 @@ public interface IUserRepository : ISearchableRepository<User>
     Task<User?> GetUserByOAuthProviderAsync(string provider, string providerUserId);
     Task<User?> GetByVerifyEmailAddressTokenAsync(string token);
     Task<FindResults<User>> GetByOrganizationIdAsync(string organizationId, CommandOptionsDescriptor<User>? options = null);
+    Task<ProductTourProgress> UpdateProductTourProgressAsync(string userId, string tourName, ProductTourProgress progress);
 }

src/Exceptionless.Core/Repositories/ProductTourUsageResult.cs

@@ -0,0 +1,16 @@
+using Exceptionless.Core.Models.Data;
+
+namespace Exceptionless.Core.Repositories;
+
+public sealed record ProductTourUsageResult(IReadOnlyCollection<ProductTourUsageBucket> Buckets);
+
+public sealed record ProductTourUsageBucket(ProductTourUsageSource Source, long Count, DateTime? LastUtc, IReadOnlyCollection<ProductTourUsagePeriod> Activity);
+
+public sealed record ProductTourUsagePeriod(DateTime DateUtc, long Count);
+
+public sealed record ProductTourUsageSource(
+    string Raw,
+    ProductTourTelemetryEvent Event,
+    string TourName,
+    int Version,
+    ProductTourLaunchSource LaunchSource);

src/Exceptionless.Core/Repositories/UserRepository.cs

@@ -1,7 +1,9 @@
 using Exceptionless.Core.Extensions;
+using Exceptionless.Core.Models.Data;
 using Exceptionless.Core.Repositories.Configuration;
 using Exceptionless.Core.Validation;
 using Foundatio.Repositories;
+using Foundatio.Repositories.Exceptions;
 using Foundatio.Repositories.Models;
 using Foundatio.Repositories.Options;
 using User = Exceptionless.Core.Models.User;
@@ -78,6 +80,41 @@ public Task<FindResults<User>> GetByOrganizationIdAsync(string organizationId, C
         return FindAsync(q => q.FieldEquals(u => u.OrganizationIds, organizationId).SortAscending(u => u.EmailAddress), o => commandOptions);
     }
 
+    public async Task<ProductTourProgress> UpdateProductTourProgressAsync(string userId, string tourName, ProductTourProgress progress)
+    {
+        const string script = """
+            if (ctx._source.product_tours == null) {
+              ctx._source.product_tours = [:];
+            }
+
+            def current = ctx._source.product_tours[params.tourName];
+            if (current != null && (current.version > params.version ||
+                (current.version == params.version && (current.status == params.completedStatus || current.status == params.status)))) {
+              ctx.op = 'none';
+            } else {
+              ctx._source.product_tours[params.tourName] = ['status': params.status, 'version': params.version];
+            }
+            """;
+        var patch = new ScriptPatch(script.TrimScript())
+        {
+            Params = new Dictionary<string, object>
+            {
+                ["completedStatus"] = (int)ProductTourStatus.Completed,
+                ["status"] = (int)progress.Status,
+                ["tourName"] = tourName,
+                ["version"] = progress.Version
+            }
+        };
+
+        await PatchAsync(userId, patch, options => options.Cache());
+
+        var user = await GetByIdAsync(userId, options => options.Cache(false));
+        if (user is null || !user.ProductTours.TryGetValue(tourName, out var storedProgress))
+            throw new DocumentNotFoundException(userId);
+
+        return storedProgress;
+    }
+
     protected override async Task AddDocumentsToCacheAsync(ICollection<FindHit<User>> findHits, ICommandOptions options, bool isDirtyRead)
     {
         await base.AddDocumentsToCacheAsync(findHits, options, isDirtyRead);

src/Exceptionless.Web/Api/Endpoints/AdminEndpoints.cs

@@ -87,6 +87,15 @@ public static IEndpointRouteBuilder MapAdminEndpoints(this IEndpointRouteBuilder
             .Produces(StatusCodes.Status401Unauthorized)
             .Produces(StatusCodes.Status403Forbidden);
 
+        endpoints.MapGet("api/v2/admin/product-tour-usage", GetProductTourUsageAsync)
+            .RequireAuthorization(AuthorizationRoles.GlobalAdminPolicy)
+            .AddEndpointFilter<AutoValidationEndpointFilter>()
+            .Produces<ProductTourUsageResponse>(StatusCodes.Status200OK)
+            .ProducesProblem(StatusCodes.Status400BadRequest)
+            .ProducesValidationProblem(StatusCodes.Status422UnprocessableEntity)
+            .Produces(StatusCodes.Status401Unauthorized)
+            .Produces(StatusCodes.Status403Forbidden);
+
         group.MapPost("change-plan", async (HttpContext httpContext, IMediator mediator, IMediatorResultMapper<HttpIResult> resultMapper, string organizationId, string planId)
             => (await mediator.InvokeAsync<Result<object>>(new AdminChangePlan(organizationId, planId, httpContext))).ToHttpResult(resultMapper));
 
@@ -130,4 +139,11 @@ private static EventSubmissionSettings CreateEventSubmissionSettings(bool? enabl
         bool configuredEnabled = !appOptions.EventSubmissionDisabled;
         return new EventSubmissionSettings(enabledOverride ?? configuredEnabled, configuredEnabled, enabledOverride.HasValue);
     }
+
+    private static async Task<HttpIResult> GetProductTourUsageAsync(
+        IMediator mediator,
+        IMediatorResultMapper<HttpIResult> resultMapper,
+        DateTime? start = null,
+        DateTime? end = null)
+        => (await mediator.InvokeAsync<Result<object>>(new GetAdminProductTourUsage(start, end))).ToHttpResult(resultMapper);
 }

src/Exceptionless.Web/Api/Endpoints/UserEndpoints.cs

@@ -1,4 +1,5 @@
 using Exceptionless.Core.Authorization;
+using Exceptionless.Core.Models.Data;
 using Exceptionless.Core.Extensions;
 using Exceptionless.Web.Api.Filters;
 using Exceptionless.Web.Api.Infrastructure;
@@ -37,6 +38,27 @@ public static IEndpointRouteBuilder MapUserEndpoints(this IEndpointRouteBuilder
             }
         });
 
+        group.MapPut("users/me/product-tours/{tourName:regex(^[a-z0-9]+(?:-[a-z0-9]+)*$):maxlength(64)}", async (string tourName, IMediator mediator, IMediatorResultMapper<HttpIResult> resultMapper, [FromBody] UpdateProductTourProgress progress)
+            => (await mediator.InvokeAsync<Result<ProductTourProgress>>(new UserMessages.UpdateCurrentUserProductTour(tourName, progress))).ToHttpResult(resultMapper))
+        .Accepts<UpdateProductTourProgress>(false, "application/json")
+        .Produces<ProductTourProgress>()
+        .ProducesProblem(StatusCodes.Status400BadRequest)
+        .ProducesProblem(StatusCodes.Status422UnprocessableEntity)
+        .ProducesProblem(StatusCodes.Status404NotFound)
+        .WithSummary("Update current user product tour progress")
+        .WithMetadata(new EndpointDocumentation {
+            RequestBodyDescription = "The versioned product tour outcome.",
+            RequestBodyRequired = true,
+            ParameterDescriptions = new() {
+                ["tourName"] = "The stable product tour name.",
+            },
+            ResponseDescriptions = new() {
+                ["400"] = "The request body is missing or malformed.",
+                ["422"] = "The product tour progress is invalid.",
+                ["404"] = "The current user could not be found.",
+            }
+        });
+
         group.MapGet("users/me/oauth-grants", async (IMediator mediator, IMediatorResultMapper<HttpIResult> resultMapper)
             => (await mediator.InvokeAsync<Result<IReadOnlyCollection<ViewOAuthGrant>>>(new UserMessages.GetCurrentUserOAuthGrants())).ToHttpResult(resultMapper))
         .Produces<IReadOnlyCollection<ViewOAuthGrant>>()