Q2 2020 (Goldenrod) Release Notes

Affected app or module

What has been changed or added that should be noted for this release

What challenges may arise related to this change or addition

If applicable, detail what action(s) must be taken here

When can the action be taken (before, during or after upgrade)

User name of person that can provide additional detail

Name of user leaving comment: comment on what you encountered or ask a question @mention Contact person

Include issue link for bug fix, story or feature that applies

Platform

There are be significant breaking changes to mod-login in this release.  The API has changed as follows:

• POST /authn/credentials - will now return 201 with no body upon successful credential creation. 

• GET /authn/credentials - Removed. 

• GET /authn/credentials/<id> - Removed.  

• PUT /authn/credentials/<id> - Removed. 

• DELETE /authn/credentials/<id> - Replaced by: DELETE /authn/credentials?userId=<userId>. 

It will no longer be possible to manually get or update credential hashes/salts.

Administrative/Operational scripts may need to be adjusted if these API endpoints are used.

Update any scripts as needed

After upgrade

@Craig McNally

While these types of breaking changes may be disruptive, the FOLIO Security Team decided it was worth it since these changes addressed fairly significant security vulnerabilities and the scope of required changes within FOLIO was limited.

https://folio-org.atlassian.net/browse/MODLOGIN-128

https://folio-org.atlassian.net/browse/MODLOGIN-133

https://folio-org.atlassian.net/browse/MODLOGIN-134

Platform

RMB requires all PostgreSQL extensions to be loaded into public schema (RMB-584)

Upgrading may fail with this PostgreSQL error (MODORDSTOR-161): "public.gin_trgm_ops" does not exist

Manually run this SQL in the modules database (okapi_modules for folio-ansible, folio for single-server) (RMB-675):
ALTER EXTENSION pg_trgm SET SCHEMA public

Immediately before starting the upgrade

@Julian Ladisch

https://folio-org.atlassian.net/browse/RMB-675

mod-kb-ebsco-java

Storing Knowledge Base configuration has been moved from mod-configuration to mod-kb-ebsco-java

Unless we migrate those credentials to the correct location, eHoldings app might not work as expected. Please note that this script needs to be run for upgrades that involve data migration. For fresh installs of goldenrod, users can update configuration in Settings - eHoldings - knowledge base from UI.

Run the script attached by filling in okapi endpoint and token kb-migration.sh

After upgrade

@Sobha Duvvuri @Carole Godfrey

@Dima Tkachenko

This has to be the practice until cross-module data migration is supported in FOLIO

RAML Module Builder

RAML Module Builder 30.x includes changes to some of the functions used in database index definition.

This means that an upgrade to a module version using RAML Module Builder 30.x will likely recreate some of the existing database indexes.

As version 30.x is the officially supported version of RAML Module Builder for Goldenrod, it is likely that most storage modules are affected by this.

The process of recreating database indexes   can take a considerable amount of time (in some cases, multiple hours).

Plan downtime appropriately. Potentially change timeouts or similar for clients or intermediaries of the upgrade process.

Prior to upgrade

@Jakub Skoczen

@Julian Ladisch

https://folio-org.atlassian.net/browse/RMB-583

https://folio-org.atlassian.net/browse/RMB-587

Platform

There are changes in the steps/order of operations when upgrading an existing instance of Folio and its respective tenant(s).

Breaking change with the introduction of Okapi SYS# permissions.

RMB requires all PostgreSQL extensions to be loaded into public schema (RMB-584).

There can no longer be a single post of an install.json file to Okapi's tenant install endpoint for an upgrade.

Administrative/Operational procedures and scripts may need to be adjusted.

Upgrading may fail with this PostgreSQL error: "public.gin_trgm_ops" does not exist

If your upgrade fails and you roll back your instance and database, you will need to restart the mod-agreements, mod-licenses and mod-permissions modules before attempting another upgrade.

These components must be upgraded for the tenant in the  order below, ahead of posting the full install.json to Okapi's tenant install endpoint:

-Okapi module 3.1.2

-mod-pubsub

-mod-permissions

-mod-authtoken

Those storage modules which introduce RMB-675 database changes must be enabled for the tenant ahead of the others. mod-orders-storage was updated for Q2 platform-complete, and mod-calendar was updated for Q2 platform-core. You can also manually run this SQL in the okapi_modules database:

ALTER EXTENSION pg_trgm SET SCHEMA public;

Prior to upgrade

@jroot (Unlicensed) @Wayne Schneider @Hongwei Ji @Sobha Duvvuri

This process is still very brittle, and your results will vary depending on:

-If you are coming from the "latest" released Q1 versions of modules, the initial released Q1 versions of modules, or some other mash-up of module versions released prior to Q2.

-If your Okapi is secured or not.

-If you are incremental upgrading, or upgrading all at once.

https://folio-org.atlassian.net/browse/FOLIO-2662

custom-fields (mod-users)

Custom TEXT fields have newly added attribute fieldFormat in Goldenrod

"textField" : {
"fieldFormat" : "TEXT"
}

Custom TEXT fields created in Fameflower and migrated to Goldenrod will need added fieldFormat attribute. 
Without attribute, Exception is observed adding custom fields or assigning custom field to user.

Manually run SQL in mod-users database to add needed attribute update-custom-field.sql

After upgrade

@Carole Godfrey
@Sobha Duvvuri
@Dima Tkachenko
@Pavlo Smahin

https://folio-org.atlassian.net/browse/FCFIELDS-9

mod-login-saml

sp-metadata.xml has changed

Single-Sign-Login (SSO) fails. Error message: Validation of received messages enabled, but no signature found on message.

Download new sp-metadata.xml from Settings->Tenant->SSO settings->Download metadata, and upload it to IdP.

After upgrade

@Julian Ladisch

https://folio-org.atlassian.net/browse/MODLOGSAML-75