User group: add description to user group (closes #14986)

src/Umbraco.Cms.Api.Management/Factories/UserGroupPresentationFactory.cs

@@ -54,6 +54,7 @@ public async Task<UserGroupResponseModel> CreateAsync(IUserGroup userGroup)
         {
             Id = userGroup.Key,
             Name = userGroup.Name ?? string.Empty,
+            Description = userGroup.Description ?? string.Empty,
             Alias = userGroup.Alias,
             DocumentStartNode = ReferenceByIdModel.ReferenceOrNull(contentStartNodeKey),
             DocumentRootAccess = contentRootAccess,
@@ -87,6 +88,7 @@ public async Task<UserGroupResponseModel> CreateAsync(IReadOnlyUserGroup userGro
         {
             Id = userGroup.Key,
             Name = userGroup.Name ?? string.Empty,
+            Description = userGroup.Description ?? string.Empty,
             Alias = userGroup.Alias,
             DocumentStartNode = ReferenceByIdModel.ReferenceOrNull(contentStartNodeKey),
             MediaStartNode = ReferenceByIdModel.ReferenceOrNull(mediaStartNodeKey),
@@ -132,6 +134,7 @@ public async Task<Attempt<IUserGroup, UserGroupOperationStatus>> CreateAsync(Cre
         {
             Name = CleanUserGroupNameOrAliasForXss(requestModel.Name),
             Alias = CleanUserGroupNameOrAliasForXss(requestModel.Alias),
+            Description = requestModel.Description,
             Icon = requestModel.Icon,
             HasAccessToAllLanguages = requestModel.HasAccessToAllLanguages,
             Permissions = requestModel.FallbackPermissions,
@@ -197,9 +200,10 @@ public async Task<Attempt<IUserGroup, UserGroupOperationStatus>> UpdateAsync(IUs
 
         current.Name = CleanUserGroupNameOrAliasForXss(request.Name);
         current.Alias = CleanUserGroupNameOrAliasForXss(request.Alias);
+        current.Description = request.Description;
         current.Icon = request.Icon;
         current.HasAccessToAllLanguages = request.HasAccessToAllLanguages;
-
+        
         current.Permissions = request.FallbackPermissions;
         current.GranularPermissions = await _permissionPresentationFactory.CreatePermissionSetsAsync(request.Permissions);
 

src/Umbraco.Cms.Api.Management/ViewModels/UserGroup/UserGroupBase.cs

@@ -1,4 +1,4 @@
-using Umbraco.Cms.Api.Management.ViewModels.UserGroup.Permissions;
+using Umbraco.Cms.Api.Management.ViewModels.UserGroup.Permissions;
 
 namespace Umbraco.Cms.Api.Management.ViewModels.UserGroup;
 
@@ -22,6 +22,11 @@ public class UserGroupBase
     /// </summary>
     public required string Alias { get; init; }
 
+    /// <summary>
+    /// The description of the user group
+    /// </summary>
+    public string? Description { get; set; }
+
     /// <summary>
     /// The Icon for the user group
     /// </summary>

src/Umbraco.Core/Models/Membership/IReadOnlyUserGroup.cs

@@ -9,6 +9,10 @@ public interface IReadOnlyUserGroup
 {
     string? Name { get; }
 
+    string Alias { get; }
+
+    string? Description { get { return null; } }
+
     string? Icon { get; }
 
     int Id { get; }
@@ -19,11 +23,6 @@ public interface IReadOnlyUserGroup
 
     int? StartMediaId { get; }
 
-    /// <summary>
-    ///     The alias
-    /// </summary>
-    string Alias { get; }
-
     // This is set to return true as default to avoid breaking changes.
     bool HasAccessToAllLanguages => true;
 

src/Umbraco.Core/Models/Membership/IUserGroup.cs

@@ -22,6 +22,14 @@ public interface IUserGroup : IEntity, IRememberBeingDirty
     /// </summary>
     string? Name { get; set; }
 
+    /// <summary>
+    ///    The description
+    /// </summary>
+    string? Description {
+        get => null;
+        set { }
+    }
+
     /// <summary>
     ///     If this property is true it will give the group access to all languages
     /// </summary>

src/Umbraco.Core/Models/Membership/ReadOnlyUserGroup.cs

@@ -55,6 +55,8 @@ public bool Equals(ReadOnlyUserGroup? other)
 
     public string Name { get; }
 
+    public string? Description { get; }
+
     public string? Icon { get; }
 
     public int? StartContentId { get; }

src/Umbraco.Core/Models/Membership/UserGroup.cs

@@ -30,6 +30,7 @@ public class UserGroup : EntityBase, IUserGroup, IReadOnlyUserGroup
     private string _alias;
     private string? _icon;
     private string _name;
+    private string? _description;
     private bool _hasAccessToAllLanguages;
     private ISet<string> _permissions;
     private ISet<IGranularPermission> _granularPermissions;
@@ -111,6 +112,13 @@ public string? Name
         set => SetPropertyValueAndDetectChanges(value, ref _name!, nameof(Name));
     }
 
+    [DataMember]
+    public string? Description
+    {
+        get => _description;
+        set => SetPropertyValueAndDetectChanges(value, ref _description!, nameof(Description));
+    }
+
     [DataMember]
     public bool HasAccessToAllLanguages
     {

src/Umbraco.Infrastructure/Migrations/Upgrade/UmbracoPlan.cs

@@ -144,6 +144,9 @@
         // To 17.0.1
         To<V_17_0_1.EnsureUmbracoPropertyDataColumnCasing>("{BE5CA411-E12D-4455-A59E-F12A669E5363}");
 
+        // To 17.1.0
+        To<V_17_1_0.AddDescriptionToUserGroup>("{F1A2B3C4-D5E6-4789-ABCD-1234567890AB}");
+
         // To 18.0.0
         // TODO (V18): Enable on 18 branch
         //// To<V_18_0_0.MigrateSingleBlockList>("{74332C49-B279-4945-8943-F8F00B1F5949}");

src/Umbraco.Infrastructure/Migrations/Upgrade/V_17_1_0/AddDescriptionToUserGroup.cs

@@ -0,0 +1,43 @@
+using Umbraco.Cms.Core;
+using Umbraco.Cms.Infrastructure.Persistence.Dtos;
+
+namespace Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_17_1_0
+{
+    /// <summary>
+    /// Migration to add a description column to the user group table.
+    /// </summary>
+    public class AddDescriptionToUserGroup : AsyncMigrationBase
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AddDescriptionToUserGroup"/> class.
+        /// </summary>
+        /// <param name="context">The migration context.</param>
+        public AddDescriptionToUserGroup(
+            IMigrationContext context)
+            : base(context)
+        {
+        }
+
+        /// <inheritdoc/>
+        protected override async Task MigrateAsync()
+        {
+            if (TableExists(Constants.DatabaseSchema.Tables.UserGroup) is false)
+            {
+                return;
+            }
+
+            const string ColumnName = "description";
+            var hasColumn = Context.SqlContext.SqlSyntax.GetColumnsInSchema(Context.Database)
+                .Any(c =>
+                    c.TableName == Constants.DatabaseSchema.Tables.UserGroup &&
+                    c.ColumnName == ColumnName);
+
+            if (hasColumn)
+            {
+                return;
+            }
+
+            AddColumn<UserGroupDto>(Constants.DatabaseSchema.Tables.UserGroup, ColumnName);
+        }
+    }
+}

src/Umbraco.Infrastructure/Persistence/Dtos/UserGroupDto.cs

@@ -40,6 +40,11 @@ public UserGroupDto()
     [Index(IndexTypes.UniqueNonClustered, Name = "IX_umbracoUserGroup_userGroupName")]
     public string? Name { get; set; }
 
+    [Column(Name = "description")]
+    [SpecialDbType(SpecialDbTypes.NVARCHARMAX)]
+    [NullSetting(NullSetting = NullSettings.Null)]
+    public string? Description { get; set; }
+
     [Column("userGroupDefaultPermissions")]
     [Length(50)]
     [NullSetting(NullSetting = NullSettings.Null)]

src/Umbraco.Infrastructure/Persistence/Factories/UserGroupFactory.cs

@@ -30,6 +30,7 @@ public static IUserGroup BuildEntity(IShortStringHelper shortStringHelper, UserG
             userGroup.StartMediaId = dto.StartMediaId;
             userGroup.Permissions = dto.UserGroup2PermissionDtos.Select(x => x.Permission).ToHashSet();
             userGroup.HasAccessToAllLanguages = dto.HasAccessToAllLanguages;
+            userGroup.Description = dto.Description;
             if (dto.UserGroup2AppDtos != null)
             {
                 foreach (UserGroup2AppDto app in dto.UserGroup2AppDtos)
@@ -84,6 +85,7 @@ public static UserGroupDto BuildDto(IUserGroup entity)
             Key = entity.Key,
             Alias = entity.Alias,
             Name = entity.Name,
+            Description = entity.Description,
             UserGroup2AppDtos = new List<UserGroup2AppDto>(),
             CreateDate = entity.CreateDate,
             UpdateDate = entity.UpdateDate,

src/Umbraco.Infrastructure/Persistence/Mappers/UserGroupMapper.cs

@@ -25,5 +25,6 @@ protected override void DefineMaps()
         DefineMap<UserGroup, UserGroupDto>(nameof(UserGroup.Icon), nameof(UserGroupDto.Icon));
         DefineMap<UserGroup, UserGroupDto>(nameof(UserGroup.StartContentId), nameof(UserGroupDto.StartContentId));
         DefineMap<UserGroup, UserGroupDto>(nameof(UserGroup.StartMediaId), nameof(UserGroupDto.StartMediaId));
+        DefineMap<UserGroup, UserGroupDto>(nameof(UserGroup.Description), nameof(UserGroupDto.Description));
     }
 }

src/Umbraco.Infrastructure/Persistence/Repositories/Implement/UserGroupRepository.cs

@@ -481,6 +481,7 @@ private static void AppendGroupBy(Sql<ISqlContext> sql) =>
                 x => x.UpdateDate,
                 x => x.Alias,
                 x => x.Name,
+                x => x.Description,
                 x => x.HasAccessToAllLanguages,
                 x => x.Key,
                 x => x.DefaultPermissions)

src/Umbraco.Web.UI.Client/src/packages/core/backend-api/types.gen.ts

@@ -419,6 +419,7 @@ export type CreateUserGroupRequestModel = {
     fallbackPermissions: Array<string>;
     permissions: Array<DocumentPermissionPresentationModel | DocumentPropertyValuePermissionPresentationModel | UnknownTypePermissionPresentationModel>;
     id?: string | null;
+    description?: string | null;
 };
 
 export type CreateUserRequestModel = {
@@ -2810,6 +2811,7 @@ export type UpdateUserDataRequestModel = {
 
 export type UpdateUserGroupRequestModel = {
     name: string;
+    description?: string | null;
     alias: string;
     icon?: string | null;
     sections: Array<string>;
@@ -2925,6 +2927,7 @@ export type UserGroupResponseModel = {
     id: string;
     isDeletable: boolean;
     aliasCanBeChanged: boolean;
+    description?: string | null;
 };
 
 export type UserInstallRequestModel = {

src/Umbraco.Web.UI.Client/src/packages/user/user-group/collection/repository/user-group-collection.server.data-source.ts

@@ -45,6 +45,7 @@ export class UmbUserGroupCollectionServerDataSource implements UmbCollectionData
 					mediaRootAccess: item.mediaRootAccess,
 					mediaStartNode: item.mediaStartNode ? { unique: item.mediaStartNode.id } : null,
 					name: item.name,
+					description: item.description || null,
 					permissions: item.permissions,
 					sections: item.sections,
 					unique: item.id,

src/Umbraco.Web.UI.Client/src/packages/user/user-group/components/user-group-ref/user-group-ref.element.ts

@@ -36,6 +36,9 @@
 		this.#observeMediaStartNode(value);
 	}
 
+	@property({ type: String })
+	description: string | null = null;
+
 	@property({ type: Array })
 	public get sections(): Array<string> {
 		return [];
@@ -150,18 +153,20 @@
 		`;
 	}
 
 	#renderDetails() {
-		const hasSections = this._sectionLabels.length;
-		const hasDocument = !!this._documentLabel || this.documentRootAccess;
-		const hasMedia = !!this._mediaLabel || this.mediaRootAccess;
-		const hasUserPermissions = this._userPermissionLabels.length;
-
-		if (!hasSections && !hasDocument && !hasMedia && !hasUserPermissions) return;
-
 		return html`
 			<div id="details">
-				${this.#renderSections()} ${this.#renderDocumentStartNode()} ${this.#renderMediaStartNode()}
-				${this.#renderUserPermissions()}
+				${this.#renderDescription()} ${this.#renderSections()} ${this.#renderDocumentStartNode()}
+				${this.#renderMediaStartNode()} ${this.#renderUserPermissions()}
+			</div>
+		`;
+	}
+
+	#renderDescription() {
+		if (!this.description) return;
+		return html`
+			<div>
+				<small>${this.description}</small>
 			</div>
 		`;
 	}

src/Umbraco.Web.UI.Client/src/packages/user/user-group/modals/user-group-picker/user-group-picker-modal.element.ts

@@ -114,6 +114,7 @@ export class UmbUserGroupPickerModalElement extends UmbModalBaseElement<
 								?mediaRootAccess=${userGroup.mediaRootAccess}
 								.mediaStartNode=${!userGroup.mediaRootAccess ? userGroup.mediaStartNode?.unique : null}
 								.sections=${userGroup.sections}
+								.description=${userGroup.description}
 								@selected=${(event: UUIMenuItemEvent) => this.#onSelected(event, userGroup)}
 								@deselected=${(event: UUIMenuItemEvent) => this.#onDeselected(event, userGroup)}>
 								${when(userGroup.icon, () => html`<umb-icon name=${userGroup.icon!} slot="icon"></umb-icon>`)}

src/Umbraco.Web.UI.Client/src/packages/user/user-group/repository/detail/user-group-detail.server.data-source.ts

@@ -45,6 +45,7 @@ export class UmbUserGroupServerDataSource
 			permissions: [],
 			sections: [],
 			unique: UmbId.new(),
+			description: '',
 		};
 
 		return { data };
@@ -98,6 +99,7 @@ export class UmbUserGroupServerDataSource
 			permissions,
 			sections: data.sections,
 			unique: data.id,
+			description: data.description ?? null,
 		};
 
 		return { data: userGroup };
@@ -136,6 +138,7 @@ export class UmbUserGroupServerDataSource
 			name: model.name,
 			permissions,
 			sections: model.sections,
+			description: model.description,
 		};
 
 		const { data, error } = await tryExecute(
@@ -186,6 +189,7 @@ export class UmbUserGroupServerDataSource
 			name: model.name,
 			permissions,
 			sections: model.sections,
+			description: model.description,
 		};
 
 		const { error } = await tryExecute(

src/Umbraco.Web.UI.Client/src/packages/user/user-group/types.ts

@@ -19,4 +19,5 @@ export interface UmbUserGroupDetailModel {
 	permissions: Array<any>;
 	sections: Array<string>;
 	unique: string;
+	description: string | null;
 }