Add criteria to split name into first, middle, and last. (#302)

* Add criteria to split name into first, middle, and last.

* Create unit test to retrieve person data

* Move the name components to its own type.

* Improve the party lookup and cache mechanism

* Use a type instead of object

* Code refactoring

* Use HasFlag instead of equality checking

* Make PersonNameComponents immutable.

* Use simple data type to build test data for party lookup with name component

* Cache the entire result

* Move the includeComponents to be a query parameter

* Code refactoring

* Rebuild a unit test to test name components

* Use IsNullOrEmpty to simulate the actual logic

* Use the array initializer syntax

* Remove single spaces

* Use descriptive values for the query parameter

* Implement a new unit test to validate the handling of invalid query parameter values.

* Enhance the logic to enable users to retrieve a person's name using a parameter with meaningful semantics

* Delegate the actual filtering logic to the Apply method

* Remove unnecessary "Organisation" property

* Rename PartyComponentOption to PartyComponentOptions

* Use the fully qualified name

* Remove a test case

* Improve the XML documentation

* Initialize the non-nullable field

* Code refactoring

* Code refactoring

Author: Ahmed-Ghanam

src/Altinn.Platform.Models/src/Altinn.Platform.Models/Register/PartyComponentOptions.cs

@@ -0,0 +1,18 @@
+namespace Altinn.Platform.Register.Models;
+
+/// <summary>
+/// Specifies the components that should be included when retrieving party's information.
+/// </summary>
+[Flags]
+public enum PartyComponentOptions : uint
+{
+    /// <summary>
+    /// No additional components are included.
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    /// Includes the party's first name, middle name, and last name.
+    /// </summary>
+    NameComponents = 1 << 0,
+}

src/Altinn.Platform.Models/src/Altinn.Platform.Models/Register/PartyLookup.cs

@@ -7,7 +7,7 @@ namespace Altinn.Platform.Register.Models;
 /// Represents a lookup criteria when looking for a Party. Only one of the properties can be used at a time.
 /// If none or more than one property have a value the lookup operation will respond with bad request.
 /// </summary>
-public record PartyLookup 
+public record PartyLookup
     : IValidatableObject
 {
     /// <summary>

src/Altinn.Platform.Models/src/Altinn.Platform.Models/Register/PartyName.cs

@@ -20,8 +20,15 @@ public record PartyName
     public string? OrgNo { get; set; }
 
     /// <summary>
-    /// Gets or sets the party name for this result
+    /// Gets or sets the party name for this result.
     /// </summary>
     [JsonPropertyName("name")]
     public string? Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the components of a person's name for this result.
+    /// </summary>
+    [JsonPropertyName("personName")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public PersonNameComponents? PersonName { get; set; }
 }

src/Altinn.Platform.Models/src/Altinn.Platform.Models/Register/PersonNameComponents.cs

@@ -0,0 +1,27 @@
+using System.Text.Json.Serialization;
+
+namespace Altinn.Platform.Register.Models;
+
+/// <summary>
+/// Represents the components of a person's name.
+/// </summary>
+public record PersonNameComponents
+{
+    /// <summary>
+    /// Gets or sets the first name.
+    /// </summary>
+    [JsonPropertyName("firstName")]
+    public string? FirstName { get; init; }
+
+    /// <summary>
+    /// Gets or sets the middle name.
+    /// </summary>
+    [JsonPropertyName("middleName")]
+    public string? MiddleName { get; init; }
+
+    /// <summary>
+    /// Gets or sets the sure name.
+    /// </summary>
+    [JsonPropertyName("lastName")]
+    public string? LastName { get; init; }
+}

src/Altinn.Register/src/Altinn.Register.Core/Parties/IV1PartyService.cs

@@ -1,4 +1,6 @@
-using V1Models = Altinn.Platform.Register.Models;
+using Altinn.Platform.Register.Models;
+
+using V1Models = Altinn.Platform.Register.Models;
 
 namespace Altinn.Register.Core.Parties;
 
@@ -40,12 +42,13 @@ public interface IV1PartyService
     IAsyncEnumerable<V1Models.Party> LookupPartiesBySSNOrOrgNos(IEnumerable<string> lookupValues, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Lookup party names by social security number organization number.
+    /// Lookup party names by social security number or organization number.
     /// </summary>
     /// <param name="lookupValues">The set of ssn/org.nr.</param>
+    /// <param name="partyComponentOption">Specifies the components that should be included when retrieving party's information.</param>
     /// <param name="cancellationToken">The cancellation token.</param>
     /// <returns>An async enumerable of <see cref="V1Models.PartyName"/>.</returns>
-    IAsyncEnumerable<V1Models.PartyName> LookupPartyNames(IEnumerable<V1Models.PartyLookup> lookupValues, CancellationToken cancellationToken = default);
+    IAsyncEnumerable<V1Models.PartyName> LookupPartyNames(IEnumerable<PartyLookup> lookupValues, PartyComponentOptions partyComponentOption, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Get parties by party ids.

src/Altinn.Register/src/Altinn.Register/ApiDescriptions/PartyComponentOptionSchemaFilter.cs

@@ -0,0 +1,29 @@
+using Altinn.Platform.Register.Models;
+using Altinn.Register.ModelBinding;
+
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Models;
+
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Altinn.Register.ApiDescriptions;
+
+/// <summary>
+/// Schema filter for <see cref="PartyComponentOptions"/>.
+/// </summary>
+public sealed class PartyComponentOptionSchemaFilter
+    : SchemaFilter<PartyComponentOptions>
+{
+    /// <inheritdoc/>
+    protected override void Apply(OpenApiSchema schema, SchemaFilterContext context)
+    {
+        schema.Enum = null;
+        schema.Format = null;
+        schema.Type = "array";
+        schema.Items = new OpenApiSchema
+        {
+            Type = "string",
+            Enum = PartyComponentOptionModelBinder.AllowedValues.Select(v => (IOpenApiAny)new OpenApiString(v)).ToList(),
+        };
+    }
+}

src/Altinn.Register/src/Altinn.Register/ApiDescriptions/SchemaFilter.cs

@@ -0,0 +1,35 @@
+using CommunityToolkit.Diagnostics;
+
+using Microsoft.OpenApi.Models;
+
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Altinn.Register.ApiDescriptions;
+
+/// <summary>
+/// Base class for schema filters that affect a specific type.
+/// </summary>
+/// <typeparam name="T">The type this schema filter affects.</typeparam>
+public abstract class SchemaFilter<T> : ISchemaFilter
+{
+    /// <inheritdoc/>
+    void ISchemaFilter.Apply(OpenApiSchema schema, SchemaFilterContext context)
+    {
+        Guard.IsNotNull(schema);
+        Guard.IsNotNull(context);
+
+        if (context.Type != typeof(T))
+        {
+            return;
+        }
+
+        Apply(schema, context);
+    }
+
+    /// <summary>
+    /// Applies the schema filter to the given schema if the context type matches the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <param name="schema">The schema to apply the filter to.</param>
+    /// <param name="context">The context in which the schema is being applied.</param>
+    protected abstract void Apply(OpenApiSchema schema, SchemaFilterContext context);
+}

src/Altinn.Register/src/Altinn.Register/Clients/PartiesClient.cs

@@ -4,13 +4,16 @@
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.Json;
+
 using Altinn.Platform.Register.Models;
 using Altinn.Register.Configuration;
 using Altinn.Register.Core.Parties;
 using Altinn.Register.Core.Utils;
 using Altinn.Register.Extensions;
+
 using Microsoft.Extensions.Caching.Memory;
 using Microsoft.Extensions.Options;
+
 using V1Models = Altinn.Platform.Register.Models;
 
 namespace Altinn.Register.Clients;
@@ -199,9 +202,9 @@ public PartiesClient(HttpClient httpClient, IOptions<GeneralSettings> generalSet
         => GetPartiesById(partyIds, fetchSubUnits: false, cancellationToken);
 
     /// <inheritdoc />
-    public IAsyncEnumerable<PartyName> LookupPartyNames(IEnumerable<PartyLookup> lookupValues, CancellationToken cancellationToken = default)
+    public IAsyncEnumerable<PartyName> LookupPartyNames(IEnumerable<PartyLookup> lookupValues, PartyComponentOptions partyComponentOption, CancellationToken cancellationToken = default)
     {
-        return RunInParallel(lookupValues, ProcessPartyLookupAsync, cancellationToken);
+        return RunInParallel(lookupValues, partyComponentOption, ProcessPartyLookupAsync, cancellationToken);
     }
 
     /// <inheritdoc />
@@ -230,24 +233,30 @@ public IAsyncEnumerable<PartyName> LookupPartyNames(IEnumerable<PartyLookup> loo
         _logger.LogError("Getting parties information from bridge failed with {StatusCode}", response.StatusCode);
     }
 
-    private async Task<PartyName> ProcessPartyLookupAsync(PartyLookup partyLookup, CancellationToken cancellationToken)
+    private async Task<PartyName> ProcessPartyLookupAsync(PartyLookup partyLookup, PartyComponentOptions partyComponentOption, CancellationToken cancellationToken)
     {
         Debug.Assert(!string.IsNullOrEmpty(partyLookup.Ssn) || !string.IsNullOrEmpty(partyLookup.OrgNo));
+
         string lookupValue = !string.IsNullOrEmpty(partyLookup.Ssn) ? partyLookup.Ssn : partyLookup.OrgNo!;
+
         string cacheKey = $"n:{lookupValue}";
-        string? partyName = await GetOrAddPartyNameToCacheAsync(lookupValue, cacheKey, cancellationToken);
+
+        PartyName? partyName = await GetOrAddPartyNameToCacheAsync(lookupValue, cacheKey, cancellationToken);
+
+        bool includePersonName = partyComponentOption.HasFlag(PartyComponentOptions.NameComponents);
 
         return new PartyName
         {
             Ssn = partyLookup.Ssn,
             OrgNo = partyLookup.OrgNo,
-            Name = partyName,
+            Name = partyName?.Name,
+            PersonName = includePersonName ? partyName?.PersonName : null
         };
     }
 
-    private async Task<string?> GetOrAddPartyNameToCacheAsync(string lookupValue, string cacheKey, CancellationToken cancellationToken)
+    private async Task<PartyName?> GetOrAddPartyNameToCacheAsync(string lookupValue, string cacheKey, CancellationToken cancellationToken)
     {
-        if (_memoryCache.TryGetValue(cacheKey, out string? partyName)
+        if (_memoryCache.TryGetValue(cacheKey, out PartyName? partyName)
             && partyName is not null)
         {
             return partyName;
@@ -268,19 +277,34 @@ private async Task<PartyName> ProcessPartyLookupAsync(PartyLookup partyLookup, C
 
         if (party != null)
         {
-            partyName = party.Name;
-            _memoryCache.Set(cacheKey, party.Name, new TimeSpan(0, _cacheTimeoutForPartyNames, 0));
+            partyName = new PartyName()
+            {
+                Name = party.Name
+            };
+
+            if (party.Person != null)
+            {
+                partyName.PersonName = new()
+                {
+                    LastName = party.Person.LastName,
+                    FirstName = party.Person.FirstName,
+                    MiddleName = party.Person.MiddleName
+                };
+            }
+
+            _memoryCache.Set(cacheKey, partyName, new TimeSpan(0, _cacheTimeoutForPartyNames, 0));
         }
 
         return partyName;
     }
 
     private static async IAsyncEnumerable<TResult> RunInParallel<TIn, TResult>(
         IEnumerable<TIn> input,
-        Func<TIn, CancellationToken, Task<TResult>> func,
+        PartyComponentOptions partyComponentOption,
+        Func<TIn, PartyComponentOptions, CancellationToken, Task<TResult>> func,
         [EnumeratorCancellation] CancellationToken cancellationToken)
     {
-        var tasks = input.Select(i => func(i, cancellationToken)).ToList();
+        var tasks = input.Select(i => func(i, partyComponentOption, cancellationToken)).ToList();
 
         while (tasks.Count > 0)
         {

src/Altinn.Register/src/Altinn.Register/Controllers/PartiesController.cs

@@ -2,14 +2,18 @@
 
 using System.Diagnostics;
 using System.Security.Claims;
+
 using Altinn.Platform.Register.Models;
 using Altinn.Register.Core.Parties;
 using Altinn.Register.Extensions;
 using Altinn.Register.Models;
 using Altinn.Register.Services.Interfaces;
+
 using AltinnCore.Authentication.Constants;
+
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
+
 using V1Models = Altinn.Platform.Register.Models;
 
 namespace Altinn.Register.Controllers
@@ -155,6 +159,7 @@ public PartiesController(IV1PartyService partyClient, IAuthorizationClient autho
         /// Perform a name lookup for the list of parties for the provided ids.
         /// </summary>
         /// <param name="partyNamesLookup">A list of lookup criteria. For each criteria, one and only one of the properties must be a valid value.</param>
+        /// <param name="partyComponentOption">Specifies the components that should be included when retrieving party's information.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The identified party names for the corresponding identifiers.</returns>
         [HttpPost("nameslookup")]
@@ -163,7 +168,10 @@ public PartiesController(IV1PartyService partyClient, IAuthorizationClient autho
         [ProducesResponseType(404)]
         [ProducesResponseType(200)]
         [Produces("application/json")]
-        public async Task<ActionResult<PartyNamesLookupResult>> PostPartyNamesLookup([FromBody] PartyNamesLookup partyNamesLookup, CancellationToken cancellationToken = default)
+        public async Task<ActionResult<PartyNamesLookupResult>> PostPartyNamesLookup(
+            [FromBody] PartyNamesLookup partyNamesLookup,
+            [FromQuery] PartyComponentOptions partyComponentOption = PartyComponentOptions.None,
+            CancellationToken cancellationToken = default)
         {
             if (partyNamesLookup.Parties is null or { Count: 0 })
             {
@@ -173,7 +181,7 @@ public async Task<ActionResult<PartyNamesLookupResult>> PostPartyNamesLookup([Fr
                 });
             }
 
-            List<PartyName> items = await _partyClient.LookupPartyNames(partyNamesLookup.Parties, cancellationToken).ToListAsync(cancellationToken);
+            List<PartyName> items = await _partyClient.LookupPartyNames(partyNamesLookup.Parties, partyComponentOption, cancellationToken).ToListAsync(cancellationToken);
             var partyNamesLookupResult = new PartyNamesLookupResult
             {
                 PartyNames = items

src/Altinn.Register/src/Altinn.Register/Extensions/ModelBinderProviderListExtensions.cs

@@ -0,0 +1,29 @@
+using Altinn.Register.ModelBinding;
+
+using Microsoft.AspNetCore.Mvc.ModelBinding;
+
+namespace Altinn.Register.Extensions;
+
+/// <summary>
+/// Extension methods for <see cref="IList{T}"/> of <see cref="IModelBinderProvider"/>.
+/// </summary>
+internal static class ModelBinderProviderListExtensions
+{
+    /// <summary>
+    /// Inserts a <see cref="ISingleton{TSelf}"/> binder provider into the list at the specified index.
+    /// </summary>
+    /// <typeparam name="T">The binder type.</typeparam>
+    /// <param name="list">The list of <see cref="IModelBinderProvider"/>.</param>
+    /// <param name="index">The zero-based index at which the binder provider should be inserted.</param>
+    /// <returns>The modified list, for chaining.</returns>
+    /// <exception cref="ArgumentNullException">Thrown if <paramref name="list"/> is null.</exception>
+    public static IList<IModelBinderProvider> InsertSingleton<T>(this IList<IModelBinderProvider> list, int index)
+        where T : IModelBinderProvider, ISingleton<T>
+    {
+        ArgumentNullException.ThrowIfNull(list);
+
+        var instance = T.Instance;
+        list.Insert(index, instance);
+        return list;
+    }
+}