Project

General

Profile

task #7012

Updated by Andreas Kohlbecker about 5 years ago

Design and establish an partially automated workflow with Pensoft. 

 ---- 
 *The below concept is based on a discussion with    Teodor Georgiev (preprint@pensoft.net) from Pensoft Publishers at the TDWG 2017 conference.* 

 Interaction workflow between Phycobank and Pensoft Publishers 
 ============================================================== 

 Phycobank is a registration for algal names and types. Phycobank will actually create registration for whole nomenclatural acts which can encompass 0 - 1 new scientific names and 0 - n typifications for new or existing names. The different types of typifications cover isosyntype, isotype, lectotype, neotype, paralectotype, paraneotype, paratype, second step lectotype, second step neotype & syntype. 


 Phycobank aims in establishing a workflow with publishers. Phycobank aims in realizing this interaction for the first time be done with Pensoft Publishers. 

 This document describes the basic principles of the interaction between Phycobank and Pensoft Publishers as discussed during the "Night at the museum" event at the TDWG conference 2017 (Andreas Kohlbecker, a.Kohlbecker@bgbm.org; Teodor Georgiev, preprint@pensoft.net).  

 ## persistent registration identifier  

 For interaction with registration web service persistent registration identifier (`{phycobankID}`) needs to be used in the request URI as url-encoded path element: `{phycobankID-urlencoded} = urlencode(http://phycobank.org/{integer})` 

 ## Authentication/authorization 

 The Publisher will need to be authenticate at Phycobank via HTTP-Basic authentication. Authorization at Phycobank is established on base of the OAuth 2.0 protocol.  

 ## Users and roles 

 Phycobank distinguishes to roles which are relevant for the registratin process: 

 * **Submitter** 
 * **Curation**  

 In Phycobank the user initiating a registration is called **submitter**. Only the **submitter** of a registration can change it. (However the *curation* of Phycobank can also modify registration data.) There is always only one submitter per registration. Pensoft will therefore be the **submitter** of all registrations created on behalf of the authors which do submit publications to Pensoft witch contain nomenclatural acts for algae names.  

 ## Registration workflow states 

 * `PREPARATION`: Initial state of a new registration 
 * `CURATION`: Once the the editing phase of a nomenclatural act is completed, the registration record (new scientific     name, typifications) are passed to the curation. This status indicates that a registration is in the curatorial process. As result of the process (for details see paragraph below) the status may be changed to `READY`, `REJECTED` (sever unresolvable problem with the nomenclatural act) or even back to `PREPARATION` (request to fix incomplete, invalid data) 
 * `READY`: The registration record can be published. The publication will immediately happen as soon as the publication date (, doi and pages detail) is set in the data.   
 * `PUBLISHED`: Unmodifiable final state of a successful registration. All related data is locked and can no longer be modified. 
 * `REJECTED`: Unmodifiable final state of a failed registration. All related data is locked and can no longer be modified. 

 ## Curatorial process in the registration office 

 The data curator of the registration office will manually validate the registration data once the status is set to `CURATION`. The curation may result in one or more of the following actions: 

 * Minor problems in the data are corrected by the curator. This includes for example minor orthographic corrections of a new name to be published. **TODO @HENNING: please complete**. 
 * Severe problems like that the exact same name has already been published before will lead to rejection of the registration which is expressed by the state `REJECTED` 
 * The registration state is progressed to `READY` in case of successful validation. 
 * The state returns to `PREPARATION` in case of problems which can't be solved by the curator without feedback from the author team. The curator will add a curatorial annotation to the registration record with information or questions for the author team. **TODO: This needs to be discussed** #8103 

 ## Initialization of the registration process 

 The initialization of the registration process is triggered by the publisher by sending nomenclatural act data to the registration system via HTTP POST request: 

 Upon being authenticated the publisher can send the data of the nomenclatural act (Name, Types, Reference ) to a web service endpoint ( ==> #8086). The transport schema of the data (TCS, CDM, ...) is being discussed at the moment internally at Phycobank. ==> #8085 

 * web service URLs:  
  * POST: http://api.phycobank.org/phycobank/registration/ 
  * PUT: http://api.phycobank.org/phycobank/registration/{phycobankID-urlencoded}  

 As response to the submission the publisher will receive a response object (==> #8086) which can contain: 

 * An HTTP error code (400) with a detailed error message in case the submitted data was causing a problem in the phycobank system. 
 * The persistent identifier (http://phycobank.org/{integer}) for the nomenclatural act. The identifier is not made public at this point. 
 * The current status of the registration. Initially this is `PREPARTATION` 

 ## Receiving messages from phycobank during the edit and curation process 

 The submitted registration record will undergo a manual curation process which may result in a notifications on the registration record. Notifications may report invalidity of the submitted data and thus may be requests for improving data, fixing problems in the submitted nomenclatural act.  

 ~~Prospective service endpoint (#7270):~~ rejected, see #7935 

 * http://api.phycobank.org/phycobank/registration/{phycobankID-urlencoded}/messages 
 * Response content type: json 
 * Response content: A list of all messages associated with the registration record sorted by time in ascending order. 
 * authorization required 

 ## Requesting for the status of a registration record 

 * see #7927 (commit:ebbad31) 
 * HTTP-GET: http://api.phycobank.org/phycobank/registration/identifier/{phycobankID-urlencoded}/status.json 
 * NO authorization required 

 **TODO** Can we get rid of the `identifier/` in the service URL? We could allow for {uuid} and    {phycobankID-urlencoded} in the same place. 

 **response data model** 

 * The webservice responds with the current status which is one of: 
     * CURATION 
     * PREPARATION 
     * PUBLISHED 
     * READY 
     * REJECTED 

 response model ( ==> #8087): 

 ~~~json 
 { 
     "registrationId" : "{Registration.identifier}" 
     "status": "{Registration.status}" 
 } 
 ~~~ 


 Once the curator accepts the submitted nomenclatural act the registration status will be set to `READY`. Now the submitter can release the registration by making use the following webservice.  


 ## Publishing a registration identifier 

 In order to publish the registration of the nomenclatural act the publisher needs to submit the **publication date**, **DOI** and the **pages detail** to phycobank. The same use same web service endpoint and schema as for updating submissions is being used to the publication step. 

 Once all this information is successfully submitted the registration record can potentially change it's status to 'PUBLISHED'. This will immediately happen if the status is 'READY'. It is not guaranteed that the curation process is finished when publishing details are received, in these cases the registration becomes only public once the curator sets the registration status to 'READY'. The persistent Phycobank identifier will only be resolvable once the registration is on state 'PUBLISHED'. Therefore the publisher could postpone the publication of the article until the registration record in the registration is on state 'READY', otherwise the publication would contain a unresolvable identifier. (This issue may require further discussion!) 

 HTTP-PUT: http://api.phycobank.org/phycobank/registration/{phycobankID-urlencoded} 

 Request data which triggers a registration which is READ to change the status to PUBLISHED: 

 * **publicationDate** : the ISO 8601 date (JJJJ-MM-TT) of the actual publication of the article. 
 * **pages** : detail information on the pages covering the published article 
 * **doi** 

 ## Workflow as sequence diagrams 

 ![](submission and publication with curation.png)

Back