Improving docs
This commit is contained in:
parent
a72dfe904e
commit
562ad114c3
|
|
@ -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
|
||||
==================
|
||||
|
|
|
|||
|
|
@ -307,18 +307,24 @@ public class Item extends REST<CKANPackage> 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.
|
||||
* <p>
|
||||
* 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.
|
||||
* </p>
|
||||
*
|
||||
* When invoked with no arguments, it deletes all the items of the invoking user in the default
|
||||
* CKAN organization for the current context.
|
||||
* <p>
|
||||
* When invoked with no arguments, it deletes all the items of the invoking user in the default
|
||||
* CKAN organization for the current context.
|
||||
* </p>
|
||||
*
|
||||
* If a Catalogue-Admins or above specifies the query parameter <em>own_only=false</em>
|
||||
* it deletes all the items of all users for the CKAN organization for the current context.
|
||||
* The service ignores the query parameter <em>own_only=false</em> if the requesting user is not
|
||||
* Catalogue-Admins or above.
|
||||
* <p>
|
||||
* If a Catalogue-Admin or above specifies the query parameter <em>own_only=false</em>
|
||||
* it deletes all the items of all users for the CKAN organization for the current context.
|
||||
* The service ignores the query parameter <em>own_only=false</em> if the requesting user is not
|
||||
* Catalogue-Admin or above.
|
||||
* </p>
|
||||
*
|
||||
* <p style="font-weight:bold;">
|
||||
* Please check the result using the items listing APIs to verify what you will delete.
|
||||
|
|
@ -350,18 +356,24 @@ public class Item extends REST<CKANPackage> 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.
|
||||
* <p>
|
||||
* 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.
|
||||
* </p>
|
||||
*
|
||||
* When invoked with no arguments, it purges all the items of the invoking user in the default
|
||||
* CKAN organization for the current context.
|
||||
* <p>
|
||||
* When invoked with no arguments, it purges all the items of the invoking user in the default
|
||||
* CKAN organization for the current context.
|
||||
* </p>
|
||||
*
|
||||
* If a Catalogue-Admins or above specifies the query parameter <em>own_only=false</em>,
|
||||
* it purges all the items of all users for the CKAN organization for the current context.
|
||||
* The service ignores the query parameter <em>own_only=false</em> if the requesting user is not
|
||||
* Catalogue-Admins or above.
|
||||
* <p>
|
||||
* If a Catalogue-Admin or above specifies the query parameter <em>own_only=false</em>,
|
||||
* it purges all the items of all users for the CKAN organization for the current context.
|
||||
* The service ignores the query parameter <em>own_only=false</em> if the requesting user is not
|
||||
* Catalogue-Admin or above.
|
||||
* </p>
|
||||
*
|
||||
* <p style="font-weight:bold;">
|
||||
* Please check the result using the items listing APIs to verify what you will purge.
|
||||
|
|
@ -372,8 +384,10 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
|
|||
* with the query parameters <em>purge=true</em>.
|
||||
* </p>
|
||||
*
|
||||
* @return <code>202 Accepted</code> HTTP Status to indicate that the request has been properly take in charge.
|
||||
* @return <code>202 Accepted</code> HTTP Status to indicate that the request has been
|
||||
* properly taken in charge.<br />
|
||||
* The operation will continue in background.
|
||||
*
|
||||
* @throws WebServiceException if an error occurs.
|
||||
*/
|
||||
@PURGE
|
||||
|
|
@ -384,6 +398,38 @@ public class Item extends REST<CKANPackage> 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.
|
||||
*
|
||||
* <p>The format is the following</p>
|
||||
*
|
||||
* <pre>
|
||||
* {
|
||||
* "system:cm_item_status":"approved",
|
||||
* "message": "..."
|
||||
* }
|
||||
* </pre>
|
||||
*
|
||||
* <p>
|
||||
* The field <code>system:cm_item_status</code> can have
|
||||
* the following values: <code>approved</code> or <code>rejected</code>, indicating the
|
||||
* item's new status.<br />
|
||||
* It is possible to send an optional message together with the new status by adding
|
||||
* the field <code>message</code>.<br />
|
||||
* This operation is available for Catalogue-Moderator only.
|
||||
* </p>
|
||||
*
|
||||
* <p>
|
||||
* Catalogue-Moderator and item author can send just a message to discuss
|
||||
* the approval of the item by indicating the field <code>message</code> only.
|
||||
* </p>
|
||||
*
|
||||
* @return <code>202 Accepted</code> HTTP Status to indicate that the request has been
|
||||
* properly taken in charge.<br />
|
||||
* The operation will continue in background.
|
||||
*/
|
||||
@POST
|
||||
@Path("/{" + ITEM_ID_PARAMETER + "}")
|
||||
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||
|
|
|
|||
Loading…
Reference in New Issue