Integration Options with FOLIO

Owned by jpnelson
Last updated: May 24, 2021Version comment
3 min read

Minimal API Integration between Sinopia and FOLIO

Sinopia retains it’s own backend datastore (MongoDB or possibly Postgres RDB) along with supporting Elasticsearch search index. 

Sinopia Editor still uses the Sinopia API for read, create, and update functions. The Sinopia API would connect to the FOLIO Okapi backend for creating/updating an inventory record in FOLIO’s mod-inventory along with mod-inventory-update and mod-inventory-storage.  

Sinopia would maintain its own authentication and authorization separate from FOLIO mod-login and mod-permissions modules; however, Sinopia API would need to use the FOLIO mod-authtoken module and at least one user to generate a valid Javascript Web Token (JWT) for sending and receiving messages from Okapi.

Potential Workflow

  1. User signs into Sinopia Editor using AWS Cognito
  2. User selects a template that is retrieved from the Sinopia API
    GET https://api.sinopia.io/resource
  3. User enters data into the form and saves the resource to the Sinopia API
    POST https://api.sinopia.io/resource/{resourceId}
  4. The Sinopia API creates a new resource in MongoDB and then indexes the resource into Elasticsearch. Sinopia API then connects to a running FOLIO Okapi endpoint that is running the mod-inventory and creates an inventory record
    POST {folio_okapi_endpoint}/inventory/instance
  5. User enters data into the form and saves the resource to the Sinopia API
    POST https://api.sinopia.io/resource/{resourceId}

Open Questions

  1. Given Sinopia is running on AWS, how will multiple FOLIO installations be configured for specific institutions?
  2. What are the UI implications for displaying FOLIO-specific information per resource?
  3. How would other FOLIO apps access and display Sinopia resources?
  4. What is the minimal metadata that must be present in FOLIO inventory records? Can arbitrary Sinopia resources provide that information?

Sinopia API as an Okapi Module

The next level of integration between Sinopia and FOLIO would be to extend the existing FOLIO data import and storage and allow for new RDF resources to be stored and managed through the existing and likely new FOLIO modules. In this scenario, the Sinopia Editor would still be independent of FOLIO but the current Sinopia API would be refactored as a FOLIO Okapi Module with all data management happening within FOLIO and not an external datastore. Sinopia API module could store its RDF in the FOLIO mod-source-record-storage as either a Raw Record or in a new RDF Record table. 

Currently FOLIO does not have a full-text search index, although discussion is happening with the FOLIO community for adding Elasticsearch to the FOLIO software stack. Currently, the process for creating a FOLIO server-side module is described in the Folio-Sample-Module repository using either Java and/or Node.js and deployed within FOLIO as a Docker container. The Sinopia API is a Node.js application that is deployed to AWS as Docker container running in AWS’s Fargate service so migrating/refactoring to Okapi is conceptually not a difficult task.

User Management and Permissions

With Sinopia resources being managed through an Okapi module and APIs, users in Sinopia would no longer be managed through an external service like AWS Cognito but would leverage the core FOLIO mod-users and mod-permissions modules.  On the client-side, Sinopia could leverage FOLIO’s Stripes stripes-core for integrating permissions with the server-side mod-permissions model.

Open Questions

  1. If the Sinopia API is a server-side FOLIO module, could other non-FOLIO Sinopia APIs services co-exist?
  2. How would an Elasticsearch search index be supported within an Sinopia API Okapi module?
  3. If multiple Sinopia API (both FOLIO and non-FOLIO) instances exist, could or should these instances be aware of each other? Would Sinopia API support some sort of federated access?

Sinopia API and Editor as FOLIO Extended Apps

Refactoring the Sinopia stack as extended FOLIO Apps would involve new FOLIO server-backend and front-end modules to support the current functionality of Sinopia. FOLIO defines extended apps as “key characteristic … is that their use is ancillary and optional in terms of running a library” Another advantage of developing an extended app is that there is more flexibility in what tools to use beyond the technology FOLIO currently uses in its software stack although the current Sinopia stack uses these technologies (i.e. React UI, node.js on the server-side).

Sinopia Editor - FOLIO client-side App

With the Sinopia editor a Single Page Application built using React and Redux, refactoring to use all or part of FOLIO’s Stripes Javascript libraries like stripes-connect for connecting to FOLIO’s services and stripes-core for user permissions. Another advantage of having the Sinopia Editor as a FOLIO client-side App is that the user experience for library staff would not be different for using other FOLIO client modules.

Sinopia API - FOLIO server-side App

See Option #2 above regarding using Sinopia API as an Okapi module.

Open Questions

  1. What UI changes would be needed in the Sinopia Editor to support FOLIO’s Stripe UI look-and-feel?
  2. Would going with this option exclude non-FOLIO Sinopia users? Could Sinopia be refactored to support both a “FOLIO” variant and standalone version? 
  3. How would search be supported if Elasticsearch is not available within FOLIO?