2025-04-09 Documentation Working Group Agenda/Meeting Notes

Housekeeping

Katharina

note taker for today: Molly Driscoll
Next meeting is on May 14th at 9am EST / 15 CET

note taker for next meeting: Christine Tobias (Martina Tumulla will provide support)

Announcements

All

No news from the Product Council.

No updates from other SIGs.

Welcome, Susanne, who is joining the group to help with Claiming app documentation. Susanne works for the Bavarian Library Network.

Katharina Jung will be leaving the FOLIO project at the end of May. She will provide next steps at the May meeting. The group wishes her well!

WOLFcon 2025

Katharina

WOLFcon 2025 will be held in Kansas City, MO from September 23 – 25, 2025. Call for proposals has been extended to 4/25.

Katharina put out a call via Slack for proposal ideas.

Christine T. has some ideas but will not be attending WOLFcon this year.

Since the Documentation Working Group has held a session several years in a row, the group determined that it would be acceptable to take a year off if no ideas arise via Slack.

WOLFcon 2026 will be in Prague, Czechia.

Mapping process Okapi Eureka

Christine

Christine provided a tutorial for how to map permissions from Okapi to capabilities in Eureka. This tutorial was also provided at the Sunflower Bugfest kickoff.

Capabilities, capability sets, and authorization roles will replace permissions and permission sets in Eureka.

Thomas Trutt (Cornell) has been pivotal in documenting this transition, but his documentation emphasizes use of APIs, so this tutorial is a supplement showing how to do this via the UI, if desired.

Tutorial:

·       In Sunflower Bugfest, log in with folio/folio.

·       Open Settings > Developer > I can haz capabilities?

·       Enter a permission name.

o   Keyword or exact phrase (with punctuation) works best

o   If not using punctuation with exact phrase (e.g. colons), search will fail with a blank screen

·       Search by permissionDisplayName

o   This is the UI label for the permission

·       Click Search

·       Result set shows equivalent capability or capability sets.

o   For a long result set, use Ctrl+F to identify the desired capability

Search observation (from Laurence M. via chat):

I've been using this method. I've noticed you can search by truncating the beginning or end of a permission name, but it doesn't find any results if you drop something in the middle -- Courses: Add, edit, and remove courses’ reserved items returned nothing because they changed the name (who knows why) to Courses: Add, edit, and remove a courses’ reserved items

Additional notes:

·       Each capability has a different type:

o   Data – front end of system

o   Settings – configuration

o   Procedural – workflow (e.g. opening an order)

·       Application ID:

o   Most apps are part of platform complete, but newly developed apps (e.g. Lists, Bulk edit) have their own applications listed

o   This is important because when building authorization roles, you select the applications you want to select from

·       Resource = capability name

·       Action = view, create, edit, delete, and/or manage

·       Permission name = back-end/API label

·       Permission display name = UI label

·       If assigning a capability set to an authorization role, this auto-assigns all capabilities associated with the set.

Documentation plan:

Replace current permissions list with a table with the following columns:

·       permissionDisplayName (OKAPI) – bolded

·       Resource (EUREKA) – bolded

·       Type

·       Application

·       Action

From Christine:

Here's a draft about mapping Okapi to Eureka: https://docs.google.com/document/d/1kjmlWGOzAMbYtLG90IYWLIcCJ0YNYPOqN78NR8_GN2k/edit?usp=sharing

Discussion:

·       Ben T. indicated that he was having trouble searching and finding appropriate capabilities in Sunflower Bugfest. He confirmed he was logged in as an administrative user.

o   He knew the capability he was looking for, but could not find the capability in the authorization role interface.

o   Advice from Laurence: I think it's easiest to just assign all applications to a role, and then look for the Capability Sets you need.

o   Laurence has discovered some variation in display names.

o   Christine will follow up offline.

·       Molly D. raised the question of if the table should also include a definition of the capability, similar to what’s already in place for Okapi permissions.

o   Laurence raised that this may make the table too wide/less usable.

o   Katharina suggested testing this out in Github.

o   Susanne suggested maybe adding a description for each action above the table.

o   Molly will mock up both approaches for the group to review.

·       Brandon will provide an update on the permissions page at the next meeting.

Stefan created a Jira epic for everyone to add their tasks for updating Okapi permissions to Eureka capabilities, etc.: https://folio-org.atlassian.net/browse/DOCS-524

·       Add this as the parent issue to any tasks in this area

Sunflower check-in

All

·       Aaron N. – will be starting soon; attended Bugfest kickoff

·       Ben T. & Susanne G. – started Claiming page with collaborators; Susanne is ready with the text this week and will submit tomorrow before holidays.

·       Christine T. – making good progress; participated in Bugfest; should be good for the current deadline but asked if this is extended due to delayed Sunflower release (not official yet)

·       Eliana L. – meeting directly after this but making progress; replacing LDP1 with MetaDB; LDLite is not compatible with MetaDB; need to plan for capabilities documentation

·       Emily S. – just finished Bugfest and starting on documentation

·       Emma R. – needs to start; will have it ready for deadline

·       Laurence M. – has participated in Bugfest; submitted documentation to POs for feedback; will work on capabilities next now that we have an approach

·       Martina T. – drafted documentation for number generator and service interaction; needs to add in Eureka capabilities; will contact Emily & Molly about integration into their apps; number generator for Inventory, Organizations for Sunflower (Users not until Trillium)

·       Molly D. – worked on Jiras for documentation; beginning later this week and on track for deadline

·       Stefan D. – ready except for Eureka permissions

·       Wilhelmina R. – has not yet started but will soon

DUE DATES

Sunflower

Sunflower is planned for the end of April 2025 (bug fest March 24th - April 11th)

Documentation deadline as ever 1 week before: April 21st

Trillium

Trillium is planned for November 10th 2025 (bug fest October 3rd - 24th)

Documentation deadline as ever 1 week before: November 3rd

BACKLOG

• Topic documentation archive + navigation in the different releases still open: first idea: use flower symbols from the releases on the top open

• Contact to Julian concerning Docsy Upgrade still ongoing: 1st step update search engine, then theme

• Finding a new place for "Install FOLIO", e.g. in GitHub open