Automate linking in quickMARC app
Introduction
This document outlines the design of a backend feature, which will allow users to automatically validate/update/create links for MARC bib fields to an authority record when editing a MARC bib record.
More details on a feature: [UXPROD-3874] and spike story: [MODELINKS-79]
Requirements
Functional Requirements
- The API must allow finding all applicable MARC authorities to control the MARC bib record based on the $0 subfield of the bib's fields.
- The API must provide only suggestions for links, and must not save any new data, saving will be performed by a user.
- The API must allow saving the MARC bib record even if linking a MARC bib field to a MARC authority record was unsuccessful.
- The API must allow sending a MARC record for links assignment with already existing links.
- The API must allow sending a MARC record for links assignment with not saved links and changes to the bib record.
- The API must provide a notification of what fields were successfully linked and what fields that are applicable for linking failed to link.
- The API must provide different types of failures for failed fields.
Non-Functional Requirements
- Automate linking should take no longer than ~2 seconds
Architecture
An API endpoint will be implemented in mod-quick-marc to provide UI with suggested links for the record. mod-quick-marc will work as a proxy module, that will call the mod-entities-links newly created endpoint. All main linking logic will be implemented in mod-entities-links. mod-search will be used as a search service for finding applicable MARC authorities. mod-source-record-storage will be used for fetching data needed to construct controllable fields in the MARC bib record. All interaction between modules is via HTTP.
Data Flow and Processing
- The UI sends a request to the backend API.
- mod-quick-marc receives the request and converts the record into an SRS-like format.
- mod-quick-marc sends a request to the mod-entities-links API.
- mod-entities-links receives the request and fetches linking rules from the database using cache.
- From MARC bib fields that are applicable for linking according to linking rules, $0 subfield values are extracted.
- $0 values are used for search authorities in mod-search. The current mod-search endpoint also calculates a number of already existing links in the instance index, this should be omitted to speed up the process.
- mod-entities-links receives a collection of authority records and prepares a request to the mod-source-record-storage.
- mod-entities-links sends a request to the mod-source-record-storage bulk endpoint.
- mod-entities-links receives a collection of authority source records.
- mod-entities-links analyze results, prepare data for links according to linking rules, and set constructed links into the record.
- mod-quick-marc receives the record with links.
- mod-quick-marc converts the record into the appropriate format.
- UI receives the record with suggested links.
API Design
mod-quick-marc
POST /records-editor/links/suggestion
This endpoint will be used to find and provide UI with valid links for a record. The request will include a JSON payload with the record data:
{
"marcFormat": "BIBLIOGRAPHIC",
"leader": "01587ccm a2200361 4500",
"fields": [
{
"tag": "001",
"content": "393893"
},
{
"tag": "100",
"content": "$a 393893 $b test $0 n1234567890 $9 312da284-a8fd-4c84-ae90-927539d6df93",
"indicators": [
"1",
"2"
],
"link": {
"authorityId": "312da284-a8fd-4c84-ae90-927539d6df93",
"authorityNaturalId": "n1234567890",
"linkingRuleId": 1,
"status": "ACTUAL"
}
},
{
"tag": "100",
"content": "$a 393893 $b test $0 n1234567890 $9 312da284-a8fd-4c84-ae90-927539d6df93",
"indicators": [
"1",
"2"
],
"link": {
"authorityId": "312da284-a8fd-4c84-ae90-927539d6df93",
"authorityNaturalId": "n1234567890",
"linkingRuleId": 1,
"status": "ERROR"
}
},
{
"tag": "600",
"content": "$a 393893 $b test",
"indicators": [
"1",
"2"
]
}
]
}
The response will include suggested links with the status "NEW"; fixed data and status "ACTUAL" for links, that had the status "ERROR"; links with the status "ERROR" and cause type for fields where a link can't be assigned.
{
"marcFormat": "BIBLIOGRAPHIC",
"leader": "01587ccm a2200361 4500",
"fields": [
{
"tag": "001",
"content": "393893"
},
{
"tag": "100",
"content": "$a 393893 $b test $0 n1234567890 $9 312da284-a8fd-4c84-ae90-927539d6df93",
"indicators": [
"1",
"2"
],
"link": {
"authorityId": "312da284-a8fd-4c84-ae90-927539d6df93",
"authorityNaturalId": "n1234567890",
"linkingRuleId": 1,
"status": "ACTUAL"
}
},
{
"tag": "100",
"content": "$a 393893 $b updated $0 n1234567890 $9 312da284-a8fd-4c84-ae90-927539d6df93",
"indicators": [
"1",
"2"
],
"link": {
"authorityId": "312da284-a8fd-4c84-ae90-927539d6df93",
"authorityNaturalId": "n1234567890",
"linkingRuleId": 1,
"status": "NEW"
}
},
{
"tag": "600",
"content": "$a 393893 $b test",
"indicators": [
"1",
"2"
],
"link": {
"status": "ERROR",
"errorCauseType": "1001"
}
}
]
}