TOC chapter ingest details are not available in BCMS
(updated 30 October by @lathrops1 proposed edits / comments in BOLD CAPS)
Workflow for creating, processing and publishing a table of contents in chapter-processed books
- User creates a chapter-processed book in the organization or organization/collection
- The book inherits settings from the relevant template which includes defaults for the TOC.
- The user changes the settings when creating the book if necessary.
- Once the book is created the TOC has an "unpublished" status. Users can open the "TOC" modal where they will see guidance on the "Live" tab. This is in line with current development.
Book manager with amended TOC button, top right
TOC modal open in unpublished state
- The user uploads source files in the UI or by FTP
- The source files are converted to xml
- After conversion the book components are listed in the correct section (front/body/back) and the components in the body are listed in the order specified in the settings. If the ordering value is missing for component this is shown with the "TOC?" icon. THE RULES / WORKFLOW FOR THIS TOC? ICON ARE NOT COMPLETELY FLESHED OUT IN A USABLE WAY, BUT WE DON'T WANT THIS TO BE A BLOCKER FOR THIS ISSUE TO START - I WILL CREATE A SEPARATE ISSUE
- When one or more chapters are published, this action triggers the creation of the toc.xml file according to the specified settings.
- sys admin can download this file from the UI (note: the Download button is inactive prior to the file being created)
- This toc.xml file is saved and will be updated when more chapters within the book are published, or when the TOC settings 'Group chapters into parts' or 'Order chapters by' OR BOOK / COLLECTION METADATA are changed and user reloads -- (See #807 (closed)).
- At 10 pm ET the following steps take place for any toc.xml file that has been created or updated:
- a) write the current book metadata into the toc.xml file
- b) If the book belongs to a collection, write the current collection metadata into the toc.xml file -- Not in testing release 1 Dec
- c) package according to chapter xml loading spec, this excludes the cover which is sent separately (#751 (closed))
- d) run agreement API checks (#481 (closed)) and release checks (#435 (closed)) as done for chapters.
- The toc status is "publishing" until the kafka notification is received:
- "Publishing failed" status - in this case errors are shown in the UI
- "Published" status - in this case the live URL send in the notification is shown in the UI (with errors of severity type "warning" AND "QUERY").
- NOTIFICATION OF THE TOC INGEST AND PUBLISHING STATUS IS SENT TO USERS -- Not in testing release 1 Dec
- If the status is "Publishing failed", NCBI SYS ADMIN OR EDITOR resolves these:
- in the BCMS by changing a setting that's linked to domain update
- in the BCMS by editing collection or book metadata
- IN THE BCMS BY DOWNLOADING, EDITING UPLOADING, RETRIGGERING SOURCE BOOK PARTS
- BY NOTIFYING NCBI OR COKO DEVELOPERS OUTSIDE OF BCMS if the errors relate to NCBI / COKO-software issue
- for all cases above, users can select the "Update published version" button to manually trigger another load to PMC session.
IF SIGNIFICANT SOFTWARE ISSUE REMAIN AT POINT OF DEPLOYMENT OTHER WORKAROUND SCENARIOS MUST BE CONSIDERED WITHIN THE BCMS
Additional wireframes
Book manager with amended TOC button, top right, now published
TOC modal open in "Published" state
TOC modal open in "Publishing failed" state
ACCEPTANCE CRITERIA
See all TOC acceptance criteria at issue #24 (closed)
Generation of TOC and its Processing and Tracking / Management
-
A valid TOC.XML that meets the Bookshelf tagging guidelines (so passes style checks) and accurately reflects the TOC that was built by auto and manual TOC rules selected at set up or modified by the user at a later date is generated by the BCMS according to provided specifications, to include any collection metadata, all book metadata, and all of the contents, component and part, and special processing instructions -
Users can download the TOC.XML from the BCMS via a TOC preview page -
BCMS sends the TOC.XML as a chapter ingest per XML integration specifications once overnight as a chron job, whenever the following occur: - collection metadata is updated -- see #807 (closed)
- book metadata is updated -- see #807 (closed)
- a part or any of its metadata is added or updated or deleted -- Included in 14 Dec Release
- a front, body, or back matter book part is published or republished so all titles and metadata are accurate and up-to-date
- any published or republished component is moved automatically or manually within the book / toc manager page -- Included in 14 Dec Release
- Any TOC sorting or part settings is updated
-
The status of the TOC (unpublished | published | publishing failed) displays on the book manager page -
The published link of the TOC is available in the BCMS along with the date and time it was published -
System admin, org admin / editor receive email notification to their email account with the published link of the TOC when TOC is published / republished -- Developed in #957 (closed) -
Notifications and links sent by NCBI per chapter ingest integration specifications about the status of the TOC.xml chapter ingest display from an Errors tab
Issue History
cc @Kireev
Expected behaviour
The CMS stores and records all XML chapter ingest details in the BCMS for tracking, all content management, and troubleshooting.
Current behaviour
This is not happening for any toc.xml chapter ingests.
Steps to reproduce
N/A because nothing is in the BCMS to support this.
But there are 31 failed toc.xml ingest sessions in our DTS system that no one had noticed or resolved, meaning no one would know there was a problem. These failures were not just invalid XML, but also stylecheck errors, database loader checks, and other non-specific ones throughout the entire session series of tasks. So we'd also need a way to fix the XML to keep working if a software solution was not immediately available.
Environment
N/A
Possible solution
See wireframe proposed for collection xml management to be adpated for toc xml management -
Priority
Y - because no one knows when this happens right now, and the Editors for the Word TOCs will be managing them and don't have access to NCBI internal tools.