diff --git a/docs/index.rst b/docs/index.rst index ba621e7..6b754d9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -221,12 +221,13 @@ Moderated Catalogues ================== Any catalogues can be declared as moderated. -In such a case, a Catalogue-Moderator must approve any submitted items to make them available to the other users of the catalogue. +This means that, a Catalogue-Moderator must approve any submitted items to make them available to the other users of the catalogue. In a moderated catalogue, an item can be in the following states: pending: - The item published by any allowed users but no Catalogue-Moderator has decided to approve or reject it; + The item published by any allowed author (a Catalogue-Editor or above) but not available to the other users of the catalogue. + A Catalogue-Moderator has to approve or reject it; approved: A Catalogue-Moderator has approved the item published by any allowed users; @@ -276,6 +277,42 @@ Messages can be sent both with an action which changes the status of the item or +The following table summarize the allowed/forbidden operations depending on: the role of the user and the state of the item. + +.. table:: + + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Operation | Item State | Roles | + + + +----------------------+--------------------------+------------------------------------------+-------------------+ + | | | Catalogue Moderator | Catalogue Admin/Manager | Catalogue Editor | Catalogue Member | + +=====================================+=============+======================+==========================+==========================================+===================+ + | List | | Yes all states | Yes all states | Yes only approved - All states if owner | Yes only approved | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Count | | Yes all states | Yes all states | Yes only approved - All states if owner | Yes only approved | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Create | | 403 Forbidden | Yes -> Pending | Yes -> Pending | 403 Forbidden | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Read | | Yes alla states | Yes all states | Yes only approved - All states if owner | Yes only approved | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Update | Pending | Yes -> Pending | 403 Forbidden | Yes if Author -> Pending | 403 Forbidden | + + +-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | | Rejected | Yes -> Pending | 403 Forbidden | Yes if Author -> Pending | 403 Forbidden | + + +-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | | Approved | 403 Forbidden | Yes -> Approved | Yes if Author -> Pending | 403 Forbidden | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Delete/Purge | Pending | Yes | Yes | Yes if Author | 403 Forbidden | + + +-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | | Rejected | Yes | Yes | Yes if Author | 403 Forbidden | + + +-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | | Approved | 403 Forbidden | Yes | Yes if Author | 403 Forbidden | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Approve a pending item | | Yes | 403 Forbidden | 403 Forbidden | 403 Forbidden | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Reject a pending item | | Yes | 403 Forbidden | 403 Forbidden | 403 Forbidden | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + | Message about an item in any state | | Yes | 403 Forbidden | Yes | 403 Forbidden | + +-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+ + Java Client ================== diff --git a/src/main/java/org/gcube/gcat/rest/Item.java b/src/main/java/org/gcube/gcat/rest/Item.java index 50223a3..09a257c 100644 --- a/src/main/java/org/gcube/gcat/rest/Item.java +++ b/src/main/java/org/gcube/gcat/rest/Item.java @@ -307,18 +307,24 @@ public class Item extends REST implements org.gcube.gcat.api.interf } /** - * The bulk delete API provides a way to delete all the times matching certain criteria - * (see Filtering Listing options). - * The operation returns immediately to the client and continues in background. - * There is no way to monitor or stop the running operation. + *

+ * The bulk delete API provides a way to delete all the items matching certain criteria + * (see Filtering Listing options). + * The operation returns immediately to the client and continues in background. + * There is no way to monitor or stop the running operation. + *

* - * When invoked with no arguments, it deletes all the items of the invoking user in the default - * CKAN organization for the current context. + *

+ * When invoked with no arguments, it deletes all the items of the invoking user in the default + * CKAN organization for the current context. + *

* - * If a Catalogue-Admins or above specifies the query parameter own_only=false - * it deletes all the items of all users for the CKAN organization for the current context. - * The service ignores the query parameter own_only=false if the requesting user is not - * Catalogue-Admins or above. + *

+ * If a Catalogue-Admin or above specifies the query parameter own_only=false + * it deletes all the items of all users for the CKAN organization for the current context. + * The service ignores the query parameter own_only=false if the requesting user is not + * Catalogue-Admin or above. + *

* *

* Please check the result using the items listing APIs to verify what you will delete. @@ -350,18 +356,24 @@ public class Item extends REST implements org.gcube.gcat.api.interf } /** - * The bulk purge API provides a way to completely remove all the times matching certain criteria - * (see Filtering Listing options). Please note that this action is not reversible. - * The operation returns immediately to the client and continues in background. - * There is no way to monitor or stop the running operation. + *

+ * The bulk purge API provides a way to completely remove all the items matching certain criteria + * (see Filtering Listing options). Please note that this action is not reversible. + * The operation returns immediately to the client and continues in background. + * There is no way to monitor or stop the running operation. + *

* - * When invoked with no arguments, it purges all the items of the invoking user in the default - * CKAN organization for the current context. + *

+ * When invoked with no arguments, it purges all the items of the invoking user in the default + * CKAN organization for the current context. + *

* - * If a Catalogue-Admins or above specifies the query parameter own_only=false, - * it purges all the items of all users for the CKAN organization for the current context. - * The service ignores the query parameter own_only=false if the requesting user is not - * Catalogue-Admins or above. + *

+ * If a Catalogue-Admin or above specifies the query parameter own_only=false, + * it purges all the items of all users for the CKAN organization for the current context. + * The service ignores the query parameter own_only=false if the requesting user is not + * Catalogue-Admin or above. + *

* *

* Please check the result using the items listing APIs to verify what you will purge. @@ -372,8 +384,10 @@ public class Item extends REST implements org.gcube.gcat.api.interf * with the query parameters purge=true. *

* - * @return 202 Accepted HTTP Status to indicate that the request has been properly take in charge. + * @return 202 Accepted HTTP Status to indicate that the request has been + * properly taken in charge.
* The operation will continue in background. + * * @throws WebServiceException if an error occurs. */ @PURGE @@ -384,6 +398,38 @@ public class Item extends REST implements org.gcube.gcat.api.interf return bulkDelete(true); } + /** + * + * @param id the name of the item to moderate + * @param json It contains the moderation action to perform on the item. + * + *

The format is the following

+ * + * 
+	 * 	{
+	 * 		"system:cm_item_status":"approved",
+	 * 		"message": "..."
+	 * 	}
+	 *
+ * + *

+ * The field system:cm_item_status can have + * the following values: approved or rejected, indicating the + * item's new status.
+ * It is possible to send an optional message together with the new status by adding + * the field message.
+ * This operation is available for Catalogue-Moderator only. + *

+ * + *

+ * Catalogue-Moderator and item author can send just a message to discuss + * the approval of the item by indicating the field message only. + *

+ * + * @return 202 Accepted HTTP Status to indicate that the request has been + * properly taken in charge.
+ * The operation will continue in background. + */ @POST @Path("/{" + ITEM_ID_PARAMETER + "}") @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)