OA Compass Admin

Alma Cloud App for OpenAthens provisioning, with a Node.js proxy for OA API calls.

Quick Start (Local)

Prerequisites

• Node.js 18+
• npm
• Alma Sandbox access (Cloud App Console)

1) Install dependencies

npm ci

2) Run the Cloud App frontend

npm start

This runs eca start and serves the app locally for Alma Cloud App Console loading.

3) Run the local OA proxy (second terminal)

From repo root, set env vars then start proxy:

$env:PORT="8081"
$env:ALLOWED_ORIGINS="https://sandbox-na.alma.exlibrisgroup.com,https://na02.alma.exlibrisgroup.com"
$env:OA_BASE_URL="https://admin.openathens.net/api"
$env:OA_TENANT="<your-tenant>"
$env:OA_API_KEY="<your-api-key>"
$env:OA_CREATE_URL="https://admin.openathens.net/api/v1/<instance>/organisation/<org_id>/accounts/create/personal?sendEmail=true&defaultPermissions=false"

node .\cloudapp\src\server\server.js

Health check:

Invoke-RestMethod http://127.0.0.1:8081/health

Load in Alma Sandbox

1. Open Alma Sandbox.
2. Open Cloud App Console.
3. Load from your local app URL shown by eca start.
4. Open app Configuration and set proxyBaseUrl.

Important Local Proxy Note

OAProxyService accepts only https:// for configured proxyBaseUrl values. A plain http://localhost:8081 config value is ignored.

Options:

• Use your deployed HTTPS proxy URL for normal testing, or
• Expose local 127.0.0.1:8081 through an HTTPS tunnel and use that tunnel URL.

Build

eca build

Build output is generated under build/.

Project Structure

• cloudapp/src/app - Angular Cloud App frontend
• cloudapp/src/server - Node.js OA proxy
• docs/design - Canonical project docs (PB, SDD, CCR, PP)
• docs/legacy - Archived previous root-era docs

Canonical Docs

• Project Brief (PB)
• System Design Document (SDD)
• Canonical Code Registry (CCR)
• Project Plan (PP)