Summary

Currently, users can trigger bulk operations by submitting a list of record identifiers. However, in many cases, the list of identifiers is not available, and users will need to have a way to identify records for bulk operations based on a query. In many cases, the search will need to be performed across different record types (for example, searching for users with specific permissions or users with outstanding fees).

This page aims to provide a design of the Query tool UI components that users will use to build queries and review the returned resultset. This also provides the definitions for data structures that will be used by the UI implementation and should be supported by the back-end side that acts as a data provider.

Requirements

Here and below, the terms "Record type" and "Entity type" are equivalent.

The query tool will be the complex UI components used to:

• compose queries visually to retrieve data;
• show the retrieved resultset to the user;

This components should not be coupled to any folio application/module; it is supposed to use this component in different FOLIO applications. The “Bulk operations” and the "List" applications are the first ones that will leverage the usage of this component.

The requirements for this UI component are listed in the JIRA Feature UXPROD-3785

In addition, there is a list of the query form elements that must be supported by the Query tool UI component.

UIPQB-2 String containing UUIDs : field-action-value component
UIPQB-3 UUID not enforced: field-action-value component
UIPQB-4 UUIDs: field-action-value component
UIPQB-5 Field-action-value component: String
UIPQB-6 Array property type - action-value component
UIPQB-7 Integer property type - action-value component
UIPQB-8 Boolean property type - action-value component
UIPQB-9 Date-time property format - action-value component
UIPQB-10 Object property type - action-value component
UIPQB-11 Enum property type - action-value component
UIPQB-12 Display record types available for querying with multiple record type support

https://docs.google.com/document/d/1hagcmSUhEYoKY7yiMcfAcW_NXXtLfXQCrm3OFCndppc/edit

The entity type (Users, Items, Holdings) defines a set of columns (A) that will be available for criteria building and a set of columns (B) that will be used to show the tabular preview and the review retrieved data. These two sets of columns can be different. The user can choose which columns of set (B) he/she wants to see on the preview/review forms. The selected/unselected columns do not affect the business logic/behavior of the UI components. The user can't unselect all columns; at least one column must be selected.

Additional requirements

• The retrieved resultset should be pageable and sortable

Non-functional requirements

• The UI components should not be coupled to any folio application/module (independent codebase). 
• The UI components should not depend on the FOLIO modules’ data structures, JSON schemas, or any other data definitions that are local or internal for a particular FOLIO module/application.
• The back-end java library must define data structures that must be used by any data provider to support the Query tool.

Implementation

The solution will consist of two UI components that could be used by any FOLIO UI application and the back-end java library that defines the SPI contract that UI components will use to perform operations.

• Query Builder - the UI components used to create FQL expression used to retrieve data https://drive.google.com/file/d/1wxehvAsSl9nW6GG-ijRZneTuTA7sMxsr/view?usp=share_link
  • Query Builder has a required input parameter, "Primary Entity Type," that will be used as a basis for the query and defines the type of the resultset.
  • The preview provides the user with the precise number of total records in the resultset.
• Resultset Viewer - the component used to show the resultset to the user. https://drive.google.com/file/d/1vDKMpk3S7XYMps2YpYY3rRLDnuzmobM-/view?usp=share_link. It provides the following functionality:
  • The user can navigate back and forth through the resultset (pagination). The size of the page is fixed and equals 100 records.
  • The user can change the sorting order of the resultset.
    • The sorting option will be available only if the total number of retrieved records is lower than some limit. The actual value for the limit must be defined beforehand based on a study of the performance of real queries in the database.
  • The user can deselect particular records from the resultset using checkboxes.
• The back-end java library defines the SPI that must be implemented by the back-end data provider in order to be used by the Query Tools UI components.
• Back-end data provider for Query tool - the back-end module that performs FQL queries created by the Query Tool
• Back-end data provider for Query tool Client - the back-end java library that the back-end modules must use to perform/send FQL queries to the data provider.

The general workflows of the Query Tool UI usage:

In order to use the query tool component to build queries, it should be provided with the metadata that defines data structures, possible options, values, restrictions, etc.

There is a repository that defines the schemas that the UI query tool component will use.

https://github.com/folio-org/folio-query-tool-metadata

Below is the diagram representing the complete data model for metadata that the UI query tool component will use to operate.

These data structures are defined by the JSON schemas from the repository mentioned above.