Exportable Granular Document Property Value permissions

[Gustavwk]

Is your feature request related to a problem? Please describe.

The UserGroupHandler in uSync.Complete 17.0.1 correctly exports Document Property Value permissions (the granular read/write permissions per property per user group introduced in Umbraco 14+), but does not import them back into the umbracoUserGroup2GranularPermission table.

This means granular property-level permissions cannot be deployed between environments via uSync. The export XML contains the permission data, but on import the data is silently ignored — the import reports success with no errors, yet the permissions are not restored.

Steps to reproduce:

1. Enable UserGroupHandler in appsettings.json
2. Set a Document Property Value permission on a User Group in the backoffice UI
3. Run a full uSync export — permission data is present in the exported XML
4. Wipe the database and run a full import
5. The permission is not restored — the umbracoUserGroup2GranularPermission table is empty and the permission is missing from the UI

Describe the solution you'd like

The UserGroupHandler deserializer should write the granular permission data from the exported XML back into the umbracoUserGroup2GranularPermission table on import. This would allow full round-trip sync of Document Property Value permissions between environments.

Describe alternatives you've considered

I've written a C# notification handler (UmbracoApplicationStartedNotification) that seeds the permissions directly into the umbracoUserGroup2GranularPermission table at startup using raw SQL. This works but relies on an undocumented internal table structure and has no official Umbraco service-layer API to use instead. It's a fragile workaround that could break on Umbraco upgrades.

I also explored using the frontend Guard Managers (propertyWriteGuard) via a backoffice extension, but this approach cannot target properties inside Block Grid blocks and relies on undocumented internals (_rules.setValue() instead of the documented addRule()).

Additional context
Umbraco version: 17.0.0
uSync.Complete version: 17.0.1

[KevinJump]

Yes, needed to fix this.

fixed in uSync.Complete v17.1.2

https://www.nuget.org/packages/uSync.Complete/17.1.2

[Gustavwk]

I updated the uSync.Complete package to v17.1.2, but my problem still persists.

"People": {
  "EnabledDefault": true
},
"Sets": {
  "Default": {
    "Handlers": {
      "UserGroupHandler": {
        "Enabled": true
      }
    }
  }
}

I make a granular Document Property Value permission, export, wipe my database and then import again. The umbracoUserGroup2GranularPermission table remains empty after import. The same is the case with granular permissions on pages.

[KevinJump]

Hi,

I had some sort of release meltdown there 😟 - did all the fixes, built and tested, merged back, pushed the wrong build to NuGet :(

v17.1.3 does fix this !

[KevinJump]

Hi,

Has the content been synced too - the grandular permissions will only work if it can find the content (at the moment by key, so it need to have been synced at some point).

if you want to share the user group .config file with me (kevin@jumoo.co.uk) i don't mind taking a glance but i suspect its just not finding the content item. - i think we might in theory be able to add the content path to the .config file on export and look it up that way, but i will have to take a look at that.

[Gustavwk]

I deleted my comment, because i thought that i had forgot to update, but i had in fact updated. Leaving this here now, just for clarity.

I am still having issues.

First it tried using this appsetting, to only enable the UserGroupHandler

...
"People": {
    "EnabledDefault": true
  },
  "Sets": {
    "Default": {
      "DisabledHandlers": [
        "MemberHandler",
        "MemberGroupHandler",
        "UserHandler"
      ]
    }
  },...

The UI indicated that the UserGroups has been importet, but i see nothing in umbracoUserGroup2GranularPermission.
Then just to test everything, i tried with a more inclusive appsettings:

...
 "uSync": {
  "Sets": {
    "Default": {
      "Handlers": {
        "UserGroupHandler": {
          "Enabled": true
        }
      }
    }
  },

...
With this enables, only the granular "Document permissions" persist, but the more specific granular "Document Property Value permissions" does not get imported and inserted into umbracoUserGroup2GranularPermission.

[Gustavwk]

Every time I run the import, I use the "Everything" import, so the content should be synced. But maybe the error is that the content is synced after the user groups. If the UI correctly indicates the order of sync, then the user groups are the first to be synced.

[KevinJump]

yes, maybe does a second import fix that ?

we can push some things into a phase past the last export (the post import actions), so we could do that for granular permissions if its an issue,

but quite a few things umbraco just lets us put a key in for something that doesn't yet exist and then it becomes correct when things sync.

but if this works after you do two impoty (you could make the second one a force import to confim) then wee could look at moving them.

[Gustavwk]

Here is what happens:

1. Create a granular permission on a document and on specific document properties
2. Export users
3. Delete the database
4. Full import
5. SELECT * FROM umbracoUserGroup2GranularPermission shows no entries
6. Force import on members
7. SELECT * FROM umbracoUserGroup2GranularPermission shows only one entry — the more general document granular permission. The granular document property permissions are not persisted

[Gustavwk]

This is still re-producible in 17.3

[KevinJump]

Hi,

Just to confirm these steps (because it appears to work for me 😞 )

hopefully you can spot something that I've done different here?

1. Create a granular permission.
   Are we talking about permissions set on the user group here ?

e.g like this :

2. export users.
   after this export step the userGroup (editors.config in my example) has granualr lines in.

3. delete the db
   I am stopping my site, and running rm .\umbraco\ -Force -Recurse (as i am using SqlLite locally this deletes the db, and logs).

4. Full import

   • run the site
   • import from the dashboard.

5. SELECT * FROM umbracoUserGroup2GranularPermission shows no entries
   At this point i do see the entries in the db.

also i see them in the back office.

6. the force doesn't change things, fo me its working first time :(

for reference my test site has these versions.

    <PackageVersion Include="Clean" Version="7.0.5" />
    <PackageVersion Include="Jumoo.TranslationManager" Version="17.*" />
    <PackageVersion Include="Umbraco.Cms" Version="17.3.4" />
    <PackageVersion Include="Umbraco.Cms.DevelopmentMode.Backoffice" Version="17.3.2" />
    <PackageVersion Include="Microsoft.ICU.ICU4C.Runtime" Version="72.1.0.3" />
    <PackageVersion Include="uSync" Version="17.3.0" />
    <PackageVersion Include="uSync.Complete" Version="17.3.0" />

[Gustavwk]

The "Document permissions" work fine after the patch, meaning that I can limit child sites in the tree document structure and sync it. I am referring to the more granular "Document Property Value permissions", which limit the user groups’ control over certain components, for example the text area in a rich text component.

From your context in the DB, it seems that you have made a higher-level limit, whereas limitations to the even more granular "Document Property Value permissions" would be labeled with "DocumentTypeProperty" in the context column in the DB.

[Gustavwk]

Another point is that if I apply a granular document permission on a parallel subsite, for example, if I remove read permissions for a user group, then that change is not persisted either, even though there is a .config file that describes it.

Example structure:
Two separate top-level sites:

• Frontpage
  • Site 1
  • Site 2
• Parallel site in the tree structure
  • Parallel site 1
  • Parallel site 2

In this case, if read permissions are removed from the editors group on the parallel site, the permission change is not saved correctly.

[KevinJump]

Yeah, see I didn't know they existed 🙂

the first issue is fixed here : https://dev.azure.com/jumoo/Public/_artifacts/feed/nightly/NuGet/uSync.Complete/overview/17.3.3-build.20260429.3

Not sure about the second one. might need a bit more detail, because granular permissions don't care about site structure, they are assigned to a content node (or it turns out a doctype). and that is saved and loaded from the db.

the only thing we are doing beyond this (which was part of the first issue) is on export we double check that the entity still exists in the db. I am guessing (because its been awhile) this is because we wanted to ensure orphaned permissions where not exported.

but as long as the entity is there - we export it, and on export event that doesn't get checked, we assign the permissions irrespective of the items existing (and this is why it works in a single pass).