Documentation for supporting Failed status for book or book component
Updated by @lathrops1 20211024
User Story / Context
There are some statuses in the BCMS (e.g., conversion, loading preview, publishing) that block a user to retrigger an action because it may conflict with an action in progress. However, sometimes, mostly because of software issues, these in-process statuses fail but are not getting communicated to the BCMS, which means the user is completely blocked from resolving the issue to do what they need to do (e.g. get a preview to approve or see their content release to the Bookshelf site).
NOTE: Sometimes there are issues in the PDF tagging workflow that must stop a tagging process in action to avoid costly duplications and errors. This use case could be communicated by email in Phase 1 to simplify the development, but want to document it as a valid use case.
Proposed Technical Solution
Create rules for the BCMS to set a "failed state" when this happens so the user can retrigger the process to do what they need to do.
Rules
When a chapter or wholebook is in status:
- Coverting
- Loading preview
After 4 hours
, if the status has not changed, push the chapter or wholebook into a "failed" state.
In a "failed" state we allow user to:
- Submit
- Reload Preview
We show a generic message in the Error tab, for example:
Name | Category | Severity | Assignee | Message |
---|---|---|---|---|
Failed: Timeout | Timeout | error | Publisher | The process failed because it took too long. Please try again or contact an NCBI System Admin. |
When a chapter or wholebook is in status:
- Publishing
After 4 hours
, if the status has not changed, push the chapter or wholebook into a " Publishing failed" state.
In a "Publishing failed" state we allow user to:
- Publish (again)
We show a generic message in the Error tab, for example:
Name | Category | Severity | Assignee | Message |
---|---|---|---|---|
Failed: Timeout | Timeout | error | Publisher | The process failed because it took too long. Please try again or contact an NCBI System Admin. |
Use Cases
General use cases:
- Problems with Kafka notifications not getting sent or picked up
- Problems with Word / XML Conversion Processes getting stuck, including TM server problems or other scripting issues not communicated to BCMS
- User problem in sending source PDFs to "Tagging" and seeing they did something in error and not being able to correct it by cancelling and resending the package
- Problems with Loading Preview Processes getting stuck, including TM server problems or other scripting issues not communicated to BCMS
- Problems with the Publishing steps, such as the Agreements API not being able to connect to the Agreements database because of server issues
Specific Proposals to address issues:
Development / Technical team to review to make sure these address the user story and general cases. Also to define x amount of time
- I'd propose two hours to start, and we review and revise in future as necessary.
Specific example use cases for putting a book or book component into a failed status, so that users can resubmit or reload preview.
Notifications / Software Issues:
-
CONVERSION XML AND WORD: A user submits source files in the WORD and XML workflows. If BCMS does not receive a notification for the book or chapter in
x amount of time
, then put the book component into a failed state that permits the user to retrigger the process. - TAGGING PDF: A user submits source PDF files and notices they made a mistake. User is able to manually "fail" process that generates an email notification to system admi, pdf2xmltaggers, users to ignore the package (with package name provided in message) and provide the user with the ability to upload and submit new files.
-
LOADING TO PREVIEW XML / WORD / PDF FROM MANUAL UPLOAD OF CONVERTED FILE: A user uploads and selects to reload preview. If BCMS does not receive a notification for the book or chapter in
x amount of time
, then put the book component into a failed state that permits the user to retrigger the process. -
SYSTEM LOADING TO PREVIEW WORD, XML, PDF: Apex OR NCBI posts to FTP ANY converted / tagged package. If BCMS does not receive a notification for the book or chapter in
x amount of time
, then put the book component into a failed state that permits the user to retrigger the process. -
PUBLISHING: The BCMS triggers a publishing process that inclues receving notifications from NCBI AND the Agreements database via integration specifications. If BCMS does not receive a notification for the book or chapter in
x amount of time
, then put the book component in a failed state that permits the user to retrigger the process.
The 'failed state' status would be communicated in the following places:
- Component it refers to
- Files it refers to
- Errors tab for that job / sessions
Minimal Acceptance Criteria
-
The BCMS has documented, transparent rules for when an "in-process" status can be failed. -
The "Failed" state staus is transparent in the BCMS for the component, files, and errors history -
Bookshelf staff and supported users can be ensured they won't be blocked because of software or other issues outside of their control from processing their content and adding it to Bookshelf without introducing content or other errors in a timely fashion (within a day of submission)