System groups RFC

RFC: System groups and extending independent branches

The independent branches feature in Koha 3.0 gives multi-branch or consortial users of Koha the ability to achieve some separation between branches. For example, with independent branches turned on, a staff user can circulate only within their own branch and only see orders and item records from their own branch.

However, independent branches currently has some limitations. On the one hand, most library parameters are global; things like item types, notice templates, MARC matching rules, system preferences, etc., are accessible to all branches, but it would be useful if these settings could have different values from one branch to the next. On the other hand, independent branches can restrict circulation between branches too much. For example, if a library is sharing a Koha database with another library, the two libraries may not do any shared circulation of their materials, and therefore would turn independent branches on. However, if the first library has more than one branch, that library cannot readily circulate between its branches without representing all of its physical branches as a single Koha branch.

To improve the ability of Koha to support administrative separation of multiple libraries, LibLime proposes to implement something we're calling system groups. The two main concepts that would be added are:

1. Adding the ability to link settings to a branch.

This means that a setting can be "owned" by a branch, i.e., have one value or set of values at one branch and a different value at another. Settings that could be owned by a branch include:

• item types
• patron categories
• acquisitions settings such as funds and currencies
• selected system preferences
• authorized values
• notice templates (note that this is related to Mason's RFC of May 29).
• calendars
• MARC record matching rules

2. Allow parent-child relationships between branches.

This means that a branch can belong to a parent branch, and inherit settings from its parent. For example, suppose two independent libraries, the Dewey Library and the Ranganathan Library, share a Koha database. Furthermore, suppose that the Dewey Library has two branches, Melvyl and John.

The John and Melvyl branches would be "children" of the Dewey Library. The Dewey Library and Ranganathan Library would be children of a notional root library, which holds global settings for all branches in the database.

A circulation calendar could be set for Dewey. The John branch would then inherit it. However, if we suppose that the Melvyl branch is closed on Mondays, and needs a different calendar, the Melvyl branch could own its own calendar, overriding the one inherited from Dewey.

Some settings would be inherited but not overridable. For example, two item types could be defined for Dewey, and John could also define a third one.

The independent branches setting as it affects circulation would then become a library setting - Dewey and Ranganathan could have completely separate circulation, while John and Melvyl could allow circulation between the two branches.

Bibliographic records would not have branch ownership - the Dewey and Ranganathan libraries could share the same pool of bib records.

The implementation of this feature would be include the following changes to the database:

• the establishment of a table to track parent-child relationships between branches
• the addition of a branch ownership fields to most tables that contain settings
• the addition of a table to allow a staff operator to have privileges at more than one branch.

The main changes to Koha's code architecture would include

• Making most lookups of settings take the operator's branch into account.
• Refactoring as needed to move all settings lookups into C4.

The main UI changes would include

• Making the Administration pages sensitive to the operators branch.
• UI changes to make it apparent when a setting inherited from a parent branch is overridden by a child.

To ensure that system groups does not add unnecessary complication to Koha users that have a single library in their database, the following compatibility requirements will be met:

• Branch ownership of settings will be an option.
• Parent-child relations between branches will be an option.
• In the database, the default value for the new branch ownership columns will be NULL.

Additional information for system groups RFC

Summary

Various LibLime customers will be hosting multiple independent libraries in a single Koha database. To support this kind of setup, they require that it be possible for various settings to have different values from one system group to another.

Definitions

In this document, a "system group" will refer to an entity whose Koha configuration and policy settings may be different from another system group's settings.

Requirements

In a Koha database with the system groups feature enabled, it should be possible for the following types of configuration information to have different values (or sets of values) from one system group to another.

• Branches, in the sense that a branch should belong to exactly one system group.
• Funds and budgets
• Currencies and exchange rates. The base list of currencies may be shared among the entire database, but the list of "active" currencies and exchange rates should be an attribute of the system group.
• Item types. (Note this assumes that item-level item types are in effect).
• Patron categories
• Circulation rules (i.e., the issuing and fine rule matrix).
• Authorized values (in particular, at least, CCODE, LOC, Asort1, Asort2, Bsort1, Bsort2, STACK, SUGGEST, and possibly the item status ones (LOST, DAMAGED, NOT_LOAN, WITHDRAWN)).
• Classification sources
• Record matching rules
• Network printers
• Z39.50 client targets
• Various system preference (see Global vs. library-specific settings document).
• label templates
• calendars
• notice templates
• notice triggers

The following types of data should be group-specific

• items
• patrons
• guided report definitions
• guide report dictionary definitions
• news
• label batches
• patron card batches
• patron comment queues (?)
• MARC import batches

The following types of settings should be global:

• Patron category types.
• MARC bibliographic and authority frameworks (an argument could be made that this should be a group-level attribute, but at the moment bibliographic and authority records would not have any notion of group-level ownership).
• Stop words
• Various system preference (see Global vs. library-specific settings document).

It is not yet clear whether the following settings should be global or group-level

• Patron cities
• Patron street types

Open questions and assumptions

• It is assumed that bib records are globally shared, and that in no sense does a bib record belong to any system group in particularly.
• Group-level ownership of a bib record, however, may be appealing to certain kinds of consortia.

Proposed Design

To implement system groups, I propose extending Koha's notion of a branch. A branch could now have a parent branch and zero or more child branches. In conjunction with that, most database tables that store configuration would have a branch column added, associating that setting with a particular branch.

A branch would therefore fall into a hierarchy, and a "system group" would consist of a branch and all of its children. There would be an implicit top-most branch, the one with no parent, that contains all of the branches in the Koha database.

For example, let's consider the Presidential Consortium, containing the Washington and Adams library systems. Each library system has two branches, i.e., George, Martha, John, and Abigail. The Koha database would contain seven branches:

• Presidential Consortium (childre are Washington and Adams)
• Washington (children are George and Martha)
• George (no children)
• Martha (no children)
• Adams (children are John and Abigail)
• John (no children)
• Abigail (no children)

Settings associated with a branch can be inherited by its children. Settings will be classified as to whether they are aggregative or overridable. An aggregative setting, such as an item type list, is determined by starting with the current branch (e.g., John), then adding in values from its parent, its grandparent, and so on. An overridable setting can have only one value at a time (i.e., it does not consist of a list), and is determined by first seeing if the setting is explicitly defined for the branch of interest. If not, the parent is checked, and if the setting is not defined, the grandparent is checked, all the way up to the database-level branch.

Setting types will be classified as aggregative or overridable as follows:

• Funds and budgets - aggregative
• Currencies and exchange rates. The base list of currencies may be shared among the entire database, but the list of "active" currencies and exchange rates should be an attribute of the system group.
• Item types - aggregative
• Patron categories - aggregative
• Circulation rules - aggregative
• Authorized values - some aggregative, some overidable
• Classification sources - aggregative
• Record matching rules - aggregative
• Network printers - aggregative
• Z39.50 client targets - aggregative
• Various system preference - overridable

Determining the branch

In most cases, the system group that is active for determining settings will be determined by using the branch that the operator is logged in as. However, for circulation rules, this needs more thought. Uniqueness of codes The following user-visible setting codes are currently unique values as enforced by database constraints:

• branches.branchcode
• itemtypes.itemtype
• aqbookfund.(bookfundid, branchcode)
• categories.categorycode
• class_sort_rules.class_sort_rule
• class_sources.cn_source
• currency.currency
• ethnicity.code
• letter.(module, code)

The following user-visible settings codes are currently non-unique

• authorised_values.authorised_value (nor is the combination of authorised_value and category a unique key)

Existing uniqueness constraints will be left as is. That means that there could be a situation where a system group administrator wants to use a particular code for a new item type but can't because another system group is already using it.