Merge pull request #20 from 4Science/DS-3851

DS-3851 initial proposal for the workflow endpoints

claimedtasks.md

@@ -0,0 +1,70 @@
+# Claimed Taks Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+## Main Endpoint
+**/api/workflow/claimedtasks**   
+
+Not allowed. Only subset of claimed tasks can be retrieved using specific filters see below
+
+## Single Pool Task
+**/api/workflow/claimedtasks/<:id>**
+
+Provide details about a specific task in the pool. The JSON response document is as follow
+
+```json
+{
+    "id": 1,
+    "step": "editstep",
+    "action": "editaction",
+    "type": "claimedtask"
+}
+```
+
+Exposed links:
+* workflowitem: the workflowitem underlying the task
+* owner: the eperson that own the task
+
+### Linked entities
+#### workflowitem
+**/api/workflow/claimedtasks/<:id>/workflowitem** (READ-ONLY)
+
+It returns the underlying workflowitem holds by the task. See the [workflowitem endpoint for more info](workflowitems.md). This is a **read-only** endpoint, once the task is created the backend workflowitem cannot be changed.
+
+#### owner
+**/api/workflow/claimedtasks/<:id>/owner** (READ-ONLY)
+
+It returns the eperson that own the task. See the [eperson endpoint for more info](epersons.md). This is a **read-only** endpoint, once the task is claimed the owner cannot be changed. To unclaim a task see the DELETE method below
+
+### Search methods
+#### findByUser
+**/api/workflow/claimedtasks/search/findByUser?uuid=<:user-uuid>**
+
+It returns the tasks claimed by the specified user
+
+## POST Method (collection level)
+The creation of claimed tasks is managed by the underline workflow system. No methods are exposed to manually trigger such creation to avoid workflow hjack and inconsistency.
+
+## POST Method (single resource level)
+To perform a claimed task a POST request must be issued against the single claimed task URL
+/api/workflow/claimedtasks/:id
+using http request parameters to instruct the workflow action class about the specific command to perform approve, reject, add a score, etc. In some case other parameters must be specified too as for instance the reason parameter for the reject action
+
+| action | command options | parameter to trigger the command | additional parameters |
+| --- | --- | --- | --- |
+| editaction | approve | submit\_approve=true | _none_ |
+| editaction | reject | submit\_reject=true | reason=<text to send to the submitter> |
+| finaleditaction | approve | submit\_approve=true | _none_ |
+| selectrevieweraction | choose a reviewer | submit\_select\_reviewer\_<uuid>=true | no extra parameters needed but the primary parameter name define the selected eperson |
+| scorereviewaction |record the score | submit_score=true | score=<int value of the score> |
+
+## Return code
+* 204 No content is returned if the request succeed
+* 403 Not authorized if the task cannot be performed by the logged in user
+* 404 if the task is not longer available
+* 422 validation errors (e.g. no "reason" parameter provided)
+
+## DELETE Method 
+To unclaim a task it is sufficient to issue a DELETE request
+
+## Multipart POST Method
+Not allowed

polltasks.md

@@ -0,0 +1,66 @@
+# Pool Taks Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+## Main Endpoint
+**/api/workflow/pooltasks**   
+
+Not allowed. Only subset of pool tasks can be retrieved using specific filters see below
+
+## Single Pool Task
+**/api/workflow/pooltasks/<:id>**
+
+Provide details about a specific task in the pool. The JSON response document is as follow
+
+```json
+{
+    "id": 1,
+    "step": "editstep",
+    "action": "claimaction",
+    "type": "pooltask"
+}
+```
+
+Exposed links:
+* workflowitem: the workflowitem underlying the task
+* eperson: the eperson that can claim the task
+* group: the group that can claim the task
+
+### Linked entities
+#### workflowitem
+**/api/workflow/pooltasks/<:id>/workflowitem** (READ-ONLY)
+
+It returns the underlying workflowitem holds by the task. See the [workflowitem endpoint for more info](workflowitems.md). This is a **read-only** endpoint, once the task is created the backend workflowitem cannot be changed.
+
+#### eperson
+**/api/workflow/pooltasks/<:id>/eperson** (READ-ONLY)
+
+It returns the eperson that can claim the task. See the [eperson endpoint for more info](epersons.md). This is a **read-only** endpoint, once the task is created the backend eperson cannot be changed.
+
+#### group
+**/api/workflow/pooltasks/<:id>/group** (READ-ONLY)
+
+It returns the group of epersons that can claim the task. See the [group endpoint for more info](epersongroups.md). This is a **read-only** endpoint, once the task is created the backend group cannot be changed.
+
+
+### Search methods
+#### findByUser
+**/api/workflow/workflowitems/search/findByUser?uuid=<:user-uuid>**
+
+It returns the tasks available for the specified user
+
+## POST Method (collection level)
+The creation of pool tasks is managed by the underline workflow system. No methods are exposed to manually trigger such creation to avoid workflow hjack and inconsistency.
+
+## POST Method (single resource level)
+To claim a pool task a POST request must be issued against the single pool task URL
+/api/workflow/pooltasks/:id
+
+204 No content is returned if the request succeed
+403 Not authorized if the task cannot be claimed by the logged in user
+404 if the task is not longer available
+
+## DELETE Method 
+Not allowed. To reset a workflow it is possible to issue a DELETE against the [workflowitem endpoint](workflowitem.md)
+
+## Multipart POST Method
+Not allowed

workflowitems.md

@@ -0,0 +1,142 @@
+# WorkflowItem Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+## Main Endpoint
+**/api/submission/workflowitems**   
+
+Provide access to the workflowitems. It returns the list of existent workflowitems.
+
+Example: to be provided
+
+## Single Workflow Item
+**/api/submission/workflowitems/<:id>**
+
+Provide detailed information about a specific workflowitem. The JSON response document is as follow
+
+```json
+{
+  "id": 1911,
+  "lastModified": "2017-06-24T00:40:54.970+0000",
+  "step": "editstep",
+  "sections": {
+  	 "collection": "05457c63-b392-4629-a373-f2d66ee9ee33",
+  	 "traditional-page1": {
+  	 	"dc.title" : [{value: "Sample Workflow Item"}],
+  	 	"dc.contributor.author" : [
+  	 		{value: "Bollini, Andrea", authority: "rp00001", confidence: 600}
+  	 	]
+  	 },
+  	 "traditional-page2": {
+  	 	"dc.subject" : [{value: "Test"}, {value: "JSON"}, {value: "REST"}],
+  	 	"dc.description.abstract" : [
+  	 		{value: "This is a long multiline text\n This is a second line of the abstract"}
+  	 	]
+  	 },
+  	 "license": {
+  	 	acceptanceDate: "2017-06-24T00:40:54.970+0000",
+  	 	url: "http://dspace7.4science.it/api/core/bitstreams/8d33bdfb-e7ba-43e6-a93a-f445b7e8a1e2/content"
+  	 },
+  	 "uploads": [ 
+  	 	{
+  	 		metadata: {
+  	 			"dc.title" : [{value: "sample_file.pdf"}],
+  	 			"dc.description" : [{value: "Description of the sample file"}]
+  	 		},
+  	 		"sizeBytes": 8528,
+			"checkSum": {
+			    "checkSumAlgorithm": "MD5",
+			    "value": "9d8f0f9e369cf12159d47c146c499cf4"
+			},
+  	 		"url": "http://dspace7.4science.it/api/core/bitstreams/00001abf-b2e0-477a-99de-104db7cb6469/content",
+  	 		"accessConditions": [
+  	 			{
+  	 				"id": 123,
+	  	 			"name": "openaccess",
+	  	 			"groupUUID": "uuid-of-the-anonymous-group"
+  	 			},
+  	 			{
+  	 				"id": 126,
+	  	 			"name": "administrator",
+	  	 			"groupUUID": "uuid-of-the-administrator-group"
+  	 			},
+  	 			{
+  	 				"id": 127,
+	  	 			"name": "embargo",
+	  	 			"groupUUID": "1faf7c51-2a14-4826-b0b1-f1c1d2d82dd7",
+	  	 			"startDate": "2018-06-24T00:40:54.970+0000"
+  	 			},
+  	 			{
+  	 				"id": 128,
+	  	 			"name": "lease",
+	  	 			"groupUUID": "38ecd5ae-af12-4144-a276-81532e1679f8",
+	  	 			"endDate": "2017-12-24T00:40:54.970+0000"
+  	 			}
+  	 		]
+ 		}
+ 	]
+  	},
+  	 "cclicense": {
+  	 	"image-url": "https://i.creativecommons.org/l/by/4.0/88x31.png",
+  	 	"license-uri": "https://creativecommons.org/licenses/by/4.0/"
+  	 }
+  },
+  "type": "workflowitem"
+}
+```
+
+Similary  to the [Workspace Item](workspaceitems.md) the actual data of the inprogress submission are arranged in *sections* map following the sections configured in the submissionDefinition. This map is *open for extension*, each type of section will expose a different JSON structure. See the [out-of-box submission section types](submissionsection-types.md) page for details. An additional step attribute containing the id of the reached step in the workflow is present
+
+Exposed links:
+* collection: the collection where the inprogress submission will be created
+* item: the item that hold the submission data
+* submissionDefinition: the [submission definition](submissiondefinitions.md) used by this inprogress submission
+
+### Linked entities
+#### collection
+**/api/submission/workflowitems/<:id>/collection** (READ-ONLY)
+
+Example: to be provided
+
+It returns the collection where the inprogress submission is occuring. This is a **read-only** endpoint, once the inprogress submission is created the collection cannot be changed directly. Specific section, like the enhanced select-collection section planned for DSpace7 will be able to alter the collection manipulating the *sections* data.
+
+#### item
+**/api/submission/workflowitems/<:id>/item** (READ-ONLY)
+
+Example: to be provided
+
+It returns the backend item holds by the submission. See the [item endpoint for more info](items.md). This is a **read-only** endpoint, once the inprogress submission is created the backend item cannot be changed. Update to the backend item will be reflected automatically on the inprogress submission but are not subject to the submission validation, i.e. they correspond to administrative edits
+
+#### submissionDefinition
+**/api/submission/workflowitems/<:id>/submissionDefinition** (READ-ONLY)
+
+Example: to be provided
+
+It returns the submission definition used by the inprogress submission. See the [submission definitions endpoint for more info](submissiondefinitions.md). This is a **read-only** endpoint. 
+The submission definition used by the inprogress submission is derived from the inprogress submission attributes. In the default implementation the definition is derived from the collection where the submission is created and is updated if it changes. 
+Please note that this endpoint is not strictly necessary as you can currently retrieve the same definition using [/api/config/submissiondefinitions/search/findByCollection?uuid=<:workspaceitem-collection-uuid>](submissiondefinitions.md#findByCollection) but it allows the client to find the submissionDefinition embedded in the workspaceitem without the need to make a separate call. 
+In addition, it allows in future to change the 1:1 association between collections and submissionDefinition without breaking the client
+
+### Search methods
+#### findBySubmitter
+**/api/submission/workflowitems/search/findBySubmitter?uuid=<:submitter-uuid>**
+
+It returns the workflowitems created by the specified submitter
+
+## POST Method
+To create a workflowitem, i.e. to start a workflow, a workspaceitem must be posted to the workflowitems resource collection endpoint (/api/submission/workflowitems).
+The workspaceitem must be supplied as URI in the request body using the text/uri-list content-type
+If succeed a 201 code will be returned and the new state of the workflowitem serialized in the body.
+If fails the following status code are expected
+403 Unauthorized - if the loggedin user is not the submitter of the workspaceitem
+422 Unprocessable Entity - if the workspace is not yet ready to be send through the workflow (i.e. there are validation errors)
+
+## Multipart POST Method
+Multipart POST request will typically result in the creation of a new file in the section identified by the name of the variable used for the upload (uploads is the default name of the user uploaded content). The process will be managed by the implementation bind with the identified section.
+If succeed a 201 code will be returned and the new state of the workflowitem serialized in the body
+
+## DELETE Method 
+Reset a workflow sending back the item to the workspace regardless to the step reached.
+
+204 No content - if the operation succeed
+403 Unauthorized - if you are not loggedin as an administrator
+404 Not found - if the workflow doesn't longer exist