GOBI integration user interface
Author | Andrei Makaranka |
---|---|
JIRA task | |
Business Requirements | |
Architects Review | DONE |
PO review | DONE |
Revision History
Version | Date | Owner | Description | Reason |
---|---|---|---|---|
v1.0 | 06.17.2022 | Initial version | ||
v1.1 | 06.20.2022 | Updates for schemas added | ||
v1.2 | 06.21.2022 | Andrei Makaranka | Work break down structure ready | |
v1.3 | 06.24.2022 | Solution finalized | ||
v 2.0 | 07.07.2022 | Andrei Makaranka | New schema "OrderMappingsView" added | Need to identify Default or Custom mapping |
Overview
Problems
It is difficult and time consuming to retrieve the data points required to connect the FOLIO and GOBI APIs for an instance of FOLIO.
It is also difficult (requires significant technical knowledge) to update the custom mapping options for this integration
In scope
- Provide an interface that is only available to users with specific permissions that displays the custom field mappings for each order type
- Allow users to edit the mappings for GOBI Localdata fields 1 - 4
- Allow users to edit the Default values for existing field mappings
- Allow users to Add or remove field mappings (Depending on effort required this may need to be delivered in a separate feature)
Constraints
Assumptions, dependencies
Out of Scope
- Provide an interface that is only available to users with specific permissions that displays the information need to connect FOLIO and GOBI APIs (Eg. URL, API Key)
Investigate : FOLIO secrets management
- Dennis Bridges In the first iteration will be not supportable updating mapping where following configs exist : "fromOtherField", "defaultMapping", "combinator", "translateDefault".
There are a small number of mappings that use several of these default mappings ("fromOtherField", "defaultMapping", "combinator", "translateDefault" ) in their configuration by default.
Architecturally Significant Requirements
- Custom configuration will be stored in the mod-configuration
Solution Design
Data Model
Update mapping schema → mapping.json
1.Insert new field in the "dataSource" element.
"dataSourceFieldName" - will be used by UI to show mapping as "GOBI field name"
2. Replace simple definition of the "dataSource.translation"
Note :
- Replace "<<Please put clear description about logic of translator>>" with details about logic and input and output of translator method.
- Field "title" from "javaEnums" must be the same as translator method name from "enum". This makes it easier to build a list of translators for the new API and improve documentation.
Specification : https://github.com/joelittlejohn/jsonschema2pojo/wiki/Reference#javaenumnames
3. Replace simple definition of the "dataSource.field"
Note :
- Replace "<<Description for FOLIO field>>" with details about FOLIO field.
- Field "title" from "javaEnums" must be the same as path to FOLIO field in the JSON from "enum". This makes it easier to build a list of fields for the new API and improve documentation.
Specification : https://github.com/joelittlejohn/jsonschema2pojo/wiki/Reference#javaenumnames
Create new schemas for retrieving list of Fields and Translators
Schemas and samples should be placed in the acq-models module
- Create new directory in "mod-gobi"
- Create schema and sample (fields.sample) for fields (field.json +folio_order_fields.json) collection
3. Create schema and sample for translators collection
4. Create new schema OrderMappingsView.json for showing Mapping on UI
5. Create new schema OrderMappingsViewCollection.json for showing Mapping on UI
APIs
Retrieve Fields and Translators and mapping Types
Create new RAML file mod-gobi\ramls\gobi-mappings.raml(if not created) and add endpoints.
Method | Path | Request | Response | Description | Interface | Notes |
---|---|---|---|---|---|---|
GET | /gobi/orders/mappings/fields | NA | folio_order_fields | Return list of FOLIO fields | gobi.mappinngs.fields | Status : 200 Permission: gobi.mappinngs.fields.collection.get |
GET | /gobi/orders/mappings/translators | NA | folio_order_translators | Return list of FOLIO translators | gobi.mappinngs.translators | Status : 200 Permission: gobi.mappinngs.translators.collection.get |
GET | /gobi/orders/mappings/types | NA | Collection of ENUMfrom OrderMappings.json: /gobi/orders/mappings/types "orderType": { "type": "string", "description": "The type of the GOBI order", "enum": [ "ListedElectronicMonograph", "ListedElectronicSerial", "ListedPrintMonograph", "ListedPrintSerial", "UnlistedPrintMonograph", "UnlistedPrintSerial" ] } | Return list of mapping types | gobi.mappinngs.types | Status : 200 Permission: gobi.mappinngs.types.collection.get |
GOBI mapping
Create new RAML file mod-gobi\ramls\gobi-mappings.raml(if not created) and add endpoints.
1. Define API for retrieving GOBI mapping
1.1 Add new schema OrderMappingsCollection.json which is collection of mod-gobi\src\main\resources\OrderMappings.json
1.2 Create new endpoint "/mappings" in the mod-gobi\ramls\gobi-mappings.raml.
Method | Path | Request | Response | Description | Interface | Notes |
---|---|---|---|---|---|---|
GET | /gobi/orders/custom-mappings | NA | OrderMappingsViewCollection.json | Return list of GOBI mapping collection | gobi.mappings | Status : 200 Permission: gobi.custom-mappings.collection.get |
GET | /gobi/orders/custom-mappings/<orderType> | NA | OrderMappingsView.json | Return item of GOBI mapping specified type OrderMappings.json: /gobi/orders/mappings/types | gobi.mappings | Status : 200 Permission: gobi.custom-mappings.item.get |
POST | /gobi/orders/custom-mappings | OrderMappings.json | OrderMappingsView.json | Create custom GOBI mapping for specific type from OrderMappings.json: /gobi/orders/mappings/types | gobi.mappings | Status : 201 Permission: gobi.custom-mappings.item.post |
PUT | /gobi/orders/custom-mappings/<orderType> | OrderMappings.json | NA | Update GOBI mapping for specific type from OrderMappings.json: /gobi/orders/mappings/types | gobi.mappings | Status : 204 Permission: gobi.custom-mappings.item.put |
DELETE | /gobi/orders/custom-mappings/<orderType> | NA | NA | Delete GOBI mapping by specified type from OrderMappings.json: /gobi/orders/mappings/types | gobi.mappings | Status : 204 Permission: gobi.custom-mappings.item.delete |
Design
Implement APIs for retrieving Fields, Translators and mapping Types
- Create business service
- Read and parse file mapping.json and this should only happen once
Path to Translators : new JsonObject(jsonString).getJsonObject("properties").getJsonObject("dataSource").getJsonObject("properties").getJsonObject("translation").getJsonArray("javaEnums")
Path to Fields : new JsonObject(jsonString).getJsonObject("properties").getJsonObject("field").getJsonArray("javaEnums")
3. Map Fields to folio_order_fields.json ( Create news schemas for retrieving list of Fields and Translators)
4. Map Translators to folio_order_translators.json ( Create news schemas for retrieving list of Fields and Translators)
Implement API for retrieving GOBI mapping configs
Configs now are stored in the mod-configuration and should be stored in the mod-configuration
Example for ListedPrintMonograph
Work Breakdown Structure
Work | Comments | Story | ~ Estimate | |
---|---|---|---|---|
1 | 1.1 Create schemas for fields and translators mapping → Create news schemas for retrieving list of Fields and Translators 1.2 Update mapping schema → Update schema mapping.json | acq-models, mod-gobi | 1 | |
2 | 2.1 Define new APIs for retrieving Fields, Translators and mapping Types → Retrieve Fields and Translators and mapping Types 2.2 Implement created APIs → Implement APIs for retrieving Fields, Translators and mapping Types | mod-gobi | 3 | |
3 | 3.1 Define API GOBI integration default or custom mappings based on order type → APIs GOBI mapping 3.2 Implement API GOBI integration default or custom mappings based on order type → Implement API for retrieving GOBI mapping configs | mod-gobi | 3 |
Open Items
Question | Answer | Story |
---|---|---|
Raman Auramau Could you please help with design API Key showing? | Investigate : FOLIO secrets management (Raman A) The mod-inn-reach by Volaris team can be used as an example of implementing very similar functionality. The logic there is as follows - when interacting with an external system, API Keys are used. When setting up such a interaction, an administrator can click the Generate keys button on the UI, and a pair of keys (API key & secret key) will be generated and saved. The keys are simply stored in the database. On the UI, one can then see these keys (access by permissions!) |