Remote Poster

Posts notices to a Polaris ILS database via the Polaris Leap (PAPI) API.

Setup

1. (Recommended) create and activate a virtual environment, then install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

   On macOS with Homebrew Python you may get an "externally managed environment" error if you skip the venv and pip install directly — the venv avoids that.

2. Copy .env.example to .env and fill in your server, org/workstation IDs, and staff login. .env is gitignored, so real credentials never get committed.

   • POLARIS_USERNAME must include the domain, e.g. MYLIB\Aladdin.
   • POLARIS_ORGANIZATION_ID should match the OrganizationID your staff login actually belongs to (visible in the PolarisUser object returned on successful auth) — it's your logged-on org context, not the list of orgs you're posting notices to.
   • POLARIS_PRODUCT_ID defaults to 7 (Notices). If calls fail, 19 (PolarisApplicationServices) is the confirmed working alternative — see Notes below.

Usage

python post_notices.py --notice-type 2 --org-ids 3,4,5,6,7,8

• --notice-type: the Notification Type ID to post (from your Polaris system tables).
• --org-ids: comma-separated Organization IDs to post notices for (the branches whose notices go out) — separate from POLARIS_ORGANIZATION_ID in .env, which is your login context.
• --delivery-option: optional, defaults to 1 (Mail) — currently the only value Polaris accepts.

On success it prints a confirmation. On failure (bad credentials, invalid IDs, etc.) it prints the error from Polaris and exits non-zero.

Every run sends real notices to real patrons — there's no dry-run mode. Double-check --notice-type and --org-ids before running.

Notes on the API (things the published docs get wrong or omit)

While wiring this up against Osceola's live server, two things in the reference doc (docs/polaris-papi-reference.md) turned out to be incomplete or misleading:

1. The staff authentication URL is shorter than every other endpoint's. Most PAPI routes follow /api/{version}/{language}/{productId}/{siteDomain}/{organizationId}/{workstationId}/..., but authentication/staffuser only uses /api/{version}/{language}/{productId}/authentication/staffuser — no siteDomain, organizationId, or workstationId. This makes sense in hindsight (those three describe a logged-on session, and you're not logged on yet when authenticating), but it isn't spelled out anywhere in the rendered help page — it's only visible as a title="..." tooltip attribute in the raw HTML of polaris.applicationservices/help/authentication/post_staffuser, which a normal page read (rendered text, or an AI summary of the page) won't surface. polaris_client.py builds this URL separately from every other call (self.auth_url vs self.base_url).
2. productId: 19 (PolarisApplicationServices) is confirmed working against the live server; 7 (Notices) was the doc's best guess but untested — worth trying if 19 ever stops working, but don't be surprised if it 400s/404s.

If you hit a 404 with an empty response body on any call, that almost always means the URL path itself doesn't match a route (wrong segment count, wrong product ID, etc.) rather than a credentials problem — Polaris's own application-level errors come back as JSON with a Message/ErrorCode, not an empty body.