Metadata spec for NCBI review
Updated 20211109 by @lathrops1
SEE COMMENTS IN BOLD
Updated 8 Nov
@lathrops1 This issue has been updated for:
- Review of creating metadata templates at the organization level
- How the templates are applied at the collection
This should be read in conjunction with the updated collection meta spec in #355 (closed) and the stying in #737 (closed)
We'd like to NCBI review so that we can proceed with development of the organisation template UI, its application to the collection, the collection metadata UI and writing of collection xml.
Metadata flow in the BCMS
This diagrams shows the flow for:
- creating metadata templates at the organization level
- how the templates are applied at the collection and book metadata level
- creating non-template metadata at the collection and book metadata level
- applying NCBI custom metadata rules
- processing and displaying metadata in the BCMS
PDF version: NCBI-Metadata-flow-20211117.pdf
I FIND THE DIAGRAM A BIT CONFUSING, SO PLEASE REFER TO COMMENTS BELOW TO THE NARRATIVE VERSION
Create an organization metadata template (Not for development in initial release)
Certain metadata fields for each organization are set once.
- publisher name
- publisher location
- all "permissions" fields (as currently defined in "permissions tab" in the metadata sheet)
- the wireframe shows an asterisks for all fields that are required in the form
- all fields copied to collections and books from the template are editable at the collection or book level.
NOTE: xml writing for all fields above are provided with queries in #355 (closed) -- NCBI can validate in one issue
Collection level
NOTE: See full spec with wireframes and collection-meta sheet in #355 (closed)
- When a collection is created by a Sys Admin within the organization:
- all template values are copied to the collection
- the
books-source-type
is automatically set toCollection
- the user defines the
books-source-type
for all wholebooks and chapter-processed books within the collection.
- After creation the metadata is displayed in the metadata modal, editable to the users with permissions (Sys Admin, Org admin, Editors added to the collection team).
- The user provides the remaining metadata in the UI and can apply certain fields to the book metadata of the collection members.
- The BCMS writes and the xml and applies this depending on the use case: collection.xml package; writing in chapter.xml files; sending to wholebook PDF conversion (APEX); sending to wholebook XML conversion (NCBI).
- NCBI Sys admins are notified when collection metadata has been edited so that they can republish any chapters within the collection members (see related issue *#807 (closed))
Chapter-processed book metadata level
In this use case, all book metadata is user created (i.e. there is no source file)
- When a Chapter-processed book is created, the template is applied depending on collection relevance and conversion workflow as shown above
- The
books-source-type
that was set at the collection level is automatically applied *If there is no collection, the user selects from the optionsdatabase
,book
ordocumentation
after the book is created. - book metadata is displayed in the book metadata modal, editable to the users with permissions (Sys Admin, Org admin, Editors).
- The
- The user provides the remaining metadata in the UI.
- Chapter is sent without any book metadata:
- To Word conversion
- To XML conversion
- To Apex/PDF conversion
- BCMS receives converted chapter xml package
- BCMS writes entire
book-meta
node into chapter.xml file - If book belongs to a collection, BCMS writes relevant
collection-meta
node into chapter.xml file - BCMS sends package to load to PMC
- NCBI Sys admins are notified when book metadata has been edited so that they can republish any chapters within the book (see related issue *#807 (closed))
Book metadata UI for chapter-process use case is pending update
Note
There is a current use case in PDF and XML workflows where chapter content being submitted by FTP also includes book-metadata (#694 (closed)) -- as agreed there this won't be supported in the initial release.
Wholebook book metadata level
XML workflow
Note: only the values publisher name
and publisher location
are applicable from the organization template
- When a wholebook is created, the template is applied depending on collection relevance as shown above
- The
books-source-type
that was set at the collection level is automatically applied - After book creation the user selects from the options
report
orbook
, if there is no related collection.
- The
- Wholebook package is sent to XML conversion with relevant book (and collection) metadata in the json file, as in XML spec #278 (comment 51578))
- After receiving the converted file the BCMS parses and displays only the fields that are required by BCMS settings (title, publication date, volume number) and those that do not display in the Preview. These are read-only, multiline text fields.
Book metadata UI for wholebook use case is pending update
PDF Workflow
UPDATE: This flow is not ready for review
The implementation here depends on whether the Permissions xml node created from the template is:
- sufficient only for passing information to Apex, or
- can be used "as is" by Apex and there is no expectation to update the UI for these values from the received converted xml file.
PER DISCUSSION, PDF WORKFLOW DEPENDS ON MORE THAN THAT - IT DEPENDS ON HOW TO SEND ALL NECESSARY METADATA VALUES WE CURRENT SEND, BEYOND PERMISSIONS.
UPDATING DOMAIN TOOL TITLE FIELD
TO BE DISCUSSED -
BOOKSHELF CURRENTLY KEEPS DOMAIN TOOL TITLE FIELD IN SYNC WITH THE FOLLOWING COMBINATION OF BOOK METADATA FIELDSIN THE XML:
TITLE: SUBTITLE, EDITION
ACCEPTANCE CRITERIA
SEE #776 (closed)
TO PASTE RELEVANT ONES IN THIS DESCRIPTION ONCE FINALIZED