{"title":"Migrate from User Groups to Permission Sets or Security Groups","url":"https://jonas-paprotka.de/docs/dev-itpro/upgrade/deprecated-features-user-groups/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/upgrade/deprecated-features-user-groups, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/upgrade/deprecated-features-user-groups","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"This article describes why we've deprecated user groups, and provides developers with examples of how they can uptake the change in their extensions.","date":"2023-08-24","meta":{"topic":"upgrade-and-migration-article"},"outline":[{"level":1,"title":"Migrate from User Groups to Permission Sets or Security Groups","slug":"migrate-from-user-groups-to-permission-sets-or-security-groups","at":0,"chars":11169},{"level":2,"title":"Optional: Security groups","slug":"optional-security-groups","at":570,"chars":717},{"level":2,"title":"Example scenarios","slug":"example-scenarios","at":1287,"chars":8273},{"level":3,"title":"Example: Your extension creates user groups","slug":"example-your-extension-creates-user-groups","at":1750,"chars":2657},{"level":3,"title":"Example: You add members to user groups through code","slug":"example-you-add-members-to-user-groups-through-code","at":4407,"chars":2218},{"level":3,"title":"Example: Your extension provides capabilities to groups of users","slug":"example-your-extension-provides-capabilities-to-groups-of-users","at":6625,"chars":1359},{"level":3,"title":"Example: Your extension relies on default profiles from user groups","slug":"example-your-extension-relies-on-default-profiles-from-user-groups","at":7984,"chars":345},{"level":3,"title":"Example: You add actions, fields, or controls to user group pages","slug":"example-you-add-actions-fields-or-controls-to-user-group-pages","at":8329,"chars":1231},{"level":2,"title":"Deprecated objects","slug":"deprecated-objects","at":9560,"chars":865},{"level":2,"title":"Objects that can help you migrate","slug":"objects-that-can-help-you-migrate","at":10425,"chars":474},{"level":2,"title":"Related information","slug":"related-information","at":10899,"chars":270}],"text":"# Migrate from User Groups to Permission Sets or Security Groups\n> APPLIES TO: Business Central 2023 release wave 1 and later\nThe recent improvements to permission set features and the introduction of Business Central security groups made user groups redundant. Therefore, to streamline permission management, we've deprecated user groups.\nThis article provides developers with examples of how they can update their extensions to accommodate the change.\nTo learn more about permission sets, go to Assign Permissions to Users and Groups</ui-define-granular-permissions>.\n## Optional: Security groups\nYou have the option of assigning permission sets to security groups. In terms of managing permissions, security groups work in the same way as user groups.\nHowever, user groups were only relevant for Business Central. Security groups are based on the security groups in Microsoft Entra ID or Windows Active Directory, depending on whether you're using Business Central online or on-premises, respectively. That means administrators can use them with other Dynamics 365 apps. For example, if salespeople use Business Central and SharePoint, administrators don't have to recreate the group and its members. See Control Access to Business Central Using Security Groups</ui-security-groups>.\n## Example scenarios\nDepending on how your extensions leverage user groups, the actions you need to take might differ. In some cases, you'll only need to change your code to use permission sets. In other cases, you'll need to use security groups. You might even want to do both.\nThe following examples show how to update your extension to address various scenarios. The examples include both how you could handle the scenarios before, and how to handle them now.\n### Example: Your extension creates user groups\nThe following example shows how to create permission sets instead of user groups.\nBefore\n```al\n    local procedure InsertUserGroup(UserGroupCode: Code[20]; UserGroupName: Text[50])\n    var\n        UserGroup: Record \"User Group\";\n    begin\n        if UserGroup.Get(UserGroupCode) then\n            exit;\n\n        UserGroup.Code := UserGroupCode;\n        UserGroup.Name := UserGroupName;\n        UserGroup.Insert();\n\n        // More logic, for example, adding permission sets to the user group by inserting records into the \"User Group Permission Set\" table.\n    end;\n```\nAfter\nThe preferred way is to create a new object of the type permissionset.\n```al\n    permissionset 9999 \"Permission set code\"\n    {\n        Assignable = true;\n        Caption 'Permission set name';\n\n        IncludedPermissionSets = ...; // This is similar to adding permission sets to the user group by inserting records into the \"User Group Permission Set\" table.\n\n        Permissions = ...;\n    }\n\n```\nAlternatively, you can create a tenant permission set dynamically.\n```al\n    local procedure CreateNewTenantPermissionSet(PermissionSetRoleID: Code[20]; PermissionSetName: Text[30])\n    var\n        TenantPermissionSet: Record \"Tenant Permission Set\";\n        NullGuid: Guid;\n    begin\n        TenantPermissionSet.SetRange(\"App ID\", NullGuid);\n        TenantPermissionSet.SetRange(\"Role ID\", PermissionSetRoleID);\n        if not TenantPermissionSet.IsEmpty() then\n            exit;\n\n        TenantPermissionSet.\"App ID\" := NullGuid;\n        TenantPermissionSet.\"Role ID\" := PermissionSetRoleID;\n        TenantPermissionSet.Name := PermissionSetName;\n        TenantPermissionSet.Insert();\n\n        // More logic, e. g. adding permission sets to the parent permission set by calling CreateTenantPermissionSetRelation\n    end;\n\n    local procedure CreateTenantPermissionSetRelation(RoleId: Code[20]; RelatedRoleID: Code[20]; RelatedAppId: Guid; RelatedScope: Option System,Tenant; PermissionType: Option Include,Exclude)\n    var\n        TenantPermissionSetRel: Record \"Tenant Permission Set Rel.\";\n        NullGuid: Guid;\n    begin\n        TenantPermissionSetRel.Init();\n        TenantPermissionSetRel.\"Role ID\" := CopyStr(RoleId, 1, MaxStrLen(TenantPermissionSetRel.\"Role ID\"));\n        TenantPermissionSetRel.\"App ID\" := NullGuid;\n        TenantPermissionSetRel.\"Related Role ID\" := RelatedRoleID;\n        TenantPermissionSetRel.\"Related App ID\" := RelatedAppId;\n        TenantPermissionSetRel.\"Related Scope\" := RelatedScope;\n        TenantPermissionSetRel.Type := PermissionType;\n        TenantPermissionSetRel.Insert();\n    end;\n```\n### Example: You add members to user groups through code\nThe following example shows how to rewrite your code to assign permission sets to users instead of adding members to user groups.\nBefore\n```al\n    local procedure AssignUserGroupToUser(InputUserGroupCode: Code[20]; InputUserSecurityID: Guid)\n    var\n        UserGroupMember: Record \"User Group Member\";\n    begin\n        if UserGroupIsAssignedToUser(InputUserGroupCode, InputUserSecurityID) then\n            exit;\n\n        UserGroupMember.\"User Group Code\" := InputUserGroupCode;\n        UserGroupMember.\"User Security ID\" := InputUserSecurityID;\n        UserGroupMember.Insert(true);\n    end;\n\n    local procedure IsUserGroupAssignedToUser(InputUserGroupCode: Code[20]; InputUserSecurityID: Guid): Boolean\n    var\n        UserGroupMember: Record \"User Group Member\";\n    begin\n        UserGroupMember.SetRange(\"User Group Code\", InputUserGroupCode);\n        UserGroupMember.SetRange(\"User Security ID\", InputUserSecurityID);\n        exit(not UserGroupMember.IsEmpty());\n    end;\n```\nAfter\n```al\n    local procedure AssignPermissionSetToUser(PermissionSetRoleId: Code[20]; InputUserSecurityID: Guid)\n    var\n        AccessControl: Record \"Access Control\";\n        AggregatePermissionSet: Record \"Aggregate Permission Set\";\n    begin\n        if IsPermissionSetAssignedToUser(PermissionSetRoleId, InputUserSecurityID) then\n            exit;\n\n        AggregatePermissionSet.SetRange(\"Role ID\", PermissionSetRoleId);\n        if not AggregatePermissionSet.FindFirst() then\n            exit;\n\n        AccessControl.\"Role Id\" := PermissionSetRoleId;\n        AccessControl.\"User Security ID\" := InputUserSecurityID;\n        AccessControl.Scope := AccessControl.Scope::System;\n        AccessControl.\"App ID\" := AggregatePermissionSet.\"App ID\";\n        if AccessControl.Insert() then;\n    end;\n\n    local procedure IsPermissionSetAssignedToUser(PermissionSetRoleId: Code[20]; InputUserSecurityID: Guid): Boolean\n    var\n        AccessControl: Record \"Access Control\";\n    begin\n        AccessControl.SetRange(\"Role Id\", PermissionSetRoleId);\n        AccessControl.SetRange(\"User Security ID\", InputUserSecurityID);\n        exit(not AccessControl.IsEmpty());\n    end;\n```\n### Example: Your extension provides capabilities to groups of users\nThe following example shows how to rewrite your code to use the grouping mechanism in security groups to group users in the same way as you did using user groups.\nBefore\n```al\n    local procedure DoStuffIfUserGroupMember(InputUserGroupCode: Code[20]; InputUserSecurityID: Guid)\n    var\n        UserGroupMember: Record \"User Group Member\";\n    begin\n        UserGroupMember.SetRange(\"User Group Code\", InputUserGroupCode);\n        UserGroupMember.SetRange(\"User Security ID\", InputUserSecurityID);\n        if not UserGroupMember.IsEmpty() then\n            ...\n            // Apply extension-specific capabilities to a member.\n    end;\n```\nAfter\n```al\n    local procedure DoStuffIfSecurityGroupMember(InputSecurityGroupCode: Code[20]; InputUserSecurityID: Guid)\n    var\n        SecurityGroupMemberBuffer: Record \"Security Group Member Buffer\";\n        SecurityGroup: Codeunit \"Security Group\";\n    begin\n        SecurityGroup.GetMembers(SecurityGroupMemberBuffer);\n        SecurityGroupMemberBuffer.SetRange(\"Security Group Code\", InputSecurityGroupCode);\n        SecurityGroupMemberBuffer.SetRange(\"User Security ID\", InputUserSecurityID);\n        if not SecurityGroupMemberBuffer.IsEmpty() then\n            ...\n            // Apply extension-specific capabilities to a member.\n    end;\n```\n### Example: Your extension relies on default profiles from user groups\nThe default profile functionality can no longer be dynamically defined for groups of users. Instead, use the Profiles (Roles) page to specify a default profile for your company. To learn more about default profiles, go to Manage User Profiles</admin-users-profiles-roles>.\n### Example: You add actions, fields, or controls to user group pages\nIf you extend the user group functionality by adding actions, fields, or controls, you can add them to pages related to permission sets and security groups. The following example shows how to do that.\nBefore\n```al\n    pageextension 9999 \"New Group Functionality\" extends \"User Group Members\"\n    {\n        actions\n        {\n            addlast(creation)\n            {\n                action(ApplyFunctionalityToMembers)\n                {\n                    ...\n                }\n            }\n        }\n    }\n```\nAfter\n```al\n    pageextension 9999 \"New Group Functionality\" extends \"Security Group Members\"\n    {\n        actions\n        {\n            addlast(Processing)\n            {\n                action(ApplyFunctionalityToMembers)\n                {\n                    ...\n                }\n            }\n        }\n    }\n    ...\n    pageextension 9998 \"New Group Functionality\" extends \"Perm. Set Assignments Part\"\n    {\n        actions\n        {\n            addlast(Processing)\n            {\n                action(ApplyFunctionalityToUsersWithPermissionSet)\n                {\n                    ...\n                }\n            }\n        }\n    }\n```\n## Deprecated objects\nThe following objects are deprecated. To make these objects easy to find in the code, we've added a `[220_UserGroups]` tag to the obsolete reason.\nName|Object type\nUser Group|table\nUser Group Member|table\nUser Group Access Control|table\nUser Group Permission Set|table\nUser Group Plan|table\nUsers in User Groups Chart|page\nDefault User Groups In Plan|page\nCustom User Groups In Plan|page\nUser Group Plan FactBox|page\nUser Groups FactBox|page\nUser Groups|page\nUser Group Members|page\nUser Group Members FactBox|page\nUser Groups User SubPage|page\nUser Group Permission Sets|page\nUser Group Permissions FactBox|page\nUser Group Memberships FactBox|page\nPermission Set by User Group|page\nUser by User Group|page\nUser Group by Plan|page\nUsers in User Groups|query\nCopy User Group|report\nExport/Import User Groups|xmlport\nExport/Import Plans|xmlport\n## Objects that can help you migrate\nThe following table lists the objects we've introduced to make it easier for you to migrate your extension to use permission sets instead of user groups.\nName|Object type|Comment\nLegacy User Groups|codeunit|Check whether user groups are enabled in the environment.\nUser Groups Migration Guide|page|A guide that can help you convert user groups to permission sets. See /ui-security-groups#optional-convert-user-groups-to-permission-sets.\n## Related information\nDeprecated Features in the Base App<deprecated-features-w1>\nBest Practices for Deprecation of AL Code<../developer/devenv-deprecation-guidelines>\nMicrosoft Timeline for Deprecating Code in Business Central<../developer/devenv-deprecation-timeline>"}