Adds ancestor identifiers on document tree and collection responses

[AndyButland]

Prerequisites

• I have added steps to test this contribution in the description below

Relates to the fix necessary for #18517

Description

When evaluating document permissions on the client, there's a need to know the ancestors of the current item. This is because granular permissions can be assigned on an ancestor document, and they should apply to the current one.

From internal discussion:

... I think I have it working correctly for the workspace now. To check the inheritance path, we currently use the /tree/document/ancestors endpoint. It all works fine, but "unfortunately," we have made some updates to the UI which give me some challenges with this endpoint.
We now show the first available "Entity Action" on all tree items and collection items. This means that I would need to check for permissions already when rendering the tree and a collection, and can't wait and ask each individual item when opening the menu.
In the old back office, if I remember correctly, we had the path - a string array of ids available on each tree item: [-1, 12, 25, 48], etc. If we are able to bring something similar back, then I have all the information available that I need.

So this PR brings back this "path", but in the form of an array of GUIDs under a property named ancestors. It's added on the document tree and collection item response models.

To populate I've created a new method in IEntityService that uses the IIdKeyMap to translate the entity's Path property - which is a comma delimited list of integer IDs - to the array of GUIDs.

Testing

To test you can call the following management API endpoints, for documents at various levels in the tree and verify the ancestors property is correctly populated.

GET /umbraco/management/api/v1/collection/document/{id}?orderBy=updateDate&skip=0&take=100
GET /umbraco/management/api/v1/tree/document/children?parentId={id}&skip=0&take=100

E.g. you should get a response like the following:

{
  "total": 5,
  "items": [
    {
      "documentType": {
        "id": "752230cd-fc00-441e-85e5-a8efbcccdc84",
        "alias": "blogpost",
        "icon": "icon-calendar color-black"
      },
      "isTrashed": false,
      "isProtected": false,
      "ancestors": [
        {
          "id": "ca4249ed-2b23-4337-b522-63cabe5587d1"
        },
        {
          "id": "e8ad9b65-cff6-4952-ac5b-efe56a60db62"
        }
      ],
     ...

[Copilot]

Pull Request Overview

This PR adds ancestor ID details (as an array of GUIDs) to document tree and collection responses to support granular permission inheritance. Key changes include:

• Adding a new method GetPathKeys to convert an entity’s comma‐separated path into GUIDs.
• Updating response models and mapping to include the new AncestorIds property.
• Extending user start node entity services and tests to validate access based on ancestor paths.

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Umbraco.Tests.Integration/Umbraco.Infrastructure/Services/EntityServiceTests.cs	Added tests for the new GetPathKeys functionality.
tests/Umbraco.Tests.Integration/ManagementApi/Services/UserStartNodeEntitiesServiceTests.cs	Introduced tests to validate start node entities with the new ancestor information.
tests/Umbraco.Tests.Integration/ManagementApi/Services/UserStartNodeEntitiesServiceTests.RootUserAccessEntities.cs	Added tests for root user access entities.
tests/Umbraco.Tests.Integration/ManagementApi/Services/UserStartNodeEntitiesServiceTests.ChildUserAccessEntities.cs	Added tests for child user access entities and pagination behavior.
src/Umbraco.Core/Services/IEntityService.cs	Added default interface definition for GetPathKeys.
src/Umbraco.Core/Services/EntityService.cs	Implemented GetPathKeys to parse and convert entity paths.
src/Umbraco.Cms.Api.Management/ViewModels/Tree/DocumentTreeItemResponseModel.cs	Added AncestorIds property to include ancestor GUID details on tree items.
src/Umbraco.Cms.Api.Management/ViewModels/Document/Collection/DocumentCollectionResponseModel.cs	Added AncestorIds property on document collections.
src/Umbraco.Cms.Api.Management/Services/Entities/UserStartNodeEntitiesService.cs	Updated user start node services to support the new ancestor logic.
src/Umbraco.Cms.Api.Management/Mapping/Document/DocumentMapDefinition.cs	Updated mapping to exclude IsProtected and include AncestorIds.
src/Umbraco.Cms.Api.Management/Factories/DocumentCollectionPresentationFactory.cs	Set AncestorIds on collection items using the new GetPathKeys call.
src/Umbraco.Cms.Api.Management/Controllers/Tree/UserStartNodeTreeControllerBase.cs	Adjusted child entity retrieval to use updated access logic.
src/Umbraco.Cms.Api.Management/Controllers/Document/Tree/DocumentTreeControllerBase.cs	Mapped AncestorIds when generating document tree item responses.

Files not reviewed (1)

• tests/Umbraco.Tests.Integration/Umbraco.Tests.Integration.csproj: Language not supported

Comments suppressed due to low confidence (1)

tests/Umbraco.Tests.Integration/ManagementApi/Services/UserStartNodeEntitiesServiceTests.cs:56

• The array initializer syntax using square brackets may be invalid in C#; consider using a proper array initializer such as "new[] { new AllowedContentType { Alias = contentType.Alias, Key = contentType.Key } }".

contentType.AllowedContentTypes = [new() { Alias = contentType.Alias, Key = contentType.Key }];

[madsrasmussen]

Reviewing as a consumer.

The updates work as expected. I get the ancestors for both document tree items and document collection items. We probably want to expand this to all silos with a tree at some point, but this is great for now!

One detail about the naming. We currently have the convention that all referenced data should be objects. I think this should follow the same convention. The data will then be something like:

"ancestors": [
  {
    "id": "1234"
  },
  {
    "id": "4567"
   }
]

[AndyButland]

One detail about the naming. We currently have the convention that all referenced data should be objects. I think this should follow the same convention.

I've updated to reflect this @madsrasmussen.

[nikolajlauridsen]

BE looks beautiful 👍