📖 Context-Sensitive Portal Help
Comprehensive field descriptions, validation rules, and example entries for all portal forms.
⚡ Jump to Form Reference Table
1. User Login Form
Route: /login
Go to Form →
Authenticates staff members into the pyrelibconnected Admin Portal. Passwords are validated against secure Argon2id hashes stored in the database.
| Field Name | Field Description | Example Entry |
|---|---|---|
Username (username) |
Unique staff login name used to identify the user account during portal authentication. | jlynch |
Password (password) |
Secret staff account password. Validated against Argon2id password hashes. Must satisfy system policy: minimum 14 characters, including uppercase (A-Z), lowercase (a-z), and numerical digit (0-9). | •••••••••••••••• (Masked input) |
Forgot Password: If you have forgotten your password, please request account assistance using the Library IT Help Form.
2. Web Student CSV File Upload Form
Route: /admin/upload-test
Go to Form →
Uploads a student CSV data file and enqueues an asynchronous Redis background job to test patron record ingestion and overlay logic.
| Field Name | Field Description | Example Entry |
|---|---|---|
Target School District (district_id) |
Dropdown selection specifying the target district namespace and ID for processing incoming patron records. | 40 (Portland Public Schools) |
Target Symphony Environment (environment) |
Destination ILS database environment for testing CSV ingestion and overlay rules. Options: test, production. |
test |
Student CSV File (file) |
File upload input selecting a local CSV file containing student patron records matching district schema. | pps_students_20260804.csv |
3. District Client Configuration Form
Route: /clients/{client_id}/edit
Go to Districts →
Configures district-level metadata, contact information, overlay permissions, field protection policies, and regex validation rules.
| Field Name | Field Description | Example Entry |
|---|---|---|
District Contact Information (contact) |
Primary email address or department contact responsible for receiving district ingestion alerts and reports. | lib-admin@pps.net |
Field Overlay Allowed (field_{field_name}_overlay) |
Checkbox (checked / unchecked) enabling or disabling CSV data overlays for field {field_name}. |
Checkbox (checked) |
Policy (field_{field_name}_protect_existing) |
Policy governing per-field protection: Always Overwrite, Overlay if Empty, Never Overwrite, or Restrictive Overlay Pattern. | if_not_empty |
Overlay Pattern (Regex) (field_{field_name}_protect_pattern) |
Optional Python Regular Expression (Regex) pattern used specifically with the Restrictive Overlay Pattern policy to filter incoming updates. | .*@pps\.net$ |
Static Overlay Value (field_{field_name}_overlay_value) |
Optional constant default or override value automatically assigned to the field when updating Symphony (e.g. patron categories or profiles). | CONNECT |
Validation Rule (field_{field_name}_validate) |
Optional validation pattern or format expression used to validate CSV values prior to database ingestion. | s:14 (14-char barcode starting with 's') |
🛡️ Understanding Field Protection Policies
The Policy setting is configured individually for each data field in a district's schema. It determines under what conditions incoming CSV data is permitted to update an existing student record retrieved from Symphony via ILSWS:
| Policy Option | Policy Behavior | When to Use |
|---|---|---|
Always Overwrite (never) |
Always Overwrite: Ingested CSV data will always overwrite existing values in Symphony for this field. | Use for fields where the district student system is always the single source of truth (e.g., student grade level or home address). |
Overlay if Empty (if_not_empty) |
Overlay if Empty: The ingestion engine queries Symphony for the student's existing record. If the field in Symphony contains a non-blank, non-null value, it is protected and preserved. The incoming CSV value overlays Symphony only if the existing field in Symphony is currently empty, blank, or null. | Use for fields where student/patron updates made in the library system must be protected from being overwritten by automated district syncs (e.g., patron phone number or preferred email). |
Never Overwrite (always) |
Never Overwrite: Existing Symphony values are always protected and never replaced by incoming CSV data once populated. | Use when a field should be populated upon initial patron record creation, but never updated via CSV ingest afterwards. |
Restrictive Overlay Pattern (matching_pattern) |
Restrictive Overlay Pattern: Tests incoming CSV data against a Python Regular Expression (Regex) pattern specified in the field's Overlay Pattern column (e.g., .*@pps\.net$). Ingested CSV data will overlay Symphony ONLY IF the incoming CSV value matches the regex pattern. If incoming CSV data does not match, the overlay is rejected and the existing Symphony value is protected. |
Use for fields where you want to allow CSV overlays only for specific domain patterns (e.g. restricting email updates to official district email domains like .*@pps\.net$ while rejecting generic personal emails like user@gmail.com). |
📌 Validation Rule vs Overlay Pattern vs Static Values: The Validation Rule (e.g. checking email format syntax) acts as a mandatory gate applied to ALL incoming updates to ensure Symphony never receives invalid data. The Overlay Pattern requires a standard Python Regular Expression (Regex) used specifically with Restrictive Overlay Pattern policy to determine whether an update should occur. The Static Overlay Value defines constant codes (e.g. CONNECT, 1_MULT_Y, 0_MULT) automatically assigned or overridden during patron updates.
Python Regex Syntax Examples for Overlay Pattern:
.*@pps\.net$— Domain matching: matches any email address ending with@pps.net.^97[0-9]{3}$— Zip code matching: matches 5-digit Oregon zip codes starting with97.^[0-9]{3}-[0-9]{3}-[0-9]{4}$— Phone format: matches###-###-####phone numbers.
Ingestion Outcome Examples Matrix
| Policy | Existing Value in Symphony | Incoming CSV Value | Final Ingest Result |
|---|---|---|---|
| Overlay if Empty | "555-1234" (Populated) |
"555-9999" |
"555-1234" (Existing value protected & preserved) |
| Overlay if Empty | "" or null (Empty) |
"555-9999" |
"555-9999" (Empty field overlaid with CSV data) |
| Restrictive Overlay Pattern (Overlay Pattern: .*@pps\.net$) |
"student@multcolib.org" |
"student@pps.net" (Matches pattern) |
"student@pps.net" (Overlay allowed — incoming data matches pattern) |
| Restrictive Overlay Pattern (Overlay Pattern: .*@pps\.net$) |
"student@multcolib.org" |
"student@gmail.com" (Does NOT match) |
"student@multcolib.org" (Overlay rejected — existing value preserved) |
| Always Overwrite | "555-1234" (Populated) |
"555-9999" |
"555-9999" (Always overwritten) |
📋 Field Validation Rules Reference Table
Validation rules are configured in the Validation Rule column for each field. They act as a mandatory gate applied to ALL incoming updates before reaching Symphony to ensure data integrity.
| Rule Type | Code / Format Example | Validation Description |
|---|---|---|
| Blank / Empty | b |
Value must be blank or empty. |
| Date Format | d |
Value must be a valid calendar date conforming to ISO or standard formats (e.g. YYYY-MM-DD or MM/DD/YYYY). |
| Email Address | e |
Value must be a valid email address format (e.g. user@example.org). |
| Integer (Length or Range) | i:8 or i:1,9999999 |
Value must be an integer of exact digit length (e.g. i:8 for 8-digit IDs) or within an inclusive numeric range (e.g. i:1,9999999). |
| JSON String | j |
Value must be a valid JSON-formatted object or array string. |
| Number / Decimal Range | n:1,999 |
Value must be an integer or decimal number within the specified inclusive range (e.g. between 1 and 999). |
| Boolean | o |
Value must be a boolean flag (1, 0, true, or false). |
| Regex Pattern | r:/^[A-Z]{2,4}$/ |
Value must match the specified regular expression pattern. |
| String Length | s:14 |
Value must be a string up to 14 characters long (longer values are safely truncated). |
| URL Address | u |
Value must be a valid web URL starting with http:// or https://. |
| List Choice | v:one|two|three |
Value must match one of a pipe-delimited list of allowed values. |
| ZIP Code | z |
Value must be a valid US ZIP code (e.g. 97201 or 97201-1234). |
4. Create Staff User Account Form
Route: /users/create
Go to Form →
Creates a new library staff account in the MySQL database with assigned authorization role and credentials.
| Field Name | Field Description | Example Entry |
|---|---|---|
Username (username) |
Unique staff username assigned to the new user account. Must be unique across all system users. | mrogers |
Email Address (email) |
Official staff email address used for system identification and notifications. | mrogers@multcolib.org |
User Role (role) |
Access control role level: super_admin (full access), district_admin (configs & test loads), viewer (read-only). |
district_admin |
Password (password) |
Initial password string assigned to the user account. Hashed securely with Argon2id. Must satisfy complexity requirements: minimum 14 characters, including uppercase (A-Z), lowercase (a-z), and numerical digit (0-9). | •••••••••••••••• (Masked input) |
5. Edit Staff User Account Form
Route: /users/{user_id}/edit
Go to Users →
Updates an existing staff user account email address, system role, account status, or resets password credentials.
| Field Name | Field Description | Example Entry |
|---|---|---|
Email Address (email) |
Updated staff email address associated with the user account. | mrogers@multcolib.org |
User Role (role) |
Updated portal permission level: super_admin, district_admin, or viewer. |
super_admin |
Account Status (is_active) |
Dropdown toggle selecting account status: Active (enabled) or Inactive (disabled/blocked). |
Active |
Reset Password (password) |
Optional field to reset user password. Leave completely blank to keep existing password unchanged. If provided, must meet complexity rules: minimum 14 characters, including uppercase (A-Z), lowercase (a-z), and numerical digit (0-9). | •••••••••••••••• (Masked input or left blank) |
6. Delete Staff User Account Form
Route: /users/{user_id}/delete
Go to Users →
Deletes or deactivates a staff account from the database. Note: Users cannot delete their own active account.
| Field Name | Field Description | Example Entry |
|---|---|---|
Target User ID (user_id) |
Unique database primary key identifier of the user account selected for removal. | 4 |
7. Ingestion Audit Logs Search & Filter Form
Route: /audit-logs
Go to Audit Logs →
Filters and searches record-level patron ingestion event logs across Test and Production environments.
| Field Name | Field Description | Example Entry |
|---|---|---|
Barcode / Student ID (q) |
Text input to search for audit log entries by patron barcode or student identification number. | 20123456 |
District (district) |
Dropdown filter to restrict search results to a specific school district client. | 40 (Portland Public Schools) |
Action (action) |
Dropdown filter selecting ingestion outcome: OVERLAY, CREATE, SKIP_CHECKSUM, AMBIGUOUS, ERROR. |
OVERLAY |
Environment (environment) |
Selects target environment database to query: TEST or PRODUCTION. |
TEST |
Start Date (start_date) |
Date input (YYYY-MM-DD) setting the earliest timestamp bound for returned audit log entries. | 2026-08-01 |
End Date (end_date) |
Date input (YYYY-MM-DD) setting the latest timestamp bound for returned audit log entries. | 2026-08-04 |