[DSpace-CRIS] Administrative Edit of archived items via submission form and security configuration for metadata visibility (Rest Contract)

edititemmodes.md

@@ -0,0 +1,44 @@
+# EditItemMode Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+## Single EditItemMode
+**/api/core/edititemmodes/<:item-uuid>:<:mode-name>**
+
+Retrieves the configuration details for a specific edit mode applied to a specific item. Edit modes control how archived items can be edited, defining security constraints, which submission definition to use, and optional metadata filters for role-based editing.
+
+Edit modes are **configuration-driven** (defined in `dspace/config/spring/api/edititem-service.xml`) and vary by entity type. They cannot be created, updated, or deleted via the REST API.
+
+The endpoint uses a composite identifier `{itemUUID}:{modeName}` where:
+- `itemUUID` - The UUID of the item being queried
+- `modeName` - The name of the edit mode (e.g., "FULL", "OWNER", "INVESTIGATOR")
+
+The JSON response document is as follows:
+```json
+{
+  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab:OWNER",
+  "name": "OWNER",
+  "label": null,
+  "submissionDefinition": "person-edit",
+  "type": "edititemmode",
+  "uniqueType": "core.edititemmode",
+  "_links": {
+    "self": {
+      "href": "http://{dspace-url}/server/api/core/edititemmodes/a1b2c3d4-5678-90ab-cdef-1234567890ab:OWNER"
+    }
+  }
+}
+```
+
+**Response fields:**
+- `id`: Composite identifier in format `{itemUUID}:{modeName}`
+- `name`: The mode name (matches the second part of the ID)
+- `label`: Optional human-readable label for UI display (typically null)
+- `submissionDefinition`: Name of the submission definition from `item-submission.xml` that defines the editing form/workflow for this mode
+
+Return codes:
+* 200 OK - if the mode exists and is configured for the item's entity type
+* 400 Bad request - if the composite ID format is invalid (must be `{uuid}:{modeName}`)
+* 401 Unauthorized - if you are not authenticated
+* 404 Not found - if the item doesn't exist or the mode is not configured for the item's entity type
+
+**Note:** This endpoint returns the mode configuration if it exists for the item's entity type, but does not verify whether the current user has permission to use that mode. Authorization is enforced when attempting to access or edit the item via `/api/core/edititems/{uuid}:{mode}`.

edititems.md

@@ -0,0 +1,159 @@
+# EditItem Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+## Single EditItem
+**/api/core/edititems/<:id>:<:MODE>**
+
+Provide detailed information about a specific edititem. The JSON response document is as follow
+```json
+{
+	"id":"7a356e11-f719-4dae-ae44-fa93f21ee6a0:FIRST",
+	"lastModified":"2020-10-12T16:06:39.021+0000",
+	"sections":{
+		"titleAndIssuedDate":{
+			"dc.title":[
+				{
+					"value":"Title item",
+					"language":null,
+					"authority":null,
+					"confidence":-1,
+					"place":0
+				}
+			],
+			"dc.date.issued":[
+				{
+					"value":"2010-06-18",
+					"language":null,
+					"authority":null,
+					"confidence":-1,
+					"place":0
+				}
+			]
+		}
+	},
+	"type":"edititem",
+  "uniqueType": "core.edititem"
+}
+```
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 if you are not logged in with sufficient permissions to view the edititem
+* 404 Not found - if the edititem or MODE doesn't exist
+
+
+## Patch operations
+The PATCH method expects a JSON body according to the [JSON Patch specification RFC6902](https://tools.ietf.org/html/rfc6902)
+
+### Add
+To add a new value to an **existent metadata**  and the metadata must be defined in the submissionDefinition of current MODE ,the client must send a JSON Patch ADD operation as follow
+
+`curl -X PATCH '{dspace7-url}/api/core/edititems/<:id>:<:MODE>' -H "Authorization: Bearer ..." -H 'Content-Type: application/json' --data '[{"op":"add","path":"/sections/<:name-of-the-form>/<:metadata>/-","value":{"value":"...","language":"...","authority":"...","confidence":-1}}]'
+
+### Remove
+It is possible to remove a specific metadatavalue if the metadata is defined in the submissionDefinition of current MODE
+`curl --data '[{ "op": "remove", "path": "/sections/traditionalpageone/dc.subject/0"}]' -X PATCH ${dspace7-url}/api/core/edititems/<:id>:<:MODE>`
+
+## Find available modes
+**/api/core/edititems/search/findModesById?uuid=<:id>**
+
+Provide detailed information about edit item modes available to current user for Item having uuid passed as input parameter. 
+The JSON response document is as follow
+```json
+{
+  "_embedded": {
+    "edititemmodes": [
+      {
+        "id": "FULL",
+        "name": "FULL",
+        "label": null,
+        "submissionDefinition": "publication-edit",
+        "type": "edititemmode",
+        "uniqueType": "core.edititemmode",
+        "_links": {
+          "self": {
+            "href": "https://{dspace-cris-backend-url}/server/api/core/edititemmodes/FULL"
+          }
+        }
+      }
+    ]
+  },
+  "_links": {
+    "self": {
+      "href": "http://{dspace-cris-backend-url}/server/api/core/edititems/search/findModesById?uuid=9880d9e1-5441-4e14-a6e8-6cf453bc25f9"
+    }
+  },
+  "page": {
+    "size": 20,
+    "totalElements": 1,
+    "totalPages": 1,
+    "number": 0
+  }
+}
+```
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad request - if the id parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated
+
+## Find edit items by submitter
+**/api/core/edititems/search/findBySubmitter?uuid=<:submitter-uuid>**
+
+Returns a paginated list of edit items submitted by the specified user (EPerson). Each EditItem is returned **without a specific mode**, using the mode identifier `"none"` in the composite ID. This means the returned EditItems have minimal information and no populated sections, as they are not bound to any particular edit mode configuration.
+
+To work with a specific edit mode for an item, use the `/api/core/edititems/search/findModesById` endpoint to discover available modes, then access the item via `/api/core/edititems/{uuid}:{mode}`.
+
+**Note:** This endpoint requires READ permission on the specified EPerson. It retrieves all archived items where the submitter field matches the provided UUID.
+
+The JSON response document is as follows:
+```json
+{
+  "_embedded": {
+    "edititems": [
+      {
+        "id": "7a356e11-f719-4dae-ae44-fa93f21ee6a0:none",
+        "lastModified": "2020-10-12T16:06:39.021+0000",
+        "sections": {},
+        "type": "edititem",
+        "uniqueType": "core.edititem",
+        "_links": {
+          "self": {
+            "href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none"
+          },
+          "item": {
+            "href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none/item"
+          },
+          "collection": {
+            "href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none/collection"
+          },
+          "modes": {
+            "href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none/modes"
+          }
+        }
+      }
+    ]
+  },
+  "_links": {
+    "self": {
+      "href": "http://{dspace-url}/server/api/core/edititems/search/findBySubmitter?uuid=a1b2c3d4-5678-90ab-cdef-1234567890ab"
+    }
+  },
+  "page": {
+    "size": 20,
+    "totalElements": 1,
+    "totalPages": 1,
+    "number": 0
+  }
+}
+```
+
+Parameters:
+* `uuid` (required): The UUID of the EPerson (submitter) whose edit items should be retrieved
+
+Return codes:
+* 200 OK - if the operation succeeds
+* 400 Bad request - if the uuid parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you don't have READ permission on the specified EPerson
+
+

endpoints.md

@@ -12,11 +12,14 @@
 * [/api/core/bundles](bundles.md)
 * [/api/core/metadatafields](metadatafields.md)
 * [/api/core/metadataschemas](metadataschemas.md)
+* [/api/core/edititems](edititems.md)
+* [/api/core/edititemmodes](edititemmodes.md)
 * [/api/core/epersons](epersons.md)
 * [/api/eperson/orcidqueues](orcidqueues.md)
 * [/api/eperson/orcidhistories](orcidhistories.md)
 * [/api/eperson/profiles](profiles.md)
 * [/api/core/groups](epersongroups.md)
+* [/api/core/groups/securitysettings/<entityType>](securitysettings-endpoint.md)
 * [/api/core/{model}/search](search-rels.md)
 * [/api/authn/login](authentication.md#Login)
 * [/api/authn/logout](authentication.md#Logout)

securitysettings-endpoint.md

@@ -0,0 +1,64 @@
+# Security Settings Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+DSpace has functionality to show or hide the metadata related with an item in order to manage the security related with
+this item. DSpace, also offers to the user the possible levels of security, to define for each metadata related with an
+entity type. These levels are configured in configuration files and returned to che client by an endpoint, based on the
+entity type requested. This contract describes this endpoint.
+
+## Security Settings Endpoint
+
+**GET /api/core/securitysettings/<EntityType>
+
+This endpoint will list all (REST supported) configurations defined in `dspace/config/modules/metadata-security.cfg`,
+based on an entity type. The configuration settings entries are embedded with a metadataSecurityDefault,
+metadataCustomSecurity and a self link, where metadataSecurityDefault is the fallback level of security, or the level of
+security for an EntityType, metadataCustomSecurity are all the configuration levels of the metadata related with an
+EntityType.
+
+The JSON response document is as follows
+
+```json
+{
+  "_embedded": {
+    "id": "securitysetting",
+    "type": "securitysetting",
+    "metadataSecurityDefault": [
+      2
+    ],
+    "metadataCustomSecurity": {
+      "dc.type": [
+        1, 2
+      ],
+      "dc.identifier.scopus": [
+        1
+      ],
+      "oairecerif.author.affiliation": [
+        0, 1
+      ],
+      "dc.identifier.isi": [
+        1, 2
+      ],
+      "dc.identifier.doi": [
+        1
+      ]
+    },
+    "_links": {
+      "self": {
+        "href": "/api/core/securitysettings"
+      }
+    }
+  }
+}
+
+
+```
+Attributes
+* metadataSecurityDefault: array with integers value of security configuration.
+* metadataCustomSecurity: a map with key value pairs, where key is the metadata name and value is an array with integers, representing the possible security configuration levels for that metadata.
+* type: string representing the type of the rest response.
+* id: string representing the type of the rest response.
+
+Return codes:
+* 200 OK - if the operation succeed.
+* 401 Unauthorized - if user is not authenticated.