access-models

Apply canonical access model descriptions across Alma institution zones.

The problem

Alma's Access Model configuration table (Configuration > Acquisitions > Licenses > Access Model) cannot be managed centrally at the Network Zone level. Each IZ maintains its own copy, so descriptions drift over time with typos, inconsistent formatting, and stale vendor-supplied defaults.

This tool lets you define descriptions once in a JSON file and push them to all your IZs via the Alma Configuration API. It supports both access model tables:

Table	Canonical file	Where it appears
PublicAccessModel	public_access_model.json	Patron-facing descriptions in Primo
PQAccessModel	pq_access_model.json	Internal descriptions on PO lines

Requirements

• Python 3.10+
• requests library (pip install requests)
• Alma API key(s) with read/write Configuration access (read-only is enough for --export and dry runs)

Quick start

1. Set up API keys

cp api_keys.csv.example api_keys.csv

Add a row for each IZ and NZ with its API key. Leave the apikey column blank for any institution you want to skip.

2. Export current descriptions from one IZ

python update_access_models.py --export --iz 01EXAMPLE_IZ

This fetches both code tables from that IZ and writes them as JSON files. To export just one table:

python update_access_models.py --export --iz 01EXAMPLE_IZ --table PublicAccessModel

Example files are included as public_access_model.json.example and pq_access_model.json.example.

3. Edit the canonical files

Open the JSON files and correct any descriptions. These files are the single source of truth — every IZ will receive exactly these values.

4. Preview changes (dry run)

python update_access_models.py

The script processes whichever canonical files are present. For each IZ, it shows what would change. Any access model codes found in an IZ but missing from your canonical file are flagged as warnings.

5. Apply changes

python update_access_models.py --apply

Options

Flag	Description
--apply	Apply changes. Without this, runs in dry-run mode.
--export	Export an IZ's current descriptions as JSON files. Requires --iz.
--table TABLE	Process only this table (PublicAccessModel or PQAccessModel). Default: all tables with a canonical file present.
--iz CODE	Process only this institution zone.
--region REGION	Alma API region (default: na). See below.
--keys-file PATH	Path to API keys CSV (default: api_keys.csv).

API regions

Region	Code
North America	na
Europe	eu
Asia Pacific (Singapore)	ap
Asia Pacific (Australia)	aps
Canada	ca
China	cn

Example for a European consortium:

python update_access_models.py --region eu

How it works

The Alma Configuration API exposes access models as code tables accessible via GET and PUT at:

/almaws/v1/conf/code-tables/{TableName}

For each institution and each active table:

1. GET the current code table
2. Replace each row's description with the canonical value from the JSON file
3. PUT the full table back (swap-all operation; row order and other fields are preserved)

Files

File	Tracked	Description
update_access_models.py	yes	The script
public_access_model.json.example	yes	Example canonical public descriptions
pq_access_model.json.example	yes	Example canonical internal descriptions
api_keys.csv.example	yes	Template for API keys
public_access_model.json	no	Your canonical public descriptions (gitignored)
pq_access_model.json	no	Your canonical internal descriptions (gitignored)
api_keys.csv	no	Your API keys (gitignored)