#33912 rest api to update asset permissions

dotCMS/src/main/java/com/dotcms/business/APILocatorProducers.java

@@ -2,6 +2,7 @@
 
 import com.dotmarketing.business.APILocator;
 import com.dotmarketing.business.PermissionAPI;
+import com.dotmarketing.business.RoleAPI;
 import com.dotmarketing.business.UserAPI;
 import com.dotmarketing.portlets.contentlet.business.HostAPI;
 import com.dotmarketing.portlets.folders.business.FolderAPI;
@@ -30,6 +31,11 @@ public PermissionAPI getPermissionAPI() {
       return APILocator.getPermissionAPI();
    }
 
+   @Produces
+   public RoleAPI getRoleAPI() {
+      return APILocator.getRoleAPI();
+   }
+
    @Produces
    public FolderAPI getFolderAPI() {
       return APILocator.getFolderAPI();

dotCMS/src/main/java/com/dotcms/rest/api/v1/system/permission/AbstractAssetPermissionsView.java

@@ -0,0 +1,133 @@
+package com.dotcms.rest.api.v1.system.permission;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.immutables.value.Value;
+
+import javax.annotation.Nullable;
+import java.util.List;
+
+/**
+ * Immutable view representing an asset's permission data including metadata
+ * and a paginated list of role permissions. This is the entity returned by
+ * the GET /v1/permissions/{assetId} endpoint.
+ *
+ * @author hassandotcms
+ * @since 24.01
+ */
+@Value.Style(typeImmutable = "*", typeAbstract = "Abstract*")
+@Value.Immutable
+@JsonSerialize(as = AssetPermissionsView.class)
+@JsonDeserialize(as = AssetPermissionsView.class)
+@Schema(description = "Asset permissions organized by roles with metadata")
+public interface AbstractAssetPermissionsView {
+
+    /**
+     * Gets the asset identifier.
+     *
+     * @return Asset ID (inode or identifier depending on asset type)
+     */
+    @JsonProperty("assetId")
+    @Schema(
+        description = "Asset identifier",
+        example = "48190c8c-42c4-46af-8d1a-0cd5db894797",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    String assetId();
+
+    /**
+     * Gets the asset type.
+     *
+     * @return Asset type constant (HOST, FOLDER, CONTENT, TEMPLATE, CONTAINER, etc.)
+     */
+    @JsonProperty("assetType")
+    @Schema(
+        description = "Asset type",
+        example = "FOLDER",
+        allowableValues = {"HOST", "FOLDER", "CONTENT", "TEMPLATE", "CONTAINER", "PAGE", "LINK", "CATEGORY", "RULE", "CONTENT_TYPE"},
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    String assetType();
+
+    /**
+     * Gets the permission inheritance mode.
+     *
+     * @return INHERITED if inheriting from parent, INDIVIDUAL if has own permissions
+     */
+    @JsonProperty("inheritanceMode")
+    @Schema(
+        description = "Permission inheritance mode",
+        example = "INDIVIDUAL",
+        allowableValues = {"INHERITED", "INDIVIDUAL"},
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    String inheritanceMode();
+
+    /**
+     * Indicates if this asset can have child permissionables.
+     * Hosts and folders are typically parent permissionables.
+     *
+     * @return true if asset can have children with inheritable permissions
+     */
+    @JsonProperty("isParentPermissionable")
+    @Schema(
+        description = "Whether this asset can have child permissionables (e.g., hosts and folders)",
+        example = "true",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    boolean isParentPermissionable();
+
+    /**
+     * Indicates if the requesting user can edit permissions on this asset.
+     *
+     * @return true if user has EDIT_PERMISSIONS permission
+     */
+    @JsonProperty("canEditPermissions")
+    @Schema(
+        description = "Whether the requesting user can edit permissions on this asset",
+        example = "true",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    boolean canEditPermissions();
+
+    /**
+     * Indicates if the requesting user can edit this asset.
+     *
+     * @return true if user has WRITE permission
+     */
+    @JsonProperty("canEdit")
+    @Schema(
+        description = "Whether the requesting user can edit this asset",
+        example = "true",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    boolean canEdit();
+
+    /**
+     * Gets the parent asset identifier if one exists.
+     *
+     * @return Parent asset ID, or null if no parent
+     */
+    @JsonProperty("parentAssetId")
+    @Schema(
+        description = "Parent asset identifier (null if no parent or at root level)",
+        example = "abc-123-def-456"
+    )
+    @Nullable
+    String parentAssetId();
+
+    /**
+     * Gets the paginated list of role permissions.
+     * Each entry represents a role and its permissions on this asset.
+     *
+     * @return List of role permission views
+     */
+    @JsonProperty("permissions")
+    @Schema(
+        description = "Paginated list of role permissions assigned to this asset",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    List<RolePermissionView> permissions();
+}

dotCMS/src/main/java/com/dotcms/rest/api/v1/system/permission/AbstractRolePermissionView.java

@@ -0,0 +1,98 @@
+package com.dotcms.rest.api.v1.system.permission;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.immutables.value.Value;
+
+import javax.annotation.Nullable;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Immutable view representing a role's permission assignments on an asset.
+ * Each role can have individual permissions (directly on the asset) and
+ * inheritable permissions (propagated to child assets).
+ *
+ * @author hassandotcms
+ * @since 24.01
+ */
+@Value.Style(typeImmutable = "*", typeAbstract = "Abstract*")
+@Value.Immutable
+@JsonSerialize(as = RolePermissionView.class)
+@JsonDeserialize(as = RolePermissionView.class)
+@Schema(description = "Role permission assignment for an asset")
+public interface AbstractRolePermissionView {
+
+    /**
+     * Gets the role identifier.
+     *
+     * @return Role ID
+     */
+    @JsonProperty("roleId")
+    @Schema(
+        description = "Role identifier",
+        example = "abc-123-def-456",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    String roleId();
+
+    /**
+     * Gets the role display name.
+     *
+     * @return Role name
+     */
+    @JsonProperty("roleName")
+    @Schema(
+        description = "Role display name",
+        example = "CMS Administrator",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    String roleName();
+
+    /**
+     * Indicates if these permissions are inherited from a parent asset.
+     *
+     * @return true if inherited, false if set directly on this asset
+     */
+    @JsonProperty("inherited")
+    @Schema(
+        description = "Whether permissions are inherited from a parent asset",
+        example = "false",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    boolean inherited();
+
+    /**
+     * Gets the individual permission levels assigned to this role on the asset.
+     * These are permissions that apply directly to this asset.
+     *
+     * @return List of permission level names (READ, WRITE, PUBLISH, EDIT_PERMISSIONS, CAN_ADD_CHILDREN)
+     */
+    @JsonProperty("individual")
+    @Schema(
+        description = "Individual permission levels assigned directly to this role on the asset",
+        example = "[\"READ\", \"WRITE\", \"PUBLISH\"]",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    List<String> individual();
+
+    /**
+     * Gets the inheritable permissions grouped by scope.
+     * Only present for parent permissionables (hosts, folders).
+     * Map keys are permission scopes (HOST, FOLDER, CONTENT, TEMPLATE, etc.)
+     * and values are lists of permission level names.
+     *
+     * @return Map of scope to permission levels, or null if not a parent permissionable
+     */
+    @JsonProperty("inheritable")
+    @Schema(
+        description = "Inheritable permissions by scope (only for parent permissionables). " +
+                     "Keys are permission scopes (HOST, FOLDER, CONTENT, etc.), " +
+                     "values are permission level names",
+        example = "{\"FOLDER\": [\"READ\", \"WRITE\"], \"CONTENT\": [\"READ\"]}"
+    )
+    @Nullable
+    Map<String, List<String>> inheritable();
+}

dotCMS/src/main/java/com/dotcms/rest/api/v1/system/permission/AbstractUpdateAssetPermissionsView.java

@@ -0,0 +1,80 @@
+package com.dotcms.rest.api.v1.system.permission;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.immutables.value.Value;
+
+/**
+ * Immutable view for the update asset permissions operation result.
+ * Contains the result of saving permissions for multiple roles on an asset.
+ *
+ * <p>This view is returned by the PUT /api/v1/permissions/{assetId} endpoint
+ * and includes information about the operation (message, counts) plus the
+ * updated asset with its new permission assignments.
+ *
+ * @author dotCMS
+ * @since 24.01
+ */
+@Value.Style(typeImmutable = "*", typeAbstract = "Abstract*")
+@Value.Immutable
+@JsonSerialize(as = UpdateAssetPermissionsView.class)
+@JsonDeserialize(as = UpdateAssetPermissionsView.class)
+@Schema(description = "Result of updating asset permissions")
+public interface AbstractUpdateAssetPermissionsView {
+
+    /**
+     * Gets the success message.
+     *
+     * @return Success message describing the operation result
+     */
+    @JsonProperty("message")
+    @Schema(
+        description = "Success message describing the operation result",
+        example = "Permissions saved successfully",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    String message();
+
+    /**
+     * Gets the number of permissions saved.
+     *
+     * @return Count of permission entries saved
+     */
+    @JsonProperty("permissionCount")
+    @Schema(
+        description = "Number of permission entries saved during this operation",
+        example = "5",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    int permissionCount();
+
+    /**
+     * Indicates if inheritance was broken during this operation.
+     * When saving permissions on an asset that was inheriting from its parent,
+     * inheritance is automatically broken before saving.
+     *
+     * @return true if inheritance was broken, false if asset already had individual permissions
+     */
+    @JsonProperty("inheritanceBroken")
+    @Schema(
+        description = "Whether permission inheritance was broken during this operation. " +
+                     "True if the asset was previously inheriting permissions from its parent.",
+        example = "true",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    boolean inheritanceBroken();
+
+    /**
+     * Gets the updated asset with its new permission assignments.
+     *
+     * @return Asset permissions view with metadata and role permissions
+     */
+    @JsonProperty("asset")
+    @Schema(
+        description = "The updated asset with its new permission assignments",
+        requiredMode = Schema.RequiredMode.REQUIRED
+    )
+    AssetPermissionsView asset();
+}