diff --git a/itemfilters.md b/itemfilters.md new file mode 100644 index 00000000..5655ee42 --- /dev/null +++ b/itemfilters.md @@ -0,0 +1,211 @@ +# Item Filter Endpoints +[Back to the list of all defined endpoints](endpoints.md) + +This endpoint contains the various logical item filters. + +## Main Endpoint +**/api/config/itemfilters** + +List all the available item filters in the system. + +```json +{ + "_embedded" : { + "itemfilters" : [ { + "id" : "a-common-or_statement", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/a-common-or_statement" + } + } + }, { + "id" : "always_true_filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/always_true_filter" + } + } + }, { + "id" : "dc-identifier-uri-contains-doi_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/dc-identifier-uri-contains-doi_condition" + } + } + }, { + "id" : "demo_filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/demo_filter" + } + } + }, { + "id" : "doi-filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/doi-filter" + } + } + }, { + "id" : "driver-document-type_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/driver-document-type_condition" + } + } + }, { + "id" : "example-doi_filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/example-doi_filter" + } + } + }, { + "id" : "has-at-least-one-bitstream_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/has-at-least-one-bitstream_condition" + } + } + }, { + "id" : "has-bitstream_filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/has-bitstream_filter" + } + } + }, { + "id" : "has-one-bitstream_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/has-one-bitstream_condition" + } + } + }, { + "id" : "in-outfit-collection_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/in-outfit-collection_condition" + } + } + }, { + "id" : "is-archived_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/is-archived_condition" + } + } + }, { + "id" : "is-withdrawn_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/is-withdrawn_condition" + } + } + }, { + "id" : "item-is-public_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/item-is-public_condition" + } + } + }, { + "id" : "openaire_filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/openaire_filter" + } + } + }, { + "id" : "simple-demo_filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/simple-demo_filter" + } + } + }, { + "id" : "title-contains-demo_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/title-contains-demo_condition" + } + } + }, { + "id" : "title-starts-with-pattern_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/title-starts-with-pattern_condition" + } + } + }, { + "id" : "type-equals-dataset_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/type-equals-dataset_condition" + } + } + }, { + "id" : "type-equals-journal-article_condition", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/type-equals-journal-article_condition" + } + } + }, { + "id" : "type_filter", + "type" : "itemfilter", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters/type_filter" + } + } + } ] + }, + "_links" : { + "self" : { + "href" : "http://localhost/api/config/itemfilters?size=30" + } + }, + "page" : { + "size" : 30, + "totalElements" : 21, + "totalPages" : 1, + "number" : 0 + } +} +``` + +Status codes: +* 200 OK - if the operation succeed +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions. Only administrators + +## Single Item Filter +**/api/config/itemfilters/<:id>** + +Status codes: +* 200 OK - if the operation succeed +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions. Only administrators +* 404 Not found - if the itemfilter doesn't exist + diff --git a/ldnservices.md b/ldnservices.md new file mode 100644 index 00000000..303940d6 --- /dev/null +++ b/ldnservices.md @@ -0,0 +1,851 @@ +# LDN Notify Services Endpoints +[Back to the list of all defined endpoints](endpoints.md) + +## Inbox Endpoint +**/api/ldn/inbox** + +Active only if config ldn.enabled is true. This is the inbox of Notification json +(see org.dspace.app.ldn.model.Notification model): when accepted an instance +of LdnMessageEntity is created and stored. See documentation at: +https://wiki.lyrasis.org/pages/viewpage.action?pageId=319815713 +where json Notification examples are shared into a ready-to-use PostMan collection. + +```json +{ + "@context": [ + "https://www.w3.org/ns/activitystreams", + "https://purl.org/coar/notify" + ], + "actor": { + "id": "https://research-organisation.org", + "name": "Research Organisation", + "type": "Organization" + }, + "context": { + "id": "http://localhost:4000/handle/123456789/1119", + "ietf:cite-as": "https://doi.org/10.5555/12345680", + "type": "sorg:AboutPage", + "url": { + "id": "https://another-research-organisation.org/repository/datasets/item/201203421/data_archive.zip", + "mediaType": "application/zip", + "type": [ + "Article", + "sorg:Dataset" + ] + } + }, + "id": "urn:uuid:2f4ec582-109e-4952-a94a-b7d7615a8c69", + "object": { + "as:object": "newValue", + "as:relationship": "somethingElse", + "as:subject": "https://research-organisation.org/repository/item/201203/421/", + "id": "http://localhost:4000/handle:123456789/1119", + "type": "Relationship" + }, + "origin": { + "id": "https://research-organisation.org/repository", + "inbox": "2f4ec582-109e-4952-a94a-b7d7615a8c69", + "type": "Service" + }, + "target": { + "id": "https://another-research-organisation.org/repository", + "inbox": "https://another-research-organisation.org/inbox/", + "type": "Service" + }, + "type": [ + "Announce", + "coar-notify:RelationshipAction" + ] +} +``` +Return codes: +* 200 OK - if the operation succeed, respose echoes the same id in the request +* 422 Unprocessable Entity - if Error parsing request body +* 500 Forbidden is not possible because it is restricted to authenticated users + +## Main Endpoint +**/api/ldn/ldnservices** + +Provide access to the notifyservices (DBMS based). List all the LDN notify services + +A sample can be found at https://api7.dspace.org/server/#/server/api/ldn/ldnservices + +Return codes: +* 200 OK - if the operation succeed +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden is not possible because it is restricted to authenticated users + +## Single LDN Notify Service +**/api/ldn/ldnservices/<:id>** + +```json +{ + "id" : 1, + "name" : "service name", + "description" : "service description", + "url" : "https://service-name.org/about", + "ldnUrl" : "https://service-name.org/ldn-inbox", + "enabled" : true, + "score" : "0.375", + "lowerIp" : "192.168.0.1", + "upperIp" : "192.168.0.5", + "notifyServiceInboundPatterns" : + [ + { + "pattern" : "patternA", + "constraint" : "itemFilterA", + "automatic" : false + }, + { + "pattern" : "patternB", + "constraint" : "itemFilterB", + "automatic" : true + } + ], + "notifyServiceOutboundPatterns" : [ { + "pattern" : "patternC", + "constraint" : "itemFilterC" + } ], + "type" : "notifyservice", + "_links" : { + "self" : { + "href" : "http://localhost/api/ldn/ldnservices/1" + } + } +} +``` + +Status codes: +* 200 OK - if the operation succeed +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden is not possible because it is restricted to authenticated users +* 404 Not found - if no LDN notify service exists with such id + + Attributes +* id: numerical identificator assigned by the rest to the service itself +* name: a short name associated to the service +* description: a description for the service, i.e. the reason for the service +* url: the URL for users to check out more information about the service +* ldnUrl: the URL of the LDN Inbox +* enabled: This proeprty is a simple boolean, it defines if the service is selected as one of the active ones +* score: This property defines to the safety score assigned by the user +* lowerIp: This property defines to the lowerIp of the ip range +* upperIp: This property defines to upperIp of the ip range +* inboundPatterns: an array that contains inbound pattern defined by 3 properties: + * pattern: the defining pattern name for the pattern itself + * constraint: a filter put in place during the pattern creation + * automatic: The automatic property is a boolean property that defines the behaviour during an item archiving operation; + * automatic:TRUE = all the patterns flagged with the true value for the automatic property, for which a positive response is returned, a notification on the corresponding service + * automatic:FALSE = all the patterns flagged with the false value for the automatic property, needs to be explicitly declared from the user during a submission in the related submission section COAR Notify + +* outboundPatterns: an array that contains inbound pattern defined by 3 properties: + * pattern: the defining pattern name for the pattern itself + * constraint: a filter put in place during the pattern creation + +## Creating a new LDN notify service +**POST /api/ldn/ldnservices** + +Only administrator users can create LDN notify service. The content-type is JSON. An example JSON can be seen below: + +```json +{ + "name": "service name", + "description": "service description", + "url": "https://service-name.org/about", + "ldnUrl": "https://service-name.org/ldn-inbox", + "score" : "0.765", + "enabled" : true, + "lowerIp" : "192.168.0.1", + "upperIp" : "192.168.0.5", + "notifyServiceInboundPatterns": + [ + {"pattern":"patternA","constraint":"itemFilterA","automatic":true}, + {"pattern":"patternB","constraint":null,"automatic":false} + ], + "notifyServiceOutboundPatterns": + [ + {"pattern":"patternC","constraint":"itemFilterC"} + ] +} +``` + +Status codes: +* 201 Created - if the operation succeed +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions. Only administrators +* 404 Not found - if no LDN notify service exists with such id +* 422 Unprocessable Entity - if Error parsing request body + +## PATCH + +### Add +PATCH /api/ldn/ldnservices/<:id> + +to add name to ldn notify service + +```json +[ + { + "op": "add", + "path": "/name", + "value": "service name" + } +] +``` + +to add description to ldn notify service + +```json +[ + { + "op": "add", + "path": "/description", + "value": "service description" + } +] +``` + +to add ldnUrl to ldn notify service + +```json +[ + { + "op": "add", + "path": "/ldnurl", + "value": "https://service-name.org/ldn-inbox" + } +] +``` + +to add url to ldn notify service + +```json +[ + { + "op": "add", + "path": "/url", + "value": "https://service-name.org/about" + } +] +``` + +to add score to ldn notify service + +```json +[ + { + "op": "add", + "path": "/score", + "value": "0.89" + } +] +``` + +to add inboundPatterns to ldn notify service + +-adding object to the last, this array isn't sorted so, not supported adding to index like "notifyServiceInboundPatterns[index]" + +```json +[ + { + "op": "add", + "path": "notifyServiceInboundPatterns/-", + "value": {"pattern":"patternA","constraint":"itemFilterA","automatic":"false"} + } +] +``` + +to add outboundPatterns to ldn notify service + +-adding object to the last, this array isn't sorted so, not supported adding to index like "notifyServiceOutboundPatterns[index]" + +```json +[ + { + "op": "add", + "path": "notifyServiceOutboundPatterns/-", + "value": {"pattern":"patternA","constraint":"itemFilterA"} + } +] +``` + +to add pattern to specific inboundPattern of ldn notify service + +```json +[ + { + "op": "add", + "path": "notifyServiceInboundPatterns[0]/pattern", + "value": "patternA" + } +] +``` + +to add constraint to specific inboundPattern of ldn notify service + +```json +[ + { + "op": "add", + "path": "notifyServiceInboundPatterns[0]/constraint", + "value": "itemFilterA" + } +] +``` + + +to add pattern to specific outboundPattern of ldn notify service + +```json +[ + { + "op": "add", + "path": "notifyServiceOutboundPatterns[0]/pattern", + "value": "patternA" + } +] +``` + +to add constraint to specific outboundPattern of ldn notify service + +```json +[ + { + "op": "add", + "path": "notifyServiceOutboundPatterns[0]/constraint", + "value": "itemFilterA" + } +] +``` + +### Replace + +to update the name of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/name", + "value": "service name" + } +] +``` + +to update the description of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/description", + "value": "service description" + } +] +``` + +to update the ldnUrl of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/ldnurl", + "value": "https://service-name.org/ldn-inbox" + } +] +``` + +to update the score of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/score", + "value": "0.97" + } +] +``` + +to update the url of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/url", + "value": "https://service-name.org/about" + } +] +``` + +to update enabled of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/enabled", + "value": false + } +] +``` + +to update the lowerIp of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/lowerIp", + "value": "192.168.0.1" + } +] +``` +to update the upperIp of ldn notify service + +```json +[ + { + "op": "replace", + "path": "/upperIp", + "value": "192.168.0.5" + } +] +``` + +to replace all inboundPatterns of ldn notify service, +if value contains an empty array all inboundPatterns will be removed + +```json +[ + { + "op": "replace", + "path": "notifyServiceInboundPatterns", + "value": [{"pattern":"patternC","constraint":"itemFilterC","automatic":"false"}, {"pattern":"patternD","constraint":"itemFilterD","automatic":"false"}] + } +] +``` + +to replace inboundPattern of ldn notify service at specific index + +```json +[ + { + "op": "replace", + "path": "notifyServiceInboundPatterns[0]", + "value": {"pattern":"patternD","constraint":"itemFilterD","automatic":"true"} + } +] +``` + +to replace all outboundPatterns of ldn notify service, +if value contains an empty array all outboundPatterns will be removed + +```json +[ + { + "op": "replace", + "path": "notifyServiceOutboundPatterns", + "value": [{"pattern":"patternC","constraint":"itemFilterC"}, {"pattern":"patternD","constraint":"itemFilterD"}] + } +] +``` + +to replace outboundPattern of ldn notify service at specific index + +```json +[ + { + "op": "replace", + "path": "notifyServiceOutboundPatterns[0]", + "value": {"pattern":"patternD","constraint":"itemFilterD"} + } +] +``` + +to replace pattern of specific inboundPattern of ldn notify service + +```json +[ + { + "op": "replace", + "path": "notifyServiceInboundPatterns[1]/pattern", + "value": "patternB" + } +] +``` + +to replace constraint of specific inboundPattern of ldn notify service + +```json +[ + { + "op": "replace", + "path": "notifyServiceInboundPatterns[1]/constraint", + "value": "itemFilterB" + } +] +``` + +to replace automatic of specific inboundPattern of ldn notify service + +```json +[ + { + "op": "replace", + "path": "notifyServiceInboundPatterns[1]/automatic", + "value": "true" + } +] +``` + +to replace pattern of specific outboundPattern of ldn notify service + +```json +[ + { + "op": "replace", + "path": "notifyServiceOutboundPatterns[1]/pattern", + "value": "patternB" + } +] +``` + +to replace constraint of specific outboundPattern of ldn notify service + +```json +[ + { + "op": "replace", + "path": "notifyServiceOutboundPatterns[0]/constraint", + "value": "itemFilterA" + } +] +``` + +### Remove + +to remove name or ldnUrl or lowerIp or upperIp from ldn notify service + +```json +[ + { + "op": "remove", + "path": "/name" + } +] +``` + +```json +[ + { + "op": "remove", + "path": "/ldnurl" + } +] +``` + +```json +[ + { + "op": "remove", + "path": "/lowerIp" + } +] +``` + +```json +[ + { + "op": "remove", + "path": "/upperIp" + } +] +``` + +status codes: +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions. Only administrators +* 404 Not found - if the LDN Notify Service doesn't exist (or was already deleted) +* 422 Unprocessable Entity - name and ldnUrl fields are mandatory and can't be removed + + +to remove description value from ldn notify service + +```json +[ + { + "op": "remove", + "path": "/description" + } +] +``` + +to remove url value from ldn notify service + +```json +[ + { + "op": "remove", + "path": "/url" + } +] +``` + +to remove score value from ldn notify service + +```json +[ + { + "op": "remove", + "path": "/score" + } +] +``` + +to remove all inboundPatterns of ldn notify service + +```json +[ + { + "op": "remove", + "path": "notifyServiceInboundPatterns" + } +] +``` + +to remove inboundPattern from ldn notify service at specific index + +```json +[ + { + "op": "remove", + "path": "notifyServiceInboundPatterns[0]" + } +] +``` + +to remove all outboundPatterns of ldn notify service + +```json +[ + { + "op": "remove", + "path": "notifyServiceOutboundPatterns" + } +] +``` + +to remove outboundPattern from ldn notify service at specific index + +```json +[ + { + "op": "remove", + "path": "notifyServiceOutboundPatterns[1]" + } +] +``` + +to remove constraint from specific inboundPattern of ldn notify service + +```json +[ + { + "op": "remove", + "path": "notifyServiceInboundPatterns[0]/constraint" + } +] +``` + +to remove constraint from specific outboundPattern of ldn notify service + +```json +[ + { + "op": "remove", + "path": "notifyServiceOutboundPatterns[0]/constraint" + } +] +``` + +Patch Status codes: +* 200 OK - if the operation succeeded +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions. Only administrators +* 404 Not found - if the LDN Notify Service doesn't exist (or was already deleted) + +## Deleting LDN notify service + +**DELETE /api/ldn/ldnservices/<:id>** + +Delete LDN notify service. + +* 204 No content - if the operation succeed +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions. Only administrators +* 404 Not found - if the LDN notify service doesn't exist (or was already deleted) + +## Search methods +### findByLdnUrl +**/api/ldn/ldnservices/search/byLdnUrl?ldnUrl=<:ldnUrl>** + +Parameters: +* The `ldnUrl` ldnUrl of the LDN notify service + +A sample search would be `/server/api/ldn/ldnservices/search/byLdnUrl?ldnUrl=service_ldn_url' + +```json +{ + "id" : 1, + "name" : "service name one", + "description" : "service description one", + "url" : "https://service-one.org/about", + "ldnUrl" : "https://service-one.org/ldn-inbox", + "score" : "0.57", + "enabled" : true, + "lowerIp" : "192.168.0.1", + "upperIp" : "192.168.0.5", + "notifyServiceInboundPatterns" : + [ + { + "pattern" : "patternA", + "constraint" : "itemFilterA", + "automatic" : false + } + ], + "notifyServiceOutboundPatterns" : [ { + "pattern" : "patternB", + "constraint" : "itemFilterB" + } ], + "type" : "notifyservice", + "_links" : { + "self" : { + "href" : "http://localhost/api/ldn/ldnservices/1" + } + } +} +``` + +Return codes: +* 200 OK - if the operation succeed +* 400 Bad Request - if the ldnUrl parameter is missing or invalid +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden is not possible because it is restricted to authenticated users + +### findByInboundPattern +**/api/ldn/ldnservices/search/byInboundPattern?pattern=<:pattern>** + +Parameters: +* The `pattern` the inbound pattern of the LDN notify service + +A sample search would be `/server/api/ldn/ldnservices/search/byInboundPattern?pattern=request-review' + +```json +{ + "_embedded" : { + "ldnservices" : [ { + "id" : 1, + "name" : "service name one", + "description" : "service description one", + "url" : "https://service.ldn.org/about", + "ldnUrl" : "https://service.ldn.org/inbox", + "score" : "0.675", + "enabled" : false, + "lowerIp" : "192.168.0.1", + "upperIp" : "192.168.0.5", + "notifyServiceInboundPatterns" : [ { + "pattern" : "request-review", + "constraint" : "itemFilterA", + "automatic" : false + } ], + "notifyServiceOutboundPatterns" : [ ], + "type" : "ldnservice", + "_links" : { + "self" : { + "href" : "http://localhost/api/ldn/ldnservices/1" + } + } + }, { + "id" : 2, + "name" : "service name two", + "description" : "service description two", + "url" : "https://service-two.org/about", + "ldnUrl" : "https://service-two.org/ldn-inbox", + "score" : "0.34", + "enabled" : true, + "lowerIp" : "192.168.0.1", + "upperIp" : "192.168.0.5", + "notifyServiceInboundPatterns" : [ { + "pattern" : "request-review", + "constraint" : "itemFilterA", + "automatic" : false + } ], + "notifyServiceOutboundPatterns" : [ ], + "type" : "ldnservice", + "_links" : { + "self" : { + "href" : "http://localhost/api/ldn/ldnservices/2" + } + } + } ] + }, + "_links" : { + "self" : { + "href" : "http://localhost/api/ldn/ldnservices/search/byInboundPattern?pattern=request-review" + } + }, + "page" : { + "size" : 20, + "totalElements" : 2, + "totalPages" : 1, + "number" : 0 + } +} +``` + +Return codes: +* 200 OK - if the operation succeed +* 400 Bad Request - if the pattern parameter is missing or invalid +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden is not possible because it is restricted to authenticated users + + +## Notify Requests for specific item + +### notifyrequests +**/api/ldn/notifyrequests/<:itemUUID>** + +Parameters: +* The `itemUUID` is the uuid of the item + +A sample search would be `/server/api/ldn/notifyrequests/_itemuuid_' + +```json +{ + "notifyStatus": [ + { + "serviceName": "NS", + "serviceUrl": "2f4ec582-109e-4952-a94a-b7d7615a8c69", + "offerType": "Request", + "status": "REJECTED" + } + ], + "itemuuid": "_itemuuid_", + "type": "notifyrequests", + "_links": { + "self": { + "href": "http://localhost:8080/server/api/ldn/notifyrequests/ldn/org.dspace.app.rest.model.NotifyRequestStatusRest@31a86e42" + } + } +} +``` + +Return codes: +* 200 OK - if the operation succeed +* 400 Bad Request - if the itemuuid parameter is missing or invalid +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden is not possible because it is restricted to authenticated users + diff --git a/qualityassuranceevents.md b/qualityassuranceevents.md index 58a50a64..6799e12a 100644 --- a/qualityassuranceevents.md +++ b/qualityassuranceevents.md @@ -46,7 +46,7 @@ Attributes * the *topic* attribute is the name of the topic of the event * the *status* attribute is one of (ACCEPTED, REJECTED, DISCARDED, PENDING) * the *eventDate* attribute is the timestamp of the event reception -* the *message* attribute is a json object which structure depends on the source and on the topic of the event. When the "topic" type is +* the *message* attribute is a json object which structure depends on the source and on the topic of the event. When the source is "openaire" and the "topic" type is * ENRICH/MISSING/PID and ENRICH/MORE/PID: fills `message.type` with the type of persistent identifier (doi, pmid, etc.) and `message.value` with the corresponding value * ENRICH/MISSING/ABSTRACT: fills `message.abstract` * ENRICH/MISSING/PROJECT and ENRICH/MORE/PROJECT: fills `acronym`, `code`, `funder`, `fundingProgram`, `jurisdiction` and `title` @@ -109,17 +109,17 @@ Return codes: ## Search methods ### Get qualityassuranceevents by a given topic -**GET /api/integration/qualityassuranceevents/search/findByTopic?topic=:target-key[&size=10&page=0]** +**GET /api/integration/qualityassuranceevents/search/findByTopic?topic=:topic-key[&size=10&page=0]** -It returns the list of qa events from a specific topic +It returns the list of qa events from a specific topic, eventually filtered by the target they refer to The supported parameters are: * page, size [see pagination](README.md#Pagination) -* topic: mandatory, the key associated with the requested topic +* topic: mandatory, the key associated with the requested topic. Please note that the topic could contain the uuid of a specific target item to restrict the qa events. See the note about the [qa topic id](qualityassurancetopics.md#get-single-topic) Return codes: * 200 OK - if the operation succeed -* 400 Bad Request - if the topic parameter is missing or invalid +* 400 Bad Request - if the topic parameter is missing Provide paginated list of the qa events available. @@ -184,3 +184,19 @@ Return codes: ### To replace a related item Replacing a related item will require deleting the related association and creating a new association hereafter + +### Get qualityassuranceevents created by the current user +**GET /api/integration/qualityassuranceevents/search/findByCurrentUser?target=<:item-uuid>[&size=10&page=0]** + +It returns the list of qa events created from the current user + +The supported parameters are: +* target: mandatory. The uuid of the item target of the returned quality assurance events +* page, size [see pagination](README.md#Pagination) + +Return codes: +* 200 OK - if the operation succeed +* 400 Bad Request - if the target parameter is missing or is not a UUID +* 422 Unprocessable Entity - it the target parameter doesn't resolve to a valid item + +Provide paginated list of the qa events for the specified target item created by the current user. An empty page is returned for unauthenticated users diff --git a/qualityassurancesources.md b/qualityassurancesources.md index a5f88d6c..946a9824 100644 --- a/qualityassurancesources.md +++ b/qualityassurancesources.md @@ -23,7 +23,7 @@ Provide access to the Quality Assurance sources. It returns the list of the Qual Attributes: * lastEvent: the date of the last update from the specific Quality Assurance source * totalEvents: the total number of quality assurance events provided by the Quality Assurance source -* id: is the identifier to use in GET Single Source +* id: is the identifier to use in GET Single Source. It can be composed of a source alias followed by colon : and the target uuid when the qa source data are focused on a specific item Return codes: * 200 OK - if the operation succeed @@ -48,3 +48,42 @@ Return codes: * 401 Unauthorized - if you are not authenticated * 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access * 404 Not found - if the source doesn't exist + +## Search methods +### Get qualityassurancesources by a given target +**/api/integration/qualityassurancesources/search/byTarget** + +It returns the list of qa sources that have events related to the specific target. + +```json +... +_embedded: { + qualityassurancesources: + [ + + { + id: "openaire:", + type: "qualityassurancesource", + totalEvents: "3" + }, + { + id: "coar-notify:", + type: "qualityassurancesource", + totalEvents: "2" + }, + ... + ] +} +``` + +The supported parameters are: +* page, size [see pagination](README.md#Pagination) +* source: mandatory, the name associated with a specific source + +Return codes: +* 200 OK - if the operation succeed +* 400 Bad Request - if the topic parameter is missing or invalid +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access + + diff --git a/qualityassurancetopics.md b/qualityassurancetopics.md index f3020d41..401a22cd 100644 --- a/qualityassurancetopics.md +++ b/qualityassurancetopics.md @@ -2,11 +2,10 @@ Provide access to the Quality Assurance topics. A topic represents a specific type of event (such as a missing abstract can be). **GET /api/integration/qualityassurancetopics** -It returns the list of the Quality Assurance Broker topics. +This method is not implemented as we haven't a use case that require to iterate over all the qa topics regardless of their source. Please use the search/bySource method instead. -```json -[ +```json { key: "ENRICH!MORE!PID", lastEvent: "2020/10/09 10:11 UTC", @@ -25,6 +24,7 @@ Attributes: * lastEvent: the date of the last update from Quality Assurance Broker * totalEvents: the total number of quality assurance events provided by Quality Assurance Broker for this topic + Return codes: * 200 OK - if the operation succeed * 401 Unauthorized - if you are not authenticated @@ -36,11 +36,14 @@ Return codes: Provide detailed information about a specific Quality Assurance Broker topic. The JSON response document is as follow ​ ```json - { - key: "ENRICH!MORE!PID", - lastEvent: "2020/10/09 10:11 UTC", - totalEvents: "33" - } + +{ + id: "openaire:ENRICH!MORE!PID", + type: "qualityassurancetopic", + name: "ENRICH/MORE/PID", + lastEvent: "2020/10/09 10:11 UTC", + totalEvents: 33 +} ``` Return codes: @@ -53,7 +56,32 @@ Return codes: ### Get qualityassurancetopics by a given source **/api/integration/qualityassurancetopics/search/bySource** -It returns the list of qa topics from a specific source +It returns the list of qa topics from a specific source. Provide paginated list of the qa topics available. + +```json +... +_embedded: { + qualityassurancetopics: + [ + + { + id: "openaire:ENRICH!MORE!PID", + type: "qualityassurancetopic", + name: "ENRICH/MORE/PID", + lastEvent: "2020/10/09 10:11 UTC", + totalSuggestions: "33" + }, + { + id: "openaire:ENRICH!MISSING!ABSTRACT", + type: "qualityassurancetopic", + name: "ENRICH/MISSING/ABSTRACT", + lastEvent: "2020/10/09 10:11 UTC", + totalSuggestions: "21" + }, + ... + ] +} +``` The supported parameters are: * page, size [see pagination](README.md#Pagination) @@ -65,4 +93,14 @@ Return codes: * 401 Unauthorized - if you are not authenticated * 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access -Provide paginated list of the qa topics available. + +### Get qualityassurancetopics by a given target +**GET /api/integration/qualityassurancetopics/search/byTarget?target=:item-uuid&source=:source-id** + +It returns the list of qa topics (from a specific source) to a specific targeted item. + +Return codes: +* 200 OK - if the operation succeed +* 400 Bad Request - if the target or the source parameters are missing or invalid (the target is not an uuid) +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access diff --git a/submissioncoarnotifyconfigs.md b/submissioncoarnotifyconfigs.md new file mode 100644 index 00000000..ed995652 --- /dev/null +++ b/submissioncoarnotifyconfigs.md @@ -0,0 +1,88 @@ +# Submission COAR Notify Endpoints +[Back to the list of all defined endpoints](endpoints.md) + +Provide access to the existing configurations for the submission COAR Notify panel. +The SubmissionCOARNotifyConfig list which request patterns can be selected during the submission. + +In the first implementation, a single configuration named *coarnotify* is expected as these configurations were set at the site level. +Introducing an endpoint to manage a collection of configurations we open the door to future extension where different setups can be used for different kind of submissions (theses, technical reports, journal articles, etc.) + +## Main Endpoint +**/api/config/submissioncoarnotifyconfigs** + +Returns the list of configured COAR notify patterns to be offered during the submission. + +```json +{ + "_embedded" : { + "submissioncoarnotifyconfigs" : [ { + "id" : "coarnotify", + "patterns" : [ { + "pattern" : "request-review", + "multipleRequest" : true + }, { + "pattern" : "request-endorsement", + "multipleRequest" : true + }, { + "pattern" : "request-ingest", + "multipleRequest" : false + } ], + "type" : "submissioncoarnotifyconfig", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/submissioncoarnotifyconfigs/coarnotify" + } + } + } ] + }, + "_links" : { + "self" : { + "href" : "http://localhost/api/config/submissioncoarnotifyconfigs" + } + }, + "page" : { + "size" : 20, + "totalElements" : 1, + "totalPages" : 1, + "number" : 0 + } +} +``` + +Status codes: +* 200 OK - if the operation succeeded +* 401 Unauthorized - if you are not authenticated. The endpoint is restricted to authenticated users + + +## Single COAR notify +**/api/config/submissioncoarnotifyconfigs/<:coarnotify-name>** + +*:coarnotify-name* is initially hard-coded to *coarnotify* + +Provide detailed information about a specific COAR notify. +```json +{ + "id" : "coarnotify", + "patterns" : [ { + "pattern" : "request-review", + "multipleRequest" : true + }, { + "pattern" : "request-endorsement", + "multipleRequest" : true + }, { + "pattern" : "request-ingest", + "multipleRequest" : false + } ], + "type" : "submissioncoarnotifyconfig", + "_links" : { + "self" : { + "href" : "http://localhost/api/config/submissioncoarnotifyconfigs/coarnotify" + } + } +} +``` + +Status codes: +* 200 OK - if the operation succeeded +* 401 Unauthorized - if you are not authenticated. The endpoint is restricted to authenticated users +* 404 Not found - if the requested submission COAR Notify Config doesn't exist \ No newline at end of file diff --git a/workspaceitem-data-coarnotify.md b/workspaceitem-data-coarnotify.md new file mode 100644 index 00000000..e972727b --- /dev/null +++ b/workspaceitem-data-coarnotify.md @@ -0,0 +1,85 @@ +# WorkspaceItem data of COAR Notify sectionType +[Back to the definition of the workspaceitems endpoint](workspaceitems.md) + +The section data represents the data about the selected COAR Notify patterns to request + +```json +[ + { + "endorsement": [ 1, 2, 3 ], + "review": [ 6 ] + } +] +``` + +the attributes represent the pattern that will be requested to the selected service(s), the value of each attribute is the array of the id of the selected services. +The above example shows a submission where three services (id 1, 2, 3) were selected to request an endorsement and one service (id 6) has been selected to request a review. + +## Patch operations +The PATCH method expects a JSON body according to the [JSON Patch specification RFC6902](https://tools.ietf.org/html/rfc6902) + +Each successful Patch operation will return a HTTP 200 CODE with the updated workspaceitem as body. + +If the requested path doesn't match a valid pattern for the current configuration or a specified service id doesn't exist 422 Unprocessable Entity will be returned. + +### Add +To specify which services request for a specific pattern + +```json +[ + { + "op": "add", + "path": "/sections/coarnotify/review/-", + "value": [1, 2, 6] + } +] +``` + +### Replace +To replace the 2nd previous selected service for the endorsement pattern + +```json +[ + { + "op": "replace", + "path": "/sections/coarnotify/endorsement/1", + "value": 4 + } +] +``` + +Please note that the number in the path (/1) represent the idx of the previous selected services, the number in the value represent the id of the new selected service. The above path applied to the initial sample +```json +[ + { + "endorsement": [ 1, 2, 3 ], + "review": [ 6 ] + } +] +``` + +will modify the section data as follow + +```json +[ + { + "endorsement": [ 1, 4, 3 ], + "review": [ 6 ] + } +] +``` + +### Remove +It is possible to remove a previously selected service for a specific pattern (review) +`curl --data '{[ { "op": "remove", "path": "/sections/coarnotify/endorsement/0"}]' -X PATCH ${dspace7-url}/api/submission/workspaceitems/1` + +The result applied to the previous example will be + +```json +[ + { + "endorsement": [4, 3 ], + "review": [ 6 ] + } +] +``` \ No newline at end of file