AlmaUserAPIUpdater

A Python-based synchronization tool for managing user accounts between a Student Information System (SIS) and Ex Libris Alma library management system via Alma's REST API.

Description

This script automates the process of synchronizing user data between an external SIS and Alma. It handles user creation, updates, and deactivation based on active SIS feeds, ensuring Alma's user database stays aligned with institutional changes.

Key operations:

• Create: Provisions new users from SIS data
• Update: Modifies existing user records when SIS data changes
• Deactivate: Expires and deactivates users no longer present in active SIS feeds

Features

• Full pagination support for Alma user listings
• Rate limiting safeguards to respect API constraints
• Logging to both console and alma_sis_sync.log
• Configurable Alma user group targeting
• Sandbox-friendly test mode with dry-run support
• Template-based design for easy customization

Prerequisites

• Python 3.6+
• requests library
• Alma API key with Read/Write permissions for Users
• Access to SIS data feed (JSON format)

Installation

1. Clone or download this repository.
2. Install required dependencies:

   pip install requests

Configuration

API Credentials

The current script expects ALMA_API_KEY to be provided in AlmaAPIUpdate.py or loaded from your environment.

#ALMA_API_KEY = 'YOUR_API_KEY_HERE'  # Must have Read/Write permissions for 'Users'
ALMA_BASE_URL = 'https://api-na.hosted.exlibrisgroup.com/almaws/v1'

Security Note

Never commit API keys to version control. In production, use environment variables or a secure credential vault:

import os
ALMA_API_KEY = os.getenv('ALMA_API_KEY')

User Group Targeting

Configure which Alma user groups this sync should manage. The script currently uses Alma user_group values, which may be numeric codes in your environment.

TARGET_USER_GROUPS = {'17', '18', '19'}

Sandbox / Test Mode

The script includes sandbox safety flags for development and validation:

• TEST_MODE = True — limits Alma fetches to a small sample and uses one-page-only behavior.
• DRY_RUN = True — prevents actual POST, PUT, and expiration operations.
• TEST_LIMIT = 10 — limits the number of users retrieved during sandbox mode.
• TEST_PRIMARY_ID_PREFIX = 'apitest_' — used for generated test user payloads.
• DISABLE_ORPHAN_DEACTIVATION = True — disables actual orphan expiration in sandbox runs.

Usage

Basic Execution

1. Prepare your SIS data as a list of dictionaries matching Alma's user schema.
2. Call the main sync function:

from AlmaAPIUpdate import run_reconciliation_sync

sis_users = [
    {
        "primary_id": "student123",
        "first_name": "Jane",
        "last_name": "Doe",
        "account_type": {"value": "EXTERNAL"},
        "user_group": {"value": "17"},
        "expiry_date": "2029-06-30Z",
        "status": {"value": "ACTIVE"},
        "contact_info": {
            "email": [{"preferred": "true", "email_address": "jdoe@univ.edu", "email_type": [{"value": "school"}]}]
        }
    }
]

run_reconciliation_sync(sis_users)

Sandbox Simulation

Use the built-in sandbox harness for safe validation of the create/update/orphan-expiration flow:

from AlmaAPIUpdate import run_sandbox_simulation

run_sandbox_simulation()

This simulation is designed to sample a small set of Alma users and execute the workflow without modifying your full production dataset when DRY_RUN=True.

API Limits and Performance

• Rate Limiting: Includes 0.05 second delays between Alma API calls (~20 calls/second max).
• Pagination: Handles Alma list pagination with a configurable batch size and test-mode overrides.
• Recommended Usage: Suitable for smaller institutions or sandbox testing. Larger deployments may require additional batching and optimization.

Logging

Logs are written to both console and alma_sis_sync.log with these levels:

• INFO: General operations and progress
• ERROR: API failures and critical issues
• DEBUG: Detailed operation traces (when enabled)

Data Flow

1. Retrieve: Fetches existing external users from Alma
2. Compare: Matches incoming SIS feed against existing Alma records
3. Create/Update: Creates missing users and updates changed records
4. Deactivate: Optionally expires orphaned users based on active feed membership

Customization

This script is a reference implementation. Typical customizations include:

• Enhanced field comparison and mapping logic
• Support for institution-specific SIS feed formats
• Improved error recovery and retry behavior
• Secure credential management and monitoring

License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

Disclaimer

This is a reference implementation. In production, implement:

• Secure credential management
• Comprehensive error handling
• Monitoring and alerting
• Backup and rollback procedures