Skip to content

Commit 9dbc1f9

Browse files
tdonohuetdonohue
authored
Merge pull request #330 from 4Science/task/main/DURACOM-447
[DSpace-CRIS] Administrative Edit of archived items via submission form and security configuration for metadata visibility (Rest Contract)
2 parents 168bb5e + b5b2ab6 commit 9dbc1f9

4 files changed

Lines changed: 270 additions & 0 deletions

File tree

‎edititemmodes.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# EditItemMode Endpoints
2+
[Back to the list of all defined endpoints](endpoints.md)
3+
4+
## Single EditItemMode
5+
**/api/core/edititemmodes/<:item-uuid>:<:mode-name>**
6+
7+
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.
8+
9+
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.
10+
11+
The endpoint uses a composite identifier `{itemUUID}:{modeName}` where:
12+
- `itemUUID` - The UUID of the item being queried
13+
- `modeName` - The name of the edit mode (e.g., "FULL", "OWNER", "INVESTIGATOR")
14+
15+
The JSON response document is as follows:
16+
```json
17+
{
18+
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab:OWNER",
19+
"name": "OWNER",
20+
"label": null,
21+
"submissionDefinition": "person-edit",
22+
"type": "edititemmode",
23+
"uniqueType": "core.edititemmode",
24+
"_links": {
25+
"self": {
26+
"href": "http://{dspace-url}/server/api/core/edititemmodes/a1b2c3d4-5678-90ab-cdef-1234567890ab:OWNER"
27+
}
28+
}
29+
}
30+
```
31+
32+
**Response fields:**
33+
- `id`: Composite identifier in format `{itemUUID}:{modeName}`
34+
- `name`: The mode name (matches the second part of the ID)
35+
- `label`: Optional human-readable label for UI display (typically null)
36+
- `submissionDefinition`: Name of the submission definition from `item-submission.xml` that defines the editing form/workflow for this mode
37+
38+
Return codes:
39+
* 200 OK - if the mode exists and is configured for the item's entity type
40+
* 400 Bad request - if the composite ID format is invalid (must be `{uuid}:{modeName}`)
41+
* 401 Unauthorized - if you are not authenticated
42+
* 404 Not found - if the item doesn't exist or the mode is not configured for the item's entity type
43+
44+
**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‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# EditItem Endpoints
2+
[Back to the list of all defined endpoints](endpoints.md)
3+
4+
## Single EditItem
5+
**/api/core/edititems/<:id>:<:MODE>**
6+
7+
Provide detailed information about a specific edititem. The JSON response document is as follow
8+
```json
9+
{
10+
"id":"7a356e11-f719-4dae-ae44-fa93f21ee6a0:FIRST",
11+
"lastModified":"2020-10-12T16:06:39.021+0000",
12+
"sections":{
13+
"titleAndIssuedDate":{
14+
"dc.title":[
15+
{
16+
"value":"Title item",
17+
"language":null,
18+
"authority":null,
19+
"confidence":-1,
20+
"place":0
21+
}
22+
],
23+
"dc.date.issued":[
24+
{
25+
"value":"2010-06-18",
26+
"language":null,
27+
"authority":null,
28+
"confidence":-1,
29+
"place":0
30+
}
31+
]
32+
}
33+
},
34+
"type":"edititem",
35+
"uniqueType": "core.edititem"
36+
}
37+
```
38+
Return codes:
39+
* 200 OK - if the operation succeed
40+
* 401 Unauthorized - if you are not authenticated
41+
* 403 if you are not logged in with sufficient permissions to view the edititem
42+
* 404 Not found - if the edititem or MODE doesn't exist
43+
44+
45+
## Patch operations
46+
The PATCH method expects a JSON body according to the [JSON Patch specification RFC6902](https://tools.ietf.org/html/rfc6902)
47+
48+
### Add
49+
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
50+
51+
`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}}]'
52+
53+
### Remove
54+
It is possible to remove a specific metadatavalue if the metadata is defined in the submissionDefinition of current MODE
55+
`curl --data '[{ "op": "remove", "path": "/sections/traditionalpageone/dc.subject/0"}]' -X PATCH ${dspace7-url}/api/core/edititems/<:id>:<:MODE>`
56+
57+
## Find available modes
58+
**/api/core/edititems/search/findModesById?uuid=<:id>**
59+
60+
Provide detailed information about edit item modes available to current user for Item having uuid passed as input parameter.
61+
The JSON response document is as follow
62+
```json
63+
{
64+
"_embedded": {
65+
"edititemmodes": [
66+
{
67+
"id": "FULL",
68+
"name": "FULL",
69+
"label": null,
70+
"submissionDefinition": "publication-edit",
71+
"type": "edititemmode",
72+
"uniqueType": "core.edititemmode",
73+
"_links": {
74+
"self": {
75+
"href": "https://{dspace-cris-backend-url}/server/api/core/edititemmodes/FULL"
76+
}
77+
}
78+
}
79+
]
80+
},
81+
"_links": {
82+
"self": {
83+
"href": "http://{dspace-cris-backend-url}/server/api/core/edititems/search/findModesById?uuid=9880d9e1-5441-4e14-a6e8-6cf453bc25f9"
84+
}
85+
},
86+
"page": {
87+
"size": 20,
88+
"totalElements": 1,
89+
"totalPages": 1,
90+
"number": 0
91+
}
92+
}
93+
```
94+
Return codes:
95+
* 200 OK - if the operation succeed
96+
* 400 Bad request - if the id parameter is missing or invalid
97+
* 401 Unauthorized - if you are not authenticated
98+
99+
## Find edit items by submitter
100+
**/api/core/edititems/search/findBySubmitter?uuid=<:submitter-uuid>**
101+
102+
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.
103+
104+
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}`.
105+
106+
**Note:** This endpoint requires READ permission on the specified EPerson. It retrieves all archived items where the submitter field matches the provided UUID.
107+
108+
The JSON response document is as follows:
109+
```json
110+
{
111+
"_embedded": {
112+
"edititems": [
113+
{
114+
"id": "7a356e11-f719-4dae-ae44-fa93f21ee6a0:none",
115+
"lastModified": "2020-10-12T16:06:39.021+0000",
116+
"sections": {},
117+
"type": "edititem",
118+
"uniqueType": "core.edititem",
119+
"_links": {
120+
"self": {
121+
"href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none"
122+
},
123+
"item": {
124+
"href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none/item"
125+
},
126+
"collection": {
127+
"href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none/collection"
128+
},
129+
"modes": {
130+
"href": "http://{dspace-url}/server/api/core/edititems/7a356e11-f719-4dae-ae44-fa93f21ee6a0:none/modes"
131+
}
132+
}
133+
}
134+
]
135+
},
136+
"_links": {
137+
"self": {
138+
"href": "http://{dspace-url}/server/api/core/edititems/search/findBySubmitter?uuid=a1b2c3d4-5678-90ab-cdef-1234567890ab"
139+
}
140+
},
141+
"page": {
142+
"size": 20,
143+
"totalElements": 1,
144+
"totalPages": 1,
145+
"number": 0
146+
}
147+
}
148+
```
149+
150+
Parameters:
151+
* `uuid` (required): The UUID of the EPerson (submitter) whose edit items should be retrieved
152+
153+
Return codes:
154+
* 200 OK - if the operation succeeds
155+
* 400 Bad request - if the uuid parameter is missing or invalid
156+
* 401 Unauthorized - if you are not authenticated
157+
* 403 Forbidden - if you don't have READ permission on the specified EPerson
158+
159+

‎endpoints.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,14 @@
1212
* [/api/core/bundles](bundles.md)
1313
* [/api/core/metadatafields](metadatafields.md)
1414
* [/api/core/metadataschemas](metadataschemas.md)
15+
* [/api/core/edititems](edititems.md)
16+
* [/api/core/edititemmodes](edititemmodes.md)
1517
* [/api/core/epersons](epersons.md)
1618
* [/api/eperson/orcidqueues](orcidqueues.md)
1719
* [/api/eperson/orcidhistories](orcidhistories.md)
1820
* [/api/eperson/profiles](profiles.md)
1921
* [/api/core/groups](epersongroups.md)
22+
* [/api/core/groups/securitysettings/<entityType>](securitysettings-endpoint.md)
2023
* [/api/core/{model}/search](search-rels.md)
2124
* [/api/authn/login](authentication.md#Login)
2225
* [/api/authn/logout](authentication.md#Logout)

‎securitysettings-endpoint.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Security Settings Endpoints
2+
[Back to the list of all defined endpoints](endpoints.md)
3+
4+
DSpace has functionality to show or hide the metadata related with an item in order to manage the security related with
5+
this item. DSpace, also offers to the user the possible levels of security, to define for each metadata related with an
6+
entity type. These levels are configured in configuration files and returned to che client by an endpoint, based on the
7+
entity type requested. This contract describes this endpoint.
8+
9+
## Security Settings Endpoint
10+
11+
**GET /api/core/securitysettings/<EntityType>
12+
13+
This endpoint will list all (REST supported) configurations defined in `dspace/config/modules/metadata-security.cfg`,
14+
based on an entity type. The configuration settings entries are embedded with a metadataSecurityDefault,
15+
metadataCustomSecurity and a self link, where metadataSecurityDefault is the fallback level of security, or the level of
16+
security for an EntityType, metadataCustomSecurity are all the configuration levels of the metadata related with an
17+
EntityType.
18+
19+
The JSON response document is as follows
20+
21+
```json
22+
{
23+
"_embedded": {
24+
"id": "securitysetting",
25+
"type": "securitysetting",
26+
"metadataSecurityDefault": [
27+
2
28+
],
29+
"metadataCustomSecurity": {
30+
"dc.type": [
31+
1, 2
32+
],
33+
"dc.identifier.scopus": [
34+
1
35+
],
36+
"oairecerif.author.affiliation": [
37+
0, 1
38+
],
39+
"dc.identifier.isi": [
40+
1, 2
41+
],
42+
"dc.identifier.doi": [
43+
1
44+
]
45+
},
46+
"_links": {
47+
"self": {
48+
"href": "/api/core/securitysettings"
49+
}
50+
}
51+
}
52+
}
53+
54+
55+
```
56+
Attributes
57+
* metadataSecurityDefault: array with integers value of security configuration.
58+
* 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.
59+
* type: string representing the type of the rest response.
60+
* id: string representing the type of the rest response.
61+
62+
Return codes:
63+
* 200 OK - if the operation succeed.
64+
* 401 Unauthorized - if user is not authenticated.

0 commit comments

Comments
 (0)
⚡