Configuration module based on the raml-module-builder and a set of raml and json schemas backed by a postgresdb async implementation
Java RAML Shell PLpgSQL Dockerfile
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Copyright (C) 2016-2018 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.

Configuration module based on the raml-module-builder and a set of raml and json schemas backed by a PostgreSQL async implementation

This project is built using the raml-module-builder, using the PostgreSQL async client to implement some basic configuration APIs. It is highly recommended to read the raml-module-builder README since there are many features that the mod-configuration module inherits from the raml-module-builder framework.

The idea behind this module is to provide a type of centralized configuration service. The service allows for the creation of module configurations. Within a module there are named configurations, and within a named configuration there are 1..N 'rows'.

-> Module

    -> config 1 -> row 1

    -> config 1 -> row 2

    -> config 2 -> row 1

    -> config 2 -> row 2

    -> config 2 -> row 3

This would in turn look something like:

Module configName updatedBy default enabled code value desc userId
CIRCULATION import.uploads.files Joe false true path_2_file PENDING file to import uid
CIRCULATION patron.drools Joe false true rule_name1 base64enc_drools_file rule file
CIRCULATION patron.drools Joe false true rule_name2 base64enc_drools_file rule file uid

The above table can be interpreted as follows:


   Config name: patron.drools

       row: rule_name1 (the code of the row)

Note that each tenant has its own schema with its own configuration tables. The userId field can be populated to associate an entry in the table with a specific user.

see configuration schema for an object description:


clone / download mod-configuration then mvn clean install


java -jar mod-configuration-server/target/mod-configuration-server-fat.jar -Dhttp.port=8085 embed_postgres=true

Or run via Dockerfile

The Configuration service can be run in either embedded PostgreSQL mode or with a regular PostgreSQL server.

Note that the embedded PostgreSQL is started on a static port (6000)

Connecting to an existing configuration service

The configuration module also comes with a statically typed Java client. To use the client via maven, add:

ConfigurationsClient cc = new ConfigurationsClient("", port, "mytenantid");

cc.getEntries("module==CIRCULATION", 0, 10, "en", response -> {
  response.bodyHandler(body -> {

String content = getFile("kv_configuration.sample");
Config conf = new ObjectMapper().readValue(content, Config.class);
cc.postEntries(null, conf, reply -> {
  reply.bodyHandler( handler -> {
   System.out.println(new String(handler.getBytes(), "UTF8"));

Query syntax

The configuration module supports the CQL syntax - please see


Every change to entries is automatically audited by the service. To see an audit list:


CQL syntax is also supported by the audit API

Documentation of the Service's APIs

Documentation is auto-generated from the RAML files into HTML. After the service is started, the documentation can be viewed at:



Make sure to include appropriate headers as the runtime framework validates them.

Accept: application/json

Content-Type: application/json

Query for all tables:

Query for a specific module / config / row:

Add an entry:
  "module": "CIRCULATION",
  "configName": "validation_rules",
  "updatedBy": "joe",
  "code": "PATRON_RULE",
  "description": "for patrons",
  "default": true,
  "enabled": true,
  "value": "any value"

Deleting / Updating specific entries is possible as well - See circulation.raml file.

Additional information

Other documentation

The raml-module-builder framework.

Other modules are described, with further FOLIO Developer documentation at

API documentation

This module's API documentation and the local docs.

Issue tracker

See project MODCONF at the FOLIO issue tracker.

Quick start

Compile with mvn clean install and see further instructions.

Run the local stand-alone instance:

java -jar mod-configuration-server/target/mod-configuration-server-fat.jar \
  -Dhttp.port=8085 embed_postgres=true

Additional command-line options and information.

Code analysis

SonarQube analysis.

Download and configuration

The built artifacts for this module are available. See configuration for repository access, and the Docker image.