A faster way to install, configure and test FOLIO ILL
Yesterday’s Foundry post was about getting the basics right. Could we install, test and update FOLIO the same way every time? Over the weekend we put that work to use. Snapshot can now start setting up interlibrary loan as soon as it finishes rebuilding. Nobody has to run a script before their first coffee.
That small change gets at a big reason K-Int started Foundry. We want to work in short sprints and put a meaningful improvement in front of someone who can try it. Coordinating a FOLIO release across many teams and modules takes real work, even on a six-month cadence. When a library has a specific problem, we want a way to try an improvement and get feedback within the sprint.
Our colleague Richard Staunton-Mann has been preparing the FOLIO ILL application for upcoming rollouts. It’s the application that lets FOLIO libraries exchange interlibrary loan requests and updates with other systems over ISO 18626. We need to get those changes onto Snapshot continually so people can try them while the work is fresh. But a newly installed ILL app still needs institutions, pickup branches, directories, routing rules and local settings. We already had scripts for much of that. The drag was asking a human to run them every morning after Snapshot’s nightly reset.
Workflow needs an event
Workflow has been part of the FOLIO conversation since the early days. Before WOLFcon 2018, K-Int built a small Camunda module as a proof of concept, separate from the Camunda work by our colleagues at Texas A&M. Our experiment helped us see that the setup jobs we had in mind needed a smaller integration point than a permanent workflow engine.
The useful bit was the signal. FOLIO needs to tell the outside world when something worth acting on has happened. A library can decide what to do with that information in the workflow tools it already uses. For Snapshot, the simplest useful consumer was Python.
This weekend we added Foundry Hooks, starting with a Workspace post-install web event. Foundry sends a CloudEvents message over HTTP to a Python runner in a separate process. For Snapshot we explicitly configured the hook to run configure-ill and pinned a recipe revision. The ILL checkbox in Console controls which module is installed. Removing ILL would leave the hook configured, and the recipe needs ILL’s APIs to succeed. A Workspace with no post-install hook configured sends no such event.
Authentication works in both directions. The Python receiver verifies a short-lived signed token from Foundry and checks that it matches the event ID before it runs the recipe. When Python calls back into FOLIO, it uses a separate, short-lived FOLIO token for a dedicated account in that tenant. FOLIO applies the account’s normal permissions. Both credentials travel in HTTP headers outside the event body.
Here’s an example body for the first ILL recipe that ran on hosted Snapshot.
{
"specversion": "1.0",
"type": "com.k-int.foundry.workspace.post-install",
"source": "/workspaces/snapshot",
"id": "example-run:rebuild-107",
"data": {
"recipe": "configure-ill",
"revision": "1"
}
}See the payload when an ISO 18626 endpoint is available
The later recipe can use the published interlibrary loan endpoint directly. This example uses a placeholder hostname.
{
"specversion": "1.0",
"type": "com.k-int.foundry.workspace.post-install",
"source": "/workspaces/snapshot",
"id": "example-run:rebuild-107",
"data": {
"recipe": "configure-ill",
"revision": "5",
"publishedEndpoints": {
"mod-ill-external-iso18626": "https://api.example.org/external/snapshot/mod-ill/externalApi/iso18626"
}
}
}A clean reset you can work with
The first hosted run created the ILL patron group and enabled multi-institution ILL (video). In a local scheduled reset, the expanded recipe set up two example institutions, their pickup branches, reciprocal routing and the published ISO 18626 address on all four Directory entries. We ran it again and the existing records stayed put. That expanded recipe is staged for the next hosted Snapshot reset; its hosted Directory and staff access checks come after that run.
ILL is where we started. Think about onboarding a library with a directory big enough to need several rounds of review. Put the configuration recipe in Git, load a test dataset and let staff try it. When someone spots an obsolete supplier or a pickup branch in the wrong place, review the change in Git, reset the test Workspace and replay the setup. Now there’s a clean baseline for another round and a record of what changed. The same pattern can be used for other post-install jobs as we add recipes.
Implementors get a proper Python environment for the work. Parse a supplier file, validate it, call FOLIO and check what actually landed. That gives library consortia and teams self-hosting FOLIO somewhere to put their custom setup code. For an example of the workflow those settings support, see our self-hosted FOLIO ILL install and two-library exchange.
Console makes the consequences visible
We also tidied up the Console screens around a Foundry FOLIO Workspace. The release source and update policy have clearer places, and the capabilities list narrows as you type. The plan shows the knock-on effects before you apply it: adding one capability can also propose an upgrade to something you already run.
Resource sharing at the route
External ILL access now sits directly under ILL in Console. Choose Private, publish directory discovery and entries, or publish the directory together with ISO 18626 messaging. For example, a consortium can let partners discover its directory entries before opening the messaging endpoint.
FOLIO’s edge modules provide a place for integrations that need a dedicated adapter. For these ILL endpoints, Foundry uses Envoy, the router it already runs. Envoy publishes the selected paths and methods and applies an authentication and authorization policy to each route. Staff APIs still require a Foundry login and Workspace membership. The published directory and ISO 18626 routes skip the staff login, and ILL owns the protocol checks and the decision to accept a message.
Using the router for gateway policy means one fewer container to run and one fewer hop for requests. A small footprint matters on a developer’s laptop and on a library’s hosting bill.
Why we’re doing this
We started with interlibrary loan, and pretty quickly recognised a source of friction we’d felt elsewhere in FOLIO. We could rebuild the software, but getting it ready for people to use still took a round of manual setup. Once we could run that setup from a versioned recipe, we could use the same approach for the next rollout. That’s what action research looks like for us. Start with the work in front of you, try a small change and see where else it helps.
I want Foundry to be the FOLIO distribution where that kind of work happens. The test is how quickly Richard can get a useful change in front of a library, hear what they think and get the next version back to them. This weekend, we took a whole morning chore out of that loop.
If you’re working on FOLIO resource sharing, planning a self-hosted install or looking for help with custom FOLIO development, get in touch with K-Int or follow us on LinkedIn.