Folio Architectural Blueprint Strategic Changes

This page contains a list of possible Folio Architectural changes for the Folio platform which are under consideration by the Technical Council. Some of these are actively under discussion, while others are intended for a later discussion. Once architectural changes have been agreed upon they will be reflected in the actual Folio Architectural Blueprint.

StatusCategoryItemSummaryPlanWhy"Aspirational" TimingRelated JiraChampionParticipants
ABI-001Done. (Pending inclusion in release)PlatformAES: pre- and post-filtersReinstate mod-aes to allow transaction data streaming directly from Okapi. The current implementation depends on Okapi filter functionality.
  • Validate changes to Okapi from Jan 2019 (MODAFILT-6)
  • Deploy mod-aes to an environment and qualify
  • Provide solution for max-headers problem
  • Depends on pending auth redesign
  • Enhance mod-aes implementation as needed
  • Release mod-aes as part of build.

  • 2020-Q2 design
  • 2020-Q3 development

MODAES-4 - Getting issue details... STATUS MODAES-5 - Getting issue details... STATUS OKAPI-837 - Getting issue details... STATUS

ABI-002Under DiscussionMulti-TenancyCross-Tenancy SupportAllows selective and controlled data sharing between separate tenants in Folio. This addresses the needs of Institutions or Consortia who need to selectively share data between their member organizations. At present Folio supports only modeling as separate tenants (share nothing) or single tenant (share everything).

Draft Document (limited access)
  • Review strawman proposal from Spitfire Team.
  • Formulate a platform-level solution
    • Identify required changes from Okapi
    • Identify required changes from RMB
    • Design mod-tenant module to arbitrate access between tenants
    • TBD


ABI-003Pending DiscussionUsersSystem and Tenant level usersIntroduce the notion of tenant-level and system-level users.
  • Spike to gather requirements including related tech-debt items
  • Implement support for user classes (mod-users)
  • Retrofit solution to existing implementations that have temporary solutions: Edge APIs; mod-pubsub.
This allows operations to be performed in the context of the entire tenant (tenant-level) or the platform (system-level). Accordingly these classes of users would be protected from casual user management and provided with suitable permissions.2020-Q3 design and development ??; 2020-Q3  released??

FOLIO-2551 - Getting issue details... STATUS

Craig McNally
ABI-004Under DiscussionMulti-TenancyDatabase Connectivity: tenant; interface; methodAllow database connectivity to be specified on a per tenant basis. Currently Folio only supports database connectivity to be specified at the module level
  • Create a solution proposal that allows flexibility for connectivity specification through RMB.
    • Primary goal is to provide tenant-level specification
    • Solution should allow for eventual interface-level specification as well and possibly method-level
  • Implement RMB changes to allow tenant-level connectivity
This would be helpful for load balancing database connectivity between tenants (allowing a large/busy tenant to have a separate database than other tenants for the same module).2020-Q3 design and development??; 2020-Q4: released ??

FOLIO-1794 - Getting issue details... STATUS

RMB-664 - Getting issue details... STATUS

ABI-005Under DiscussionPlatformAuthN/Z Refactoring

Refactoring of authentication and authorization address:

  • Performance issues related to token signature/generation
  • Protocol limitations wrt header size limitation and security best practices
  • Protocol complexity and comprehensibility


  • design a new internal Authn/z protocol (Okapi ↔ mod-authtoken)
  • Favour standard API design (RAML/JSON) implementation (handler vs filter)
  • Provide a solution with high level of cacheability
Primarily improved performance

2020-Q2 Design

2020-Q2 Development

FOLIO-2523 - Getting issue details... STATUS




PlatformDistributed Transactions

Discussion regarding strategies for dealing with cross-module (microservice) communication that required data consistency. Including:

  • architectural patterns (eg 2PC, ES/CQRS, Saga, PM, etc)
  • examples through specific FOLIO use-cases (Acq, Circ, DI)
  • platform-level support (Okapi, mod-pubsub, etc)
  • recommended external tools/libraries/frameworks
  • error handling for async operations and eventual consistency
  • Capture representative use-cases and discuss limitations of existing implementation
  • Discuss patterns that can be used to remove the limitations
  • Propose extensions to the platform components to aid developers when implementing processed requiring DT
  • Research and proposed third party library and tools that could be integrated with the FOLIO Platform

2020-Q1/Q2 Requirements analysis


Research and design

Spike: Distributed transaction use cases and solutions

Handling Errors in Asynchronous Processes

ABI-006Suggested for evaluationRefactor OkapiTenant Context (runtime)Split out Okapi tenant management into "mod-tenant". Intersects with cross-tenancy functionality.

ABI-007Suggested for evaluationRefactor OkapiDependency ManagementDedicated global registry for Folio dependencies

ABI-008Suggested for evaluationRefactor OkapiRegistry (runtime)Split out Okapi management of registered modules and interfaces.

ABI-009Suggested for evaluationRefactor OkapiTenant APIs (admin)See below

ABI-010Suggested for evaluationMulti-TenancyTenant ManagementA administrative component for tenant provisioning and upgrading (including data upgrading). Refactoring the TenantAPI functionality from Okapi forms the basis

ABI-011Under DiscussionSearchSearch EngineIntroduce a dedicated search engine (e.g. ElasticSearch) for performance reasons. Also provides cross-tenant searching.

See related proposal:

ABI-012Suggested for evaluationAutomationCamundaAdd an automation engine for Folio

ABI-013Suggested for evaluationUsers


is this the same as Team/Group concept (data ownership)?

Create support for formalized Roles within Folio

ABI-014Suggested for evaluationPlatformGraphQLAdopt GraphQL as a API calling convention in Folio

ABI-015Suggested for evaluationRelease ManagementApplication packagingSupport the distribution of "Applications" separate from monolithic Folio releases.

ABI-016Suggested for evaluationUsersSAML SSO strategyCome to a more focused project strategy for SAML support.

MODLOGSAML-44 - Getting issue details... STATUS

MODLOGSAML-58 - Getting issue details... STATUS

MODLOGSAML-59 - Getting issue details... STATUS

MODLOGSAML-66 - Getting issue details... STATUS

UXPROD-554 - Getting issue details... STATUS

UXPROD-556 - Getting issue details... STATUS

UXPROD-1612 - Getting issue details... STATUS

UXPROD-2444 - Getting issue details... STATUS

See also:

ABI-017Suggested for evaluationCodexCodex

Next generation of Codex functionality

  • beyond Codex Search

ABI-018Suggested for evaluationInstrumentationOkapi/modules

Define instrumentation capabilities, including:

  • logging formats and structure (fields, patterns)
  • metrics: supported protocols (e.g JMX, Prometheus, etc) and measured quantities
  • integration with third-part tools, including log aggregators (ELK, CW, etc), time series databases (Prometheus), service mesh solutions (e.g Istio, X-ray)