Important Upgrade Considerations
This section outlines all changes that require special consideration for customers in production. Configuration changes may be needed to prevent operational interruptions. See checklist for guidelines on how to fill this out.
Changes and Required Actions
|Functional Area||Change or Addition||Considerations||Action required||Action timing||Contact person||Comments||Related JIRA issues|
|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|
|mod-inventory-storage||The module now depends on Kafka message broker. Kafka should be up and running before module install.||Inventory-storage APIs (instances/holding-records/items - create, update, delete actions) will fail with 500 status code if Kafka is unreachable.||Make sure KAFKA_PORT and KAFKA_HOST environment variables are set and propagated to the mod-inventory-storage container before module installation.|
Example: for rancher dev environments we set following values - KAFKA_HOST: kafka, KAFKA_PORT: 9092
|Before upgrade||The same approach as for mod-pubsub may be used here. We tried to follow the same naming for the properties.|
|mod-inventory-storage||Statistical code ||The upgrade process will fail when there are two or more statistical codes with the same name prior to the upgrade||Change the name of any existing statistical codes that are the same as another statistical code||Before upgrade|
Changes to the default MARC Bib-to-Instance map:
|If library has customized the default MARC bib-to-Instance map, review these changes and decide if they should be added to the library's custom map. If changes are made, you may need to trigger a refresh of the existin gInstances that are based on the SRS MARC records, so that the changes are reflected in the Instance|
|mod-source-record-storage||An end point has been added to allow searching MARC records.||The end point will only return results from MARC records added after the upgrade. A script to retroactively process pre-existing records has been developed, see MODSOURCE-276: Add existing records to the SRS Query API table||To add records that existed prior to upgrade to the query search see MODSOURCE-276: Add existing records to the SRS Query API table Script: https://github.com/folio-org/mod-source-record-storage/blob/master/mod-source-record-storage-server/src/main/resources/migration_scripts/fill_marc_indexers.sql||After upgrade|
|mod-circulation||The age to lost processes (||No items will be aged to lost and no fees / fines will be issued unless these processes are scheduled by the hosting provider|
Organisations who need these processes to run will have to schedule them from outside the system
Configuration needed by the hosting provider
Organisations will likely need to schedule these processes separately meaning two separate tasks and schedules are likely to be needed (separate users may be used for each process)
New External Endpoints
No body needs to be provided to make requests to either of these endpoints.
Further documentation is available at How to Schedule Age to Lost Processes
|During or after the upgrade|
|mod-kb-ebsco-java||New feature "Usage Consolidation" is now supported||Configuring Usage Consolidation settings||In order to configure "Usage Consolidation" → apart from the settings on UI, middle layer service needs to be configured by making a query directly to DB like the below:|
INSERT INTO <tenant_id>_mod_kb_ebsco_java.usage_consolidation_credentials(client_id, client_secret) VALUES (?, ?);
User stories have been created to make this configurable from UI.
|After upgrade to Iris|
|mod-ncip||New permission required to call NCIP services:||During or after upgrade|
|mod-oai-pmh||This is not a required step but we noticed during tests that if the mod-oai-pmh performance is poor, re-indexing and vacuuming indexes located in mod-inventory-storage resolved the issue.||During or after upgrade|
|mod-data-import, mod-source-record-manager, mod-source-record-storage, mod-inventory, mod-invoice||All modules involved in data import process are now communicating through Kafka directly. Kafka should be configured and running before modules are installed and additional parameters should be set for modules.||New setup and configurations required||Follow the instructions to set all the necessary parameters for Kafka and the modules||Before and during the upgrade|
Since 1.3.0 version OKAPI_URL environment variable is required for the module.
|Data ingestion won't work.||Set/pass OKAPI_URL to the application container.||On module startup.|
|mod-pubsub||Environment variables SYSTEM_USER_NAME and SYSTEM_USER_PASSWORD can be used to set up credentials for PubSub system user. Otherwise, default values (username pub-sub, password pubsub) will be used.||Not providing these variables will result in using default credentials which is considered a security issue.||Set SYSTEM_USER_NAME and SYSTEM_USER_PASSWORD environment variables.||On module startup.|
|mod-agreements||When upgrading from Goldenrod consider running the Supplementary Document cleanup job on initialising the module in the tenant.||The Supplementary Document cleanup job fixes an issue that could lead to a single supplementary document being linked to multiple agreements. The cleanup job will detect this situation and duplicate the document so each agreement is linked to it's own copy of the document|
On installing/starting the module in the tenant, include
in the tenantParameters.
|On module startup.|
|mod-patron-blocks||Events which took place before first mod-patron-blocks deployment are NOT taken into account while calculating automated patron blocks.||This is an inherent limitation of mod-patron-blocks which is an event-based system.|
If tenant plans on using Automated Patron Blocks feature AND full event synchronization has not been performed before, follow steps outlined in Q3 2020 (Honeysuckle) Release Notes.
Remote storage integration (Dematic)
Remote storage integration for Dematic StagingDirector and Dematic EMS. Accessed through Settings > Remote storage and Settings > Tenant > Location.
Circulation log export to CSV
This feature will allow a user to export filtered data in the Circulation log to a CSV file. Accessed through the Circulation Log app > Run a search > Open the “Actions” drop-down list > Select “.CSV export”
Cornell Library's go-live requirements to transfer fees/fines to the Cornell bursar system
Automated Transfer of fees/fines to bursar or other account. Accessed through Settings > Tenant > General: Bursar (to run a Bursar export manually or set the scheduling parameters for the export)
|App||New Permissions||Deprecated Permissions||Product Owner|
|Data import||Renamed UI: ui-data-import module is enabled to Data import: all permissions, to make it clearer. Scope of the permissions did not change.|
|Data import||Renamed Settings (data-import): display list of settings pages to Settings (Data import): Can view, create, edit, and remove, to make it clearer. Scope of the permission did not change.||Ann-Marie Breaux|
The option to add tags to Inventory record types (instance, holdings, item) now has the consequence that anyone with inventory permissions should have their permissions edited to add either the Tags on records: View only or Tags: All permissions
Important: If the user permissions are not updated as described above, then the Inventory app will not display in the top menu bar for the user with the Inventory app permissions.
We have implemented the possibility to move holdings and item in Inventory, but any transfers are not yet being reflected in dependent apps; e.g. Orders, Request, and Courses. In order to prevent corrupt data it's highly recommended that all libraries limit the ability to move holdings and item by limiting the number of staff having the appropriate user permission to move holdings and item.
|Remote Storage||Remote storage integration has one level of permissions - Remote storage: Create, read, update, delete. A user with these permissions can create and configure remote locations. |
Any user with Inventory: View, create, edit instances has the ability to change the location of holdings and items to remote storage, and from remote storage to main locations.
New Permissions: ui-checkout.viewRequests, ui-checkout.viewLoans, and ui-checkout.viewFeeFines
UI-only permissions that control whether the Loans, Requests, and FeeFine information in the user pane of Check out are active hyperlinks to their respective information.
Important: these permissions are not included in any other permission set by default, including ui-checkout.all, and they are required to enable the indicated hyperlinks in Check out.
|quickMARC||quickMARC: Derive new MARC bibliographic record - this permission allows one to derive a new MARC bib record from an existing MARC record||Khalilah Gambrell|
|Local KB Admin|
- Most front-end modules don't fetch exact search result count from backend ( - RMB-673Getting issue details... STATUS ).
- Estimated search result count has a wording that incorrectly suggests it is a precise number ("8081 records found"). Only numbers below 1000 are precise (details: RMB Estimated totalRecords). (WIP - UXPROD-2623Wait for POC of Elastic Search - Round estimated search result hit count (totalRecords) Blocked )
- Some modules fail in Pgpool-II replication ( - FOLIO-2447Getting issue details... STATUS , - FOLIO-2978Getting issue details... STATUS ).
|App||Known issue||Workaround||JIRA issue||Product Owner|
|Orders and Receiving||Data corruption. When holding/item data are moved in Inventory the connected Order lines are not updated accordingly. The PO remains linked to the original instance and items but location IS NOT updated. This could result in receiving of unreceived pieces generating new holding records or moving back to the original instance.||The current workaround is to be very judicious in allowing users to move items and holdings in Inventory when there are open orders related to item records. We suggest ONLY granting certain users this ability for now. All short term fix we attempted to put in place while we wait for a more systemic resolution to the underlying issue would introduce problems of its own.|
|Orders and receiving|
If users "Unopen" orders that have "Manually add pieces for receiving" = true. If they had created any pieces they will not be able to open the order again without deleting pieces from the receiving area. System will force user to delete as part of open order process.
|You can recreate the necessary records after the opening the order again.|
|Orders||Possible to save POL with no location even though location is a "required" field. This can happen when you use an order template to add a location field set with only quantity populated||When order fails to open edit POL and select a location. Save POL and Open when desired.||Dennis Bridges|
|mod-orders-storage||If OKAPI_URL contains a path after the hostname like https://example.com/okapi the upgrade always fails.||no known workaround|
|Organizations||When fields within a closed accordion are invalid the UI does not force them open when trying to save the record. This may confuse users as to why they cannot save edits to an organization record||Click "Expand all" accordions and look for the validation errors. This may be empty required fields or invalid data added during a migration.||Dennis Bridges|
|Data export||Holdings' permanent location or item's effective location not always populated during the export while using a custom mapping profile.||Not known at this point. We believe this is the data corruption issue as we were not able to recreate it on other than Bugfest environments.||MDEXP-391|
|OAI-PMH||Holdings data is not discoverable when item record is suppressed||Not known at this point||MODOAIPMH-317|
|Requests||Out of sync data: When holding/item data are moved, or other updates made to items, in inventory, any connected requests are not updated accordingly (eg. new barcodes, title, or instance identifiers)||Take care when modifying items with open hold requests.|
|Circulation log||Loan details from the Action dropdown in the Log will sometimes show an error message BEFORE loan details actually load.||Give the record a little time to load, or get Loan details from another source, like the Item record||Stephanie Buck|
|Claimed returned fees/fines|
There were two bugs discovered in the Iris BugFest after the test cases had been passed and just before Iris was to be released. They were caused by changes to the code in BugFest that adversely impacted what had already been tested. As there are easy workarounds, the two bugs will not be fixed until the Juniper (R2 2021) release.
Bug 1: When checking in a claimed returned item, the "suspended" lost item fees are not being cancelled (UICHKIN-252)
Bug 2: When resolving a claimed returned situation, the lost item fees are not cancelled if they have had a transfer made before they were claimed returned (UICIRC-570)
We also have a bug that was found earlier that we were unable to fix for the Iris Release.
Bug 3: For aged to lost items that are claimed returned, and then returned by patron, if the Lost Item Processing Fee is not refunded the Payment Status should be updated to "Outstanding" (UIU-2129)
Bug 1: The "suspended" Lost Item Fee and Lost Item Processing Fee (if there is one) remain suspended after claimed returned item is check in. Given they are "suspended", the patron is not being held liable for the fees. The library is able to waive the "suspended" lost fees to remove them from the "suspended" status.
Bug 2: The "suspended" Lost Item Processing Fee appears in the Closed Fees/Fines tab, so the patron is not being held liable. This should not be a problem at all for libraries that don't transfer fees/fines or don't do it quickly.
Bug 3: This only impacts you if your institution is using aged to lost processing and do not refund the Lost Item Processing Fee if a lost item is returned. The Lost Item Processing Fee will remain as "Suspended claim returned." It can be paid with this status, but more likely you will want to waive the original Lost Item Processing Fee and create a new one as a manual charge.
Overdue fines not charged when charging overdue fines by the minute over periods when library is opened then closed
|This bug only impacts you if your institution bills overdue fines by the minute and does not charge overdue fines when the library is closed. You will need to update your "Overdue fine" policies to use hours (or anything other than minutes) as the "Interval".||CIRC-1135||Holly Mistlebauer|
|Manual fees/fines||When creating a new manual fee/fine, if you enter a comma in the "Fee/fine amount" field the value will not be saved properly despite looking correct (for example, "1,000.00" will be saved as "1.00").||Do not enter a comma in the "Fee/fine amount" field on the "New fee/fine" page.||UIU-2156|
|Mod-finance-storage||Transaction table upgrade failure when purchase order record is missing. Discovered when upgrading from mod-finance-storage-6.0.1 to mod-finance-storage-7.0.2||Delete orphaned encumbrance transaction records. Retry migration. See script in comment here from Wayne for more information.|
|Data Import||MARC record field protection is not yet working correctly|
|Data Import||EDIFACT invoices can be imported, but invoice and invoice-line adjustments still need additional work. Also, if an incoming invoice line does not link to a corresponding purchase order line, there is no manual way to link them in Iris (will be available in Juniper). If the EDIFACT invoice file has an upper-case file extension (e.g. EDI), it much be changed to lower-case (e.g. edi) before uploading and importing.|
For invoice and invoice-line adjustments, enter them manually after the rest of the invoice has been imported.
For invoice lines that do not match to purchase order lines, 1) delete the invoice line, and add the invoice line manually, based on finding and linking the purchase order line manually. Or 2) review the matchpoints in the invoice data, and manually edit each purchase order lines to include those matchpoints manually, Then delete the imported invoice, and re-import it. This time the incoming invoice-lines should match to the corresponding purchase order lines.
|Local KB Admin Settings||The "LOCAL" knowledgebase appears as editable in the settings. Only external data sources should be visible and editable in this screen. Editing the LOCAL knowledgebase could cause issues or the creation of an addition LOCAL knowledgebase (if the name is changed)||Do NOT edit the LOCAL knowledgebase in the settings|
|Mod-invoice and mod-finance||Credit invoice results in a credit of $0 being charged to the fund. Meaning $0 is added back to the Fund.||No current workaround. Suggesting libs avoid creating credit invoices. This should be resolved in a hotfix release|
|Courses||An error in the "Courses: All Permissions" system-defined permission set was inadvertently introduced as part of the Iris release and not discovered until Iris implementer sites began testing. Users with the permission set "Courses: All Permissions" and no other Courses permissions cannot edit courses.|
The workaround is not use the Courses: All Permissions set, and instead assigned Courses app users a mix of the segmented permissions that allows them to have desired create/edit functionality:
The Courses: All Permissions set is fixed as of the Juniper release, so permissions can be reverted at that point.
Notes on functionality
There are several changes related to migration of static (system-defined) permissions introduced in Iris:
- When permissions that once appeared in a module descriptor are removed in a newer version of the module descriptor, they will be marked deprecated.
- In Iris, this means the
displayNameof these permissions will be prefixed with "
(deprecated)", but the permissions will not be filtered out of any API calls.
- Eventually we'd like to filter deprecated permissions out of API responses unless they're specifically requested. This feature, however, did not make it into Iris.
- In Iris, this means the
- Permissions can now be renamed via a new "
replaces" property. Perm-users (Assignments) and PermissionSet sub-permissions will be updated automatically.
- Example: "
foo.get" replaces "
foo.view". Any users which were assigned either "
foo.read" or "
foo.view" would automatically be granted "
foo.get". Permissions "
foo.read" and "
foo.view" would be marked deprecated.
- Example: "
- A new "
purgeDeprecated" API has been introduced to allow an operator to purge deprecated permissions. This will:
- Remove deprecated permissions from the system
- Remove deprecated permission names from user's permission assignments
- Remove deprecated permissions from permission sets
- N.B. This API should only be called once you're confident that a module downgrade will not be required. Once deprecated permissions are purged, the system will not know how to "undo" the permission migration for that module.
- N.B. Currently this is an all-or-nothing operation. There is no way to purge individual deprecated permissions, or remove deprecated permissions for a particular module.
- If a permission name collides with a user-defined permission with the same name,
- In Iris, the call to enable the module (install/upgrade) will fail with an appropriate error message.
- Eventually we'd like to do something like rename the user-defined permissions and adjust assignments as needed.
- All system-defined permissions will now include context about the module that defined them (new permission fields
- Duplicate permission definitions are not allowed. If a permission (name) is defined by multiple module descriptors the upgrade will fail with an appropriate error message.
mutableproperty will now be ignored when creating or updating permissions. This is a system-controlled field.
- Orphaned system-defined permissions - those which are marked as immutable and are no longer present in any enabled module descriptor - will automatically be deprecated when upgrading mod-permissions.
- If you want to benefit from permission migration you need OKAPI v4.6.0 or greater (v4.7.2 or greater is highly recommended) and mod-permissions v5.13.0.
- Contrary to earlier communications, it is NOT required to upgrade mod-permissions first or last. It is also NOT required that you upgrade to the latest Honeysuckle Hot Fix release prior to upgrading to Iris.
- Supported in Iris:
- Create and update Inventory Instances, Holdings, and Items
- MARC record modifications to add, remove, and change constant data within the incoming file
- MARC-MARC matching on 001 and 999 ff fields, but not any other MARC fields
- EDIFACT invoice loading
- For importing EDIFACT invoices, the User needs these permissions
- Data import: all permissions
- Settings (Data import): Can view, create, edit, and remove
- Invoice: Assign acquisitions units to new record
- Invoice: Can view, edit and create new Invoices and Invoice lines
- Invoice: Can view, edit and delete Invoices and Invoice lines
- Implemented configurable number of locations
- UIIN-1480 - in order to support library systems with more and more locations, then we have implemented a change and made the number of locations configurable in the platform' Stripes configuration file, stripes.config.js
- Supported in Iris:
- Assign tags to Instances, Holdings, and Item records, and filter by them
- Add a Java-based migration process for item effectiveShelvingOrder property, this has following impact:
- Module initialization takes significant time for migration to 20.2.1 version (the process is triggered only once), currently it is up to 5 hours. It is recommended to run this process at non working hours, because mod-inventory-storage is a critical part of FOLIO, most subsystems will be irresponsible.
- The migration process does not generates domain events for updates.
- Override blocks on requests:
- UXPROD-2910 - Added the ability to override patron and item blocks on requests
- Warning modals when an item with pending requests is marked missing, withdrawn, claimed returned, or declared lost:
- UXPROD-2411 - When changing an item's status to missing or withdrawn in Inventory or claimed returned or declared lost in Users, a modal stating the number of open requests (with a link to the request queue) will be presented to staff with the option to cancel the status change
- Patron comments on requests:
- UXPROD-1800 - Added a patron comments field to requests that can be entered by staff or via the edge-patron API (discovery) and is available as a token in staff slips and the Requests interface
- Check Removed Loan and User detail links when circulation action has been anonymized
- Removed Loan details when circulation action includes multiple barcodes (item details available through linked barcode)
- Checked in filter added to Loans dropdown
- Dates reformatted to match dates in the rest of FOLIO
- Updated search boxes to free-text format as in the rest of FOLIO
Claimed returned fees/fines
As discussed with the Resource Access SIG, not all of the claimed returned fee/fine changes have been included in Iris. The remainder will be finished for Juniper. Please see the Google Sheet here to see what is included in each release. Holly has also updated Emma's Claimed Returned Flowchart to show what is in Iris (R1) and Juniper (R2), which was helpful for her and may help you as well. (Important note: There were two bugs discovered in the Iris BugFest after the test cases had been passed and just before Iris was to be released. They were caused by changes to the code in BugFest that adversely impacted what had already been tested. The two bugs are described in the "Known Issues" section above.)
- Changes to Agreement periods and start and end date management mean that:
- The earliest period start date is now treated as the agreement start date
- The latest period end date is now treated as the agreement end date, or if there is a blank period end date the agreement is treated as having no end date
- If only a single agreement period is used, no other information is displayed in relation to periods, allowing tenants to use single periods as the start/end date for an agreement
- If multiple agreement periods are used it is easy to see the "previous", "current" and "next" periods for the agreement as well as view the details of all the agreement periods
- Agreements can be searched by start and end date
- When an agreement line is linked to a Purchase Order Line that is linked to an Inventory instance, a link directly to the Inventory instance is displayed in the Agreement Line display
- In the Agreement display any accordions not populated with data and not otherwise required are not displayed to the user, simplifying the display
- Keyboard shortcuts now supported
- Separate actions buttons (Edit, Delete, etc.) replaced by single Actions menu
- New settings (Settings → Agreements → Display settings) to control the number of lines to show per page (i.e. before showing the "Load more" button) in multi-column lists (tabular lists) across the Agreements application. The default value for all lists is 10. The multi-column lists affected are:
Agreement view pane > Agreement lines
Agreement view pane > E-resources covered by this agreement
E-resource view pane > Options for acquiring e-resource
Package view pane > E-resources in package
E-resource view pane > Agreements for this e-resource
Agreements Local Knowledgebase
- Support for proxy server and platform dependent URL customisations. See Proxy server configuration and URL customizations for a full description of this functionality.
- Platform search and view added to Agreements app to support the ability to manage platform dependent URL customisations
- Tags and tag search now supported for Titles and Packages in the local KB
- "Suppress from discovery" flag now supported (edit and display) for Titles and Titles in a Package as well as Agreement Lines
- Links on Titles in the "E-resources covered by this agreement" list now link to the Title in Package record rather than the Title record
- In Local KB Admin Separate actions buttons (New, Delete, etc.) replaced by single Actions menu
- Keyboard shortcuts supported in Local KB Admin app
- Keyboard shortcuts supported in ERM comparisons app
- Support for duplicating amendments on a license
- Keyboard shortcuts now supported
- Separate actions buttons (Edit, Delete, etc.) replaced by single Actions menu
- Ability to search licenses by start and end date
- In the License display any accordions not populated with data and not otherwise required are not displayed to the user, simplifying the display
- When duplicating a license the license term values are now included in duplication
- On license CSV export the escape character used changed from backslash (ASCII 92) to quote mark (ASCII 34) for improved compatibility with common software used to view CSV files (specifically Microsoft Excel)
Hot fix release #1 - RELEASED AT MAY 28
Module mod-aes removed from the Iris release platform by request of the dev team (Hongwei Ji and Matt Reno). Was added by mistake
Hot fix release #2 - TO BE RELEASED AT JUNE 25
New Features by Epic (Sub-Project)
|RAML Module Builder||0||1||1||0||4||6|
|Total Unique Issues:||28||111||121||14||126||400|
View in Jira
All Closed Bugs and Stories
|Folio Automation Testing||0||0||1||0||0||0||1|
|RAML Module Builder||0||1||1||0||0||5||7|
|User Experience Design||0||3||8||0||0||1||12|
|Total Unique Issues:||31||239||557||21||1||277||1126|
View in Jira
Remaining Open Bugs at Time of Release
|Folio Automation Testing||1||0||0||1||0||0||2||4|
|RAML Module Builder||0||0||12||17||0||0||32||61|
|User Experience Design||0||0||0||0||0||0||1||1|
|Total Unique Issues:||1||69||418||387||57||4||439||1375|