Managing Named Users in Alma: Multi-Step Process
Step 1 - Find Alma Users Without Expiration Dates
Based on Code from Github
At a glance
Status: In-Process
Workflow ID: 9hWFoIOOCuguN86e
Version: 95997d36-81cc-43b3-9d5a-811a6960d07c
Environment / Tags: User Record Management; NZ Sandbox; NZ Production
Applies consortium-wide?: No
Runs on: NZ Sandbox and a second selectable Alma environment labeled NZ Production
Trigger: A LibOW web form submitted on demand; there is no automatic schedule.
Primary outcome: Scans Alma user records and emails a CSV listing accounts whose expiry_date is missing or blank.
Who receives results: shields@wrlc.org
Why this exists
User records without an expiration date may remain eligible longer than intended and can be difficult to locate through routine review. This workflow gives staff a repeatable audit that can be run against a selected Alma environment, first on a limited set of records for testing or across all available users.
The results provide the starting CSV for later workflows that assign purge dates and manage expired accounts.
What it does
• Presents a form where the operator chooses NZ Sandbox or NZ Production and enters the maximum number of users to scan.
• Treats a maximum of 0 as “scan all available users”; positive values are capped at 10,000.
• Routes the request to the Alma node associated with the selected environment.
• Requests full Alma user records in pages of up to 100.
• Checks each returned user for an absent, null, blank, or empty-object expiry_date.
• Extracts the Primary ID, preferred or first email address, and patron group for matching users.
• Stores matching rows and internal page-state rows in the users_missing_expiration LibOW data table.
• Continues requesting pages until it reaches the selected limit or Alma’s total record count.
• Builds a CSV report and emails it when matches exist.
• Sends a no-results email when no matching users are found.
Where it runs
Alma IZ(s)
• NZ Sandbox
• A second branch labeled NZ Production
Systems touched
• LibOW / n8n: Hosts the form and coordinates the workflow.
• Alma Users API: Retrieves full user records. An API is a controlled way for one system to request data from another.
• LibOW Data Tables: Temporarily stores matching rows and page-state information.
• Gmail: Delivers the report or no-results notice.
Credentials referenced
• NZ Sandbox - Alma APIs - Read Only
• SCF Sandbox - Alma APIs - Read Only
• Gmail Credentials - Generic LibOW
Reports / queries used
No Alma Analytics report is used.
The workflow queries the Alma Users API with:
• Full expansion
• Page size up to 100
• Offset-based pagination
LibOW data table:
• users_missing_expiration
How it works
Logic overview
The workflow validates the form, creates a timestamp-based run ID, and starts at offset zero. A Switch node selects the environment-specific Alma API node. Each response page is inspected in JavaScript rather than with a visual filter, allowing the workflow to detect several ways an expiration field can be missing or empty.
A page-state row records the next offset and whether more records remain. After the final page, the workflow retrieves all rows for the current run, removes the internal state rows, and creates the report.
If results exist:
The workflow creates and emails a CSV containing:
• Primary ID
• Email Address
• Patron Type
The email includes the run ID, selected environment, number of users scanned, and number of users without an expiration date.
If no results exist:
The workflow sends an email confirming completion and reporting that zero users without an expiration date were found. No attachment is sent.
CSV filename pattern:
alma-users-missing-expiration-<run ID>.csv
Step 2: Add Purge Dates to Alma Users from CSV
At a Glance
Status: In-Process
Workflow ID: WToSDYo9SCv2iZux
Version: 492f03e1-ca18-4316-8507-97642e38075a
Environment / Tags: User Record Management; SCF Sandbox credential
Applies consortium-wide?: No
Runs on: SCF Sandbox Alma environment
Trigger: A LibOW web form submitted on demand; there is no automatic schedule.
Primary outcome: Applies a selected purge date to Alma users listed in an uploaded Step 1 CSV and emails a detailed audit report.
Who receives results: shields@wrlc.org
Why this exists
Step 1 identifies accounts that lack an expiration date. This workflow provides a controlled follow-up process for assigning a purge date to those accounts. It requires an uploaded CSV, a selected date, a processing limit, and explicit confirmation before any Alma record is changed.
The workflow retrieves each complete Alma user record before updating it, reducing the risk of unintentionally replacing unrelated user data.
What it does
• Presents a form for a CSV upload, purge date, maximum number of users, and confirmation checkbox.
• Validates the date, confirmation, file upload, and processing limit.
• Converts the selected date to Alma’s YYYY-MM-DDZ format.
• Reads the uploaded CSV and requires a Primary ID column.
• Removes blank and duplicate Primary IDs and applies the maximum-user limit.
• Processes one user at a time.
• Retrieves the complete Alma user record by Primary ID.
• Changes only the purge_date field and submits the complete user object back to Alma.
• Records GET failures, update failures, and successful updates without stopping the remaining rows.
• Creates a CSV audit report and emails the completion summary.
Where it runs
Alma IZ(s)
• SCF Sandbox
Systems touched
• LibOW / n8n: Hosts the submission form, CSV processing, loop, and reporting logic.
• Alma Users API: Retrieves and updates full Alma user records.
• Gmail: Sends the completion summary and audit report.
Credentials referenced
• SCF Sandbox - Alma APIs - Read & Write
• Gmail Credentials - Generic LibOW
Reports / queries used
No Alma Analytics report is used.
Input requirement:
CSV column: Primary ID
Alma operations:
• Get one complete user record
• Update one complete user record
How it works
Logic overview
The form submission is validated before processing begins. The CSV is converted into one LibOW item per unique Primary ID, subject to the maximum-user safety limit. A loop retrieves the complete user, makes a deep copy, changes purge_date, and sends the updated record through the Alma API node.
Each iteration returns a final success or failure row. The loop’s completed output is checked against the number of queued users before the final report is created.
If results exist
This workflow always produces an audit result for every queued row:
• Successful users are marked Success.
• Retrieval or update failures are marked Failed, with the failure stage and available error details.
The workflow emails the CSV audit report after processing completes.
If no results exist
The workflow does not have a separate no-results branch. It stops with an error when the uploaded CSV has no data rows or contains no usable Primary IDs.
Step 3: Alma Expiration Checker
At a glance
Status: In-Process
Workflow ID: JjlojFEXPvTm7D06
Version: d93597a4-ef2b-43d3-afe8-ca234c4b4d2b
Environment / Tags: User Record Management; NZ Sandbox; NZ Production
Applies consortium-wide?: No
Runs on: NZ Sandbox and a second selectable Alma environment labeled NZ Production
Trigger: A LibOW web form submitted on demand; there is no automatic schedule.
Primary outcome: Finds users whose expiration date is on or before a selected date and emails CSV and JSON reports.
Who receives results: shields@wrlc.org
Why this exists
After purge dates have been assigned, staff need a repeatable way to identify accounts that have reached or passed an expiration threshold. This workflow scans a selected Alma environment and produces a reviewable list without changing user records.
The output CSV is designed to serve as the input for the later deactivation workflow.
What it does
• Presents a form for Alma environment, expiration cutoff date, and maximum users to scan.
• Treats 0 as “scan all users.”
• Converts the selected date to the end of that calendar day.
• Routes the request to the selected environment’s Alma node.
• Retrieves full Alma user records in pages of up to 50.
• Reads multiple possible expiration-field names and parses date-only or ISO date formats.
• Includes users whose expiration date is on or before the selected cutoff date.
• Collects Primary ID, first name, last name, preferred email, and expiration date.
• Continues through pages until the selected limit or total Alma user count is reached.
• Emails CSV and JSON reports when matches exist, or a no-results notice otherwise.
Where it runs
Alma IZ(s)
• NZ Sandbox
• A second branch labeled NZ Production
Systems touched
• LibOW / n8n: Hosts the form, pagination, date comparison, and report creation.
• Alma Users API: Retrieves full user records.
• Gmail: Sends reports or a no-results notice.
Credentials referenced
• NZ Sandbox - Alma APIs - Read Only
• SCF Sandbox - Alma APIs - Read Only
• Gmail Credentials - Generic LibOW
Reports / queries used
No Alma Analytics report is used.
Alma Users API configuration:
• Full user expansion
• Page size up to 50
• Offset-based pagination
How it works
Logic overview
The form validates the selected environment, cutoff date, and scan limit. The cutoff is stored as 23:59:59.999 UTC on the chosen date, so users expiring at any time on that date are included.
The workflow accumulates matching users across Alma pages. Pagination continues until all selected users have been examined. The final report builder creates both CSV and JSON versions of the matching records.
If results exist
The workflow emails two attachments:
1. A CSV report with:
• primary_id
• first_name
• last_name
• email
• expiration_date
2. A JSON report containing the same matching user records.
If no results exist
The workflow sends a completion email reporting that no expired users were found. It does not attach CSV or JSON files.
Step 4: Deactivate Alma Users from Step 3 CSV
At a glance
Status: In-Process
Workflow ID: H6EbLWv8vYyUf1AY
Version: 1ed30e19-195a-42f1-97be-a9cc0bdb16eb
Environment / Tags: User Record Management; NZ Sandbox; NZ Production
Applies consortium-wide?: No
Runs on: NZ Sandbox and NZ Production
Trigger: A LibOW web form submitted on demand; there is no automatic schedule.
Primary outcome: Changes users listed in the Step 3 CSV to INACTIVE, assigns the PurgePending user group, and emails an audit report.
Who receives results: shields@wrlc.org
Why this exists
Step 3 identifies accounts that have reached or passed the selected expiration threshold. Step 4 performs the controlled account change: it deactivates the selected users and places them in the PurgePending Alma user group.
Because this workflow modifies patron records, it includes an explicit confirmation checkbox, environment selection, and a maximum-user testing limit.
What it does
• Presents a form for the Step 3 CSV, Alma environment, maximum users, and deactivation confirmation.
• Treats a maximum of 0 as “process all CSV rows.”
• Validates the file, environment, limit, and confirmation.
• Reads primary_id values from the Step 3 CSV and removes blanks and duplicates.
• Processes one user at a time.
• Retrieves the complete user record from the selected Alma environment.
• Skips a user only when the account is already INACTIVE and already belongs to PurgePending.
• Otherwise sets status to INACTIVE and user group to PurgePending.
• Removes fields known to cause update errors, filters unsupported phone types, and deduplicates identifiers.
• Updates the full Alma user record and records success, skip, retrieval failure, or update failure.
• Creates CSV and JSON audit reports and emails them after the loop completes.
Where it runs
Alma IZ(s)
• NZ Sandbox
• NZ Production
Systems touched
• LibOW / n8n: Hosts the form, file processing, loop, record preparation, and reporting.
• Alma Users API: Retrieves and updates complete user records.
• Gmail: Sends the completion report and attachments.
Credentials referenced
• NZ Sandbox - Alma APIs - Read & Write
• NZ Production - Alma APIs - Read & Write
• Gmail Credentials - Generic LibOW
Reports / queries used
No Alma Analytics report is used.
Input CSV must contain one of these user identifier headings:
• primary_id
• Primary ID
• user_id
• User ID
Alma operations:
• Get User Details
• Update User Details
How it works
Logic overview
The workflow turns each unique identifier in the uploaded file into one loop item. A Switch node chooses the correct environment-specific GET credential. The complete user record is inspected before any change is made.
If the user is already inactive and in PurgePending, the workflow records a skip. Otherwise, it prepares a full update payload that changes the status and group while retaining the rest of the user data. A second environment Switch sends that payload to the corresponding update node.
All terminal paths return a final audit row to the loop. The report builder verifies that the number of final rows equals the number of queued users.
If results exist
Every queued user produces one of these outcomes:
• Success: Alma accepted the update.
• Skipped: The user was already inactive and already in PurgePending.
• Failed: The user could not be retrieved or updated.
The workflow emails CSV and JSON audit reports containing these results.
If no results exist
There is no separate no-results email branch. The workflow stops with an error if the uploaded CSV has no rows or contains no usable user identifiers.
Artifacts produced
Filename patterns:
deactivation_results_<environment>_<run ID>.csv
deactivation_report_<environment>_<run ID>.json
CSV columns:
• primary_id
• status
• stage
• http_status
• reason
• tracking_id
• processed_at
Step 5: Check PurgePending Users
At a glance
Status: In-Process
Workflow ID: iCDoBVA4jONrRGWc
Version: efa5b58e-02ac-4e3a-83f3-569ae76405cd
Environment / Tags: User Record Management; NZ Sandbox; NZ Production
Applies consortium-wide?: No
Runs on: NZ Sandbox and NZ Production
Trigger: A LibOW web form submitted on demand; there is no automatic schedule.
Primary outcome: Reviews uploaded Alma users, identifies those in PurgePending or DEL, classifies their expiration status, and emails CSV and JSON reports.
Who receives results: shields@wrlc.org
Why this exists
After user accounts have been deactivated and moved into a purge-oriented user group, staff need a verification step before any later deletion or cleanup process. This workflow provides a read-only audit of the selected accounts.
It distinguishes users that are expired, not yet expired, missing an expiration date, assigned to another group, or unavailable through the API.
What it does
· Presents a form for a CSV or TXT file, Alma environment, and maximum number of users.
· Treats 0 as “check all uploaded IDs.”
· Accepts the Step 4 results CSV or a single-column list of Alma Primary IDs.
· Recognizes several identifier headings and removes blank or duplicate IDs.
· Processes one user at a time.
· Retrieves the complete user from the selected read-only Alma credential.
· Checks whether the user group is exactly PurgePending or DEL.
· Classifies matching users as EXPIRED, NOT_EXPIRED, or NO_EXPIRY.
· Counts users in other groups and users that could not be retrieved.
· Creates a CSV containing the PurgePending and DEL analysis and a JSON file containing the full summary.
· Emails both files after all IDs have been checked.
Where it runs
Alma IZ(s)
· NZ Sandbox
· NZ Production
Systems touched
· LibOW / n8n: Hosts the form, uploaded-file processing, loop, classification, and report creation.
· Alma Users API: Retrieves complete user records without modifying them.
· Gmail: Sends the analysis and summary.
Credentials referenced
· NZ Sandbox - Alma APIs - Read Only
· NZ Production - Alma APIs - Read Only
· Gmail Credentials - Generic LibOW
Reports / queries used
No Alma Analytics report is used.
Accepted input formats:
· CSV
· TXT
· Step 4 results CSV
· Single-column identifier list
Recognized identifier headings:
· primary_id
· Primary ID
· user_id
· User ID
· ID
How it works
Logic overview
Each unique uploaded identifier becomes one loop item. A Switch node selects the appropriate Alma environment. The returned user record is inspected for its user-group code and expiration date.
Only users whose group code is exactly PurgePending or DEL are included in the CSV analysis. Users in other groups and API failures are retained in the JSON summary and counted in the email.
Expiration comparison uses the current UTC calendar date:
· Earlier than today: EXPIRED
· Today or later: NOT_EXPIRED
· Missing or unreadable date: NO_EXPIRY
If results exist
The workflow always produces an analysis package when valid IDs were queued.
The CSV includes only PurgePending and DEL users with:
· Primary ID
· User Group
· Expiry Date
· Status
The JSON summary also includes:
· Users in other groups
· Failed API retrievals
· Counts for each classification
If no results exist
There is no separate no-results branch. If no uploaded IDs belong to PurgePending or DEL, the CSV contains only its header row, while the JSON and email report zero matching users and include the other-group or failure counts.