Agreements API request at Publish step
Use case
- Before a chapter, book, or TOC is released to Bookshelf, there needs to be a check to ensure certain domain settings match the relevant agreement.
- This applies to all books and collections.
Workflow steps
- Editor (or Org admin or Sys admin) selects "Publish" button which starts checks to Agreements API. Status changes to "Publishing".
- At Check 1: if there is NO agreement for a book or its collection domain OR if there is more than one agreement, the status changes to "Publishing Failed" and the error reported is displayed on the errors tab (developed in #800 (closed)). NCBI sys admins resolves Agreements errors (out of BCMS) and then repeats step 1.
- If check 1: passes, the status remains "Publishing" and Checks 2 and 3 are done (If the book domain belongs to a collection, run the checks 2 and 3 against the book domain). Update the domain to match the agreement.
- Status remains publishing during release (see #435 (closed)) and then status changes to "Published".
Agreement checks
GET AGREEMENT DATA
You will need to request agreement data for a book and also for its parent collection (if any):
Use the domain name: https://www.ncbi.nlm.nih.gov/books/publisherportal/api/agreement_journals/?is_current=true&agreement__is_current=true&journal__pmc_domain=DOMAIN
Note, you will be looking at an array of agreements, not just one.
For each agreement, you care about agreement_type.title
, open_access
, and sites
.
So, let's take the above example (domain=gene) and reduce it down to what matters here:
[
{
"type": "Customized Agreement",
"oa": "None",
"sites": "bookshelf"
},
{
"type": "Access Amendment",
"oa": "All",
"sites": ""
}
]
Agreement Check 1: Domain has exactly one agreement
Agreement Check 1: Domain has exactly one agreement
The domain or the parent collection domains must be linked to an agreement.
Wrinkle: we are only interested in agreements of certain types. Let's call them "main types"
11: Works of the U.S. Government
5: Customized Agreement
4: NCBI Bookshelf Restricted Access
3: NCBI Books Online Agreement
2: Bookshelf Full Participation
1: NLM LitArch Participation
6: Additional Title Amendment
If neither the domain nor the parent collection has an agreement, then throw an error:
Neither the book nor the parent collection is linked to an agreement.
If the domain or the parent collection has more than one agreement of these types, then also throw an error:
The book is linked to more than one agreement of the following types: {main types}
Using our example: we're good, there is one and only one agreement of the type Customized Agreement
.
Agreement Check 2: OA setting matches PMCBook
Agreement Check 2: OA setting matches PMCBook
We are interested in whether the domain is open access (OA).
We're looking at the oa
setting, but in a certain priority order (Access Amendment
->PMCI Permission
->main types
).
So in our example we look at Access Amendment
first and the respective setting reads All
.
We check this against the domain service (DS), namely properties.entire_journal_open_access
After check, the BCMS updates the domain with whatever value is returned by the Agreements API, as it is the version of truth.
Agreement Check 3: UKPMC setting matches PMCBook
Agreement Check 3: UKPMC setting matches PMCBook
We are interested in whether the book is allowed to be shipped to "Europe PMC" in the UK (aka "UKPMC").
We're looking at the sites
setting, again in a certain priority order (PMCI Permission
->Access Amendment
->main types
).
A domain is considered to be "in UKPMC" if sites
contains (not equals) the string ukpmc
Our example is negative, it only reads bookshelf
and not e.g. bookshelf,ukpmc
We check this against the domain service (DS), namely attributes[name=ukpmc-journal]
After check, the BCMS updates the domain with whatever value is returned by the Agreements API, as it is the version of truth.
QA Steps
resources: a list of linked domains to agreements: agreements_recent_books.txt
Coko QA Steps
- Agreements Check 1 -- cannot be tested by Coko QA (unless an agreements is associates to a book by NCBI)
- Agreement Check 2 or 3 -- cannot be tested on
ncbidev
(unless the domain service is down). Test locally by faking a failed connection to the domain by changing the url field to each of those functions : server/services/axiosService/index.js.
NCBI testing
All testing to be done on NCBI's production
deployment by turning on the Agreement checks in the config (Denis)
Current Bug
From @lathrops1 testing on NCBI's production
deployment (demonstrated in #481 (comment 88921)), it's clear that the BCMS UI does not update for Agreement Check 2 and 3.