/
GOBI integration user interface

GOBI integration user interface


AuthorAndrei Makaranka
JIRA task

UXPROD-3681 - Getting issue details... STATUS

Business Requirements
Architects Review

DONE

PO review

DONE

Revision History

VersionDateOwnerDescriptionReason
v1.006.17.2022Initial version
v1.106.20.2022Updates for schemas added
v1.206.21.2022Andrei Makaranka Work break down structure ready
v1.306.24.2022Solution finalized
v 2.007.07.2022Andrei Makaranka New schema "OrderMappingsView" addedNeed 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"

GOBI field name
...... 
 "dataSource": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
  		"dataSourceFieldName": {
      		"type": "string",
      		"description": "GOBI field name"
    	}, 
        "from": {
          "type": "string",
          "description": "XPath to the data for the field to map"
        }, 
	......  
 }
......

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

Detailed translation
       "translation": {
          "enum": [
            "lookupContributorNameTypeId",
            "lookupExpenseClassId",
            "lookupAcquisitionMethodIds",
            "lookupAcquisitionUnitDefaultAcqUnitName",
            "lookupLocationId",
            "lookupMaterialTypeId",
            "lookupFundId",
            "lookupMock",
            "lookupOrganization",
            "lookupProductIdType",
            "lookupBillTo",
            "lookupShipTo",
            "lookupSuffix",
            "lookupPrefix",
            "lookupLinkedPackage",
            "lookupConfigAddress",
            "separateISBNQualifier",
            "truncateISBNQualifier",
            "toBoolean",
            "toDate",
            "toDouble",
            "toInteger"
          ],
          "javaEnums": [
            {
              "name": "LOOKUP_CONTRIBUTOR_NAME_TYPE_ID",
              "title": "lookupContributorNameTypeId",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_EXPENSE_CLASS_ID",
              "title": "lookupExpenseClassId",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_ACQUISITION_METHOD_IDS",
              "title": "lookupAcquisitionMethodIds",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_ACQUISITION_UNIT_DEFAULT_ACQ_UNIT_NAME",
              "title": "lookupAcquisitionUnitDefaultAcqUnitName",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_LOCATION_ID",
              "title": "lookupLocationId",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_MATERIAL_TYPE_ID",
              "title": "lookupMaterialTypeId",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_FUND_ID",
              "title": "lookupFundId",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_MOCK",
              "title": "lookupMock",
              "description": " <<Please put clear description about logic of translator>>"
            },

            {
              "name": "LOOKUP_ORGANIZATION",
              "title": "lookupOrganization",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_PRODUCT_ID_TYPE",
              "title": "lookupProductIdType",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_BILL_TO",
              "title": "lookupConfigAddress",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_SHIP_TO",
              "title": "lookupConfigAddress",
              "description": " <<Please put clear description about logic of translator>>"
            },

            {
              "name": "LOOKUP_SUFFIX",
              "title": "lookupSuffix",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_PREFIX",
              "title": "lookupPrefix",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_LINKED_PACKAGE",
              "title": "lookupLinkedPackage",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "LOOKUP_CONFIG_ADDRESS",
              "title": "lookupConfigAddress",
              "description": " <<Please put clear description about logic of translator>>"
            },

            {
              "name": "SEPARATE_ISBN_QUALIFIER",
              "title": "separateISBNQualifier",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "TRUNCATE_ISBN_QUALIFIER",
              "title": "truncateISBNQualifier",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "TO_BOOLEAN",
              "title": "toBoolean",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "TO_DATE",
              "title": "toDate",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "TO_DOUBLE",
              "title": "toDouble",
              "description": " <<Please put clear description about logic of translator>>"
            },
            {
              "name": "TO_INTEGER",
              "title": "toInteger",
              "description": " <<Please put clear description about logic of translator>>"
            }
          ],
          "description": "Method to translate the specified type"
        }

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

Folio fields
    "field": {
      "type": "string",
      "description": "Field name of the mapping",
      "enum": [
        "poLine.eresource.accessProvider",
        "poLine.acquisitionMethod",
        "po.acqUnitIds",
          ...
        "poLine.cost.quantityElectronic",
        "poLine.cost.quantityPhysical",
        ...
      ],
      "javaEnums": [
        {
          "name": "ACCESS_PROVIDER",
          "title": "poLine.eresource.accessProvider",
          "description": "<<Description for FOLIO field>>"
        },
        {
          "name": "ACQUISITION_METHOD",
          "title": "poLine.acquisitionMethod",
          "description": " <<Description for FOLIO field>>"
        },
        {
          "name": "LOOKUP_ACQUISITION_UNIT_DEFAULT_ACQ_UNIT_NAME",
          "title": "po.acqUnitIds",
          "description": "<<Description for FOLIO field>>"
        },
        ....,
        {
          "name": "QUANTITY_ELECTRONIC",
          "title": "poLine.cost.quantityElectronic",
          "description": " <<Description for FOLIO field>>"
        },
        {
          "name": "QUANTITY_PHYSICAL",
          "title": "poLine.cost.quantityPhysical",
          "description": "<<Description for FOLIO field>>"
        }
        ...
      ]
    }

Create new schemas for retrieving list of Fields and Translators

Schemas and samples should be placed in the acq-models module

  1. Create new directory in "mod-gobi"
  2. Create schema and sample (fields.sample) for fields (field.json +folio_order_fields.json) collection


field.json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Field description",
  "type": "object",
  "properties": {
    "name": {
      "description": "Name of the field",
      "type": "string"
    },
    "path": {
      "description": "Path to field",
      "type": "string"
    },
    "description": {
      "description": "Description of the field",
      "type": "string"
    }
  }
}

folio_order_fields.json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Collection of pairs field name and path in the JSON",
  "type": "object",
  "properties": {
    "fields": {
      "description": "An array of pairs field name and path in the JSON",
      "id": "fields",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "field.json"
      }
    },
    "totalRecords": {
      "description": "total number of records in the array",
      "type": "integer"
    }
  },
  "required": [
    "fields",
    "totalRecords"
  ]
}


folio_order_fields.sample
{
  "fields": [
    {
      "name": "PREFIX",
      "path": "po.poNumberPrefix",
      "description": "Purchase order prefix"
    },
    {
      "name": "QUANTITY_ELECTRONIC",
      "path": "poLine.cost.quantityElectronic",
      "description": "Purchase order line electronic quantity"
    }
  ],
  "totalRecords": 1
}
 

3. Create schema and sample for translators collection


translator.json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Translator description",
  "type": "object",
  "properties": {
    "name": {
      "description": "Name of the translator",
      "type": "string"
    },
    "translator": {
      "description": "Path to field",
      "type": "string"
    },
    "description": {
      "description": "Description of the translator",
      "type": "string"
    }
  }
}

folio_order_translators.json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Collection of pairs translator Java method name and name of translator",
  "type": "object",
  "properties": {
    "translators": {
      "description": "An array of pairs translator Java method name and name of translator",
      "id": "translators",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "translator.json"
      }
    },
    "totalRecords": {
      "description": "total number of records in the array",
      "type": "integer"
    }
  },
  "required": [
    "translators",
    "totalRecords"
  ]
}
  


folio_order_translators.sample