Design and establish an partially automated workflow with Pensoft.

Interaction workflow between Phycobank and Pensoft Publishers¶

• Table of contents
• Interaction workflow between Phycobank and Pensoft Publishers
  • persistent registration identifier
  • Authentication/authorization
  • Users and roles
  • Registration workflow states
  • Curatorial process in the registration office
  • Initialization of the registration process
  • Data scope and granularity
    • Name
    • Typifications
      • Specimen types
      • Name types
  • Receiving messages from Phycobank during the edit and curation process
  • Requesting for the status of a registration record
  • Publishing a registration identifier
  • Workflow as sequence diagram
  • Teleconference on July 7th 2019
  • Open Questions

The below concept is based on a discussion with Teodor Georgiev (preprint@pensoft.net) from Pensoft Publishers at the TDWG 2017 conference. This original concept has been reconsidered and was refined during a teleconference on July 7th 2019

Phycobank is a repository for registration of algal names and types according to the International Code of Nomenclature for algae, fungi, and plants (ICN). 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 with Pensoft Publishers.

he basic principles of the interaction between Phycobank and Pensoft Publishers as described in this document have been discussed during the "Night at the museum" event at the TDWG conference 2017 (Andreas Kohlbecker, a.kohlbecker@bgbm.org; Teodor Georgiev, preprint@pensoft.net). The current state of this concept is more elaborated and detailed in contrast to the outcome of the discussion in Ottawa on October, 2017 which has been sent to preprint@pensoft.net on Oktober 10th 2017

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 authenticate at the Phycobank registration webservice via HTTP-Basic authentication. Authorization at Phycobank is established on base of the OAuth 2.0 protocol.

Users and roles¶

Phycobank distinguishes two roles which are relevant for the registration process:

• Submitter: The user initiating a registration is called submitter. Only the submitter of a registration can modify the related 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.
• Curation: The curation of Phycobank can also modify registration data as long the registration is not yet published.

Registration workflow states¶

• PREPARATION: Initial state of a new registration
• CURATION: Once 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 this process (for details see paragraph below) the status may be changed to READY, REJECTED (severe unsolvable 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 process 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, atomize specimen data, if necessary; add missing data (e.g. publication date of basionym reference).
• 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 model of the data is currently being developed ==> #8085. For an brief overview on the required data and its granularity, please see the paragraph Data scope and granularity below

• web service URLs:
  • HTTP-POST: http://api.phycobank.org/phycobank/registration/
  • HTTP-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 and according registration is not made public at this point.
• The current status of the registration. Initially this is PREPARATION

Data scope and granularity¶

(For a detailed discussion on this topic please see #8085)

Pyhcobank is a registration for nomenclatural acts. There are two general types of acts to be distinguished:

1. New name + one or more typifications (The new name is the typified name in this case)
2. One or more typification for an name which has previously been published in an other publication.

(Required fields are marked with an asterisk * in the below listings)

Name¶

A name can have different roles in a nomenclatual act:

1. it is the name being newly published
2. it is the name for which a typification is published, in this case the name is the typified name (specimen types and name types)
3. it is used in a typification as type for another name, in this case the name is the type name (name types).
4. it related to a name used in the cases 1) to 3) as basionym, replaced synonym, validated name or orthographcally corrected name.

• genusOrUninomial*:
• specificEpithet*:
• rank*:
• nameType*: (="ICNAFP"),
• nomenclaturalReference*:
• citationDetail*:
  
• nameRelationships: (relations to other name which are basionym, replaced synonym, validated name or orthographcally corrected name.)

Typifications¶

Specimen types¶

• summary text*: e.g.
  • C Ghana 141/1961. “Southwest Ghana. Fresh water (a small stream in bamboo thicket between the villages Agona and Nsuaem, Loc. No. 12). 9.III.1961.”
  • NMW C90.12.179 “River Chigara, Sierra Leone”
• type status*: (holotype, lectotype, ...)
• kind of unit*: (="Specimen")
• record basis*: (="PreservedSpecimen")
• collection code* : Index Herbariorum Code (C, BRM, B, BM or BP etc.)
• accession number*: e.g. C90.12.179
• typified name*: (a reference to the typified name)

Name types¶

• type status*: (e.g. lectotype, original designation, ...)
• typified name*: (a reference to the typified name)
• conserved type: [true|false]
• rejected type: [true|false]
• not designated type: [true|false]
• type name*: (a reference to the typified name)
• citation detail*:

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

For a new concept see #8103

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):

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

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.

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 in state 'PUBLISHED'. Therefore the publisher could consider to 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.

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 diagram¶

Teleconference on July 7th 2019¶

Attendees: Andreas Kohlbecker, Teodor Gregoriev and Plamen Pankov from Pensoft Publishers

Data granularity at Pensoft

The data on the nomenclatural acts if available in basically two different granularities. The granularity depends on the workflow in which the journal is processed at Pensoft.

• Zookeys, Mycokeys, (Phytokeys? ,) ... , have rather low granularity (-> taxon name + status) example: https://mycokeys.pensoft.net/article/35682/download/xml/
• Biodiversity Journal BDJ has higher granularity (details on typification, etc ...) You can check an example of a paper (although is on Dipter) with new species description: https://bdj.pensoft.net/article/29553/download/xml/:

Excerpt from the BDJ Example:

<tp:treatment-sec sec-type="materials"><title>Materials</title><list list-type="alpha-lower" list-content="occurrences"><list-item><p><bold>Type status:</bold><named-content content-type="dwc:typeStatus" xlink:type="simple">Holotype</named-content>. <bold>Occurrence:</bold> occurrenceDetails: <named-content content-type="dwc:occurrenceDetails" xlink:type="simple"><ext-link ext-link-type="uri" xlink:href="http://janzen.sas.upenn.edu" xlink:type="simple">http://janzen.sas.upenn.edu</ext-link></named-content>; catalogNumber: <named-content content-type="dwc:catalogNumber" xlink:type="simple">DHJPAR0007297</named-content>; recordedBy: <named-content content-type="dwc:recordedBy" xlink:type="simple">D.H. Janzen, W. Hallwachs, & Ruth Franco</named-content>; individualID: <named-content content-type="dwc:individualID" xlink:type="simple">DHJPAR0007297</named-content>; individualCount: <named-content content-type="dwc:individualCount" xlink:type="simple">1</named-content>; sex: <named-content content-type="dwc:sex" xlink:type="simple">male</named-content>; lifeStage: <named-content content-type="dwc:lifeStage" xlink:type="simple">adult</named-content>; preparations: <named-content content-type="dwc:preparations" xlink:type="simple">pinned</named-content>; otherCatalogNumbers: <named-content content-type="dwc:otherCatalogNumbers" xlink:type="simple">ASTAT069-06 ,04-SRNP-13432, BOLD:ABZ0529</named-content>

All XMLs and the respective data can be fetched from here: http://arphahub.com/about/OAI-PMH

Identifier workflow with Zoobank:

Zoobank uses persitent ID in the form of http://www.zoobank.org/NomenclaturalActs/{uuid}
Pensoft issues the uuid to be used in the Zoobank identifier and submits the uuid to the registration.

Workflow proposal for interaction of Pensoft with PhycoBank:

Pensoft uses placeholders in the journal data which can be filled with the PhycoBank ID once submitted to the publisher.

1 step registration process:

1. Pensoft sends all data on the nomenclatural act to PhycoBank together with the scheduled publication date.
2. PhycoBank returns the PhycoBank identifier
3. The placeholder in the article is replaced with the PhycoBank ID
4. PhycoBank sets the Registration status to PUBLISHED by the day of the planned publication date.

2 step registration process (optional and under discussion)

This process includes a feedback mechanism from PhycoBank to Pensoft by which the registration can notify the publisher on severe problems in the nomencaltural act. Generally the publication date as planned by Pensoft is 5 days in the future from the day when the nomenclatural act is submitted to PhycoBank. The curation of the registration system theoretically has 4 days to review the submission and to give feedack to the publisher on potential problems in the nomenclatural act. In case of severe problems Pensoft could consider postponing the publication and asking the authors for fixing the problem.

Further steps:

• PhycoBank will provide user credentials for Pensoft to test the manual data entry as submitter into the PhycoBank registration system. DONE
• Pensoft (Teodor G.) will discuss with the technical staff possibilities of using feedback from the registration system to verify the nomenclatural acts to be published. Submission of a invalid name or typification will result in a warning issued by PhycoBank. This warning could be used to postpone the publication and to ask the authors for correction of the invalid data.

Open Questions¶

• How to deal with new related names? Create blocking registrations?
  • does the publisher need to deal with blocking registrations explicitely or is this been managed behind the scenes for him?
• Discuss: If the object is Multimedia or a strain -> no automatic submission (because this is a different workflow for >5% of the types?
• How is data exchanged between Pensoft and Mycobank?
• What is the level of granularity at which Pensoft can deliver data?

The UML sequence diagram of the workflow is located in the PhycoBank github repository: digital publisher workflow - webservices.xmi