Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation

psLens has two parts to install: the SWS framework in your PeopleSoft environment, and the psLens application on a server.

Hosting psLens yourself in production? This page walks through the basic “Docker on one host” install. For client-hosted deployments that need HTTPS, version pinning, backups, and a clear upgrade story, read Deployment Options after this page.

Step 1: Install the SWS Framework in PeopleSoft

psLens reads data from PeopleSoft through the SWS (Secure Web Services) framework, developed by Cedar Hills Group. SWS exposes a REST API; psLens calls it instead of talking to the database directly.

Whitelist Tables

Mon, 01 Jan 0001 00:00:00 +0000

Whitelist Tables

SWS controls which PeopleSoft tables can be queried through a whitelist. You need to whitelist every table that psLens reads. The full list of tables (organized by feature area) is documented in the Reference section.

This page contains the SQL inserts you run once during installation. After running them, restart psLens (or wait for the next whitelist cache refresh) and confirm the Settings > Database Connections page shows the database as fully connected with no missing-table warnings.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration

psLens reads a config.yaml file from the same directory as the binary. There is no database to set up; persistent data (report results, alert state) is stored in an embedded NATS data store.

Full Configuration Examples

psLens supports configuration in either YAML (config.yaml) or JSON (config.json) format. The application detects the format automatically on boot.

YAML Configuration Example (`config.yaml`)

# Schema validation pointer (optional, for IDE support)
# yaml-language-server: $schema=http://localhost:8080/static/config-schema.json

server:
 port: 8080
 host: "0.0.0.0"
 natsStoreDir: "./data/nats"
 projectStoreDir: "./data/projects"
 dmsStoreDir: "./data/dms"
 appBaseURL: "http://localhost:8080"
 recentlyViewed:
 maxItems: 20

databases:
 - name: "PROD"
 description: "Production PeopleSoft HR"
 baseURL: "https://psft.example.com:8000/PSIGW/RESTListeningConnector/PSFT_HR/CHG_SWS_PSOFTQL/"
 username: "PSLENS_API"
 password: "your-api-password"
 piaURL: "https://psft.example.com/psp/ps/"
 timezone: "America/Chicago"
 production: true
 alerts:
 enabled: true
 intervalMinutes: 10

 - name: "DEV"
 description: "Development Environment"
 baseURL: "https://psftdev.example.com:8000/PSIGW/RESTListeningConnector/PSFT_HR/CHG_SWS_PSOFTQL/"
 username: "PSLENS_API"
 password: "dev-api-password"
 timezone: "America/Chicago"
 production: false

alerts:
 enabled: true
 intervalMinutes: 5
 checks:
 long_running_processes:
 enabled: true
 thresholdMinutes: 20
 process_errors:
 enabled: true
 lookbackHours: 24
 ib_operation_errors:
 enabled: true
 lookbackHours: 24
 ib_pub_contract_errors:
 enabled: true
 lookbackHours: 24
 ib_sub_contract_errors:
 enabled: true
 lookbackHours: 24
 ib_operation_stalled:
 enabled: true
 thresholdMinutes: 30
 ib_pub_contract_stalled:
 enabled: true
 thresholdMinutes: 30
 ib_sub_contract_stalled:
 enabled: true
 thresholdMinutes: 30
 genericSWSAlerts:
 - id: "stale_users"
 name: "Stale User Accounts"
 enabled: true
 severity: "warning"
 alertOn: "row_found"
 message: "Warning: Stale user accounts detected"
 query:
 records:
 - recordName: "PSOPRDEFN"
 sqlWhereClause: "LASTUPDDTTM < CAST('2026-01-01' AS TIMESTAMP) AND ACCTLOCK = 0"
 rowLimit: 5

auth:
 enabled: true
 authorizedUsers:
 - "admin@example.com"
 - "auditor@example.com"

smtp:
 host: "smtp.mailtrap.io"
 port: "2525"
 username: "smtp-user"
 password: "smtp-password"
 fromName: "psLens Alerts"
 fromEmail: "alerts@pslens.example.com"

notifications:
 subscriptions:
 - id: "team-email"
 enabled: true
 alertTypes: ["*"]
 databases: ["PROD"]
 severityMin: "warning"
 type: "email"
 target: "psoft-alerts@example.com"
 - id: "slack-webhook"
 enabled: true
 alertTypes: ["process_errors", "ib_operation_errors"]
 databases: ["*"]
 type: "webhook"
 target: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
 - id: "teams-webhook"
 enabled: true
 alertTypes: ["*"]
 databases: ["*"]
 type: "webhook"
 target: "https://example.webhook.office.com/webhookb2/..."

JSON Configuration Example (`config.json`)

{
 "$schema": "http://localhost:8080/static/config-schema.json",
 "server": {
 "port": 8080,
 "host": "0.0.0.0",
 "natsStoreDir": "./data/nats",
 "projectStoreDir": "./data/projects",
 "dmsStoreDir": "./data/dms",
 "appBaseURL": "http://localhost:8080",
 "recentlyViewed": {
 "maxItems": 20
 }
 },
 "databases": [
 {
 "name": "PROD",
 "description": "Production PeopleSoft HR",
 "baseURL": "https://psft.example.com:8000/PSIGW/RESTListeningConnector/PSFT_HR/CHG_SWS_PSOFTQL/",
 "username": "PSLENS_API",
 "password": "your-api-password",
 "piaURL": "https://psft.example.com/psp/ps/",
 "timezone": "America/Chicago",
 "production": true,
 "alerts": {
 "enabled": true,
 "intervalMinutes": 10
 }
 },
 {
 "name": "DEV",
 "description": "Development Environment",
 "baseURL": "https://psftdev.example.com:8000/PSIGW/RESTListeningConnector/PSFT_HR/CHG_SWS_PSOFTQL/",
 "username": "PSLENS_API",
 "password": "dev-api-password",
 "timezone": "America/Chicago",
 "production": false
 }
 ],
 "alerts": {
 "enabled": true,
 "intervalMinutes": 5,
 "checks": {
 "long_running_processes": {
 "enabled": true,
 "thresholdMinutes": 20
 },
 "process_errors": {
 "enabled": true,
 "lookbackHours": 24
 },
 "ib_operation_errors": {
 "enabled": true,
 "lookbackHours": 24
 },
 "ib_pub_contract_errors": {
 "enabled": true,
 "lookbackHours": 24
 },
 "ib_sub_contract_errors": {
 "enabled": true,
 "lookbackHours": 24
 },
 "ib_operation_stalled": {
 "enabled": true,
 "thresholdMinutes": 30
 },
 "ib_pub_contract_stalled": {
 "enabled": true,
 "thresholdMinutes": 30
 },
 "ib_sub_contract_stalled": {
 "enabled": true,
 "thresholdMinutes": 30
 }
 },
 "genericSWSAlerts": [
 {
 "id": "stale_users",
 "name": "Stale User Accounts",
 "enabled": true,
 "severity": "warning",
 "alertOn": "row_found",
 "message": "Warning: Stale user accounts detected",
 "query": {
 "records": [
 {
 "recordName": "PSOPRDEFN",
 "sqlWhereClause": "LASTUPDDTTM < CAST('2026-01-01' AS TIMESTAMP) and ACCTLOCK = 0"
 }
 ],
 "rowLimit": 5
 }
 }
 ]
 },
 "auth": {
 "enabled": true,
 "authorizedUsers": [
 "admin@example.com",
 "auditor@example.com"
 ]
 },
 "smtp": {
 "host": "smtp.mailtrap.io",
 "port": "2525",
 "username": "smtp-user",
 "password": "smtp-password",
 "fromName": "psLens Alerts",
 "fromEmail": "alerts@pslens.example.com"
 },
 "notifications": {
 "subscriptions": [
 {
 "id": "team-email",
 "enabled": true,
 "alertTypes": ["*"],
 "databases": ["PROD"],
 "severityMin": "warning",
 "type": "email",
 "target": "psoft-alerts@example.com"
 },
 {
 "id": "slack-webhook",
 "enabled": true,
 "alertTypes": ["process_errors", "ib_operation_errors"],
 "databases": ["*"],
 "type": "webhook",
 "target": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
 },
 {
 "id": "teams-webhook",
 "enabled": true,
 "alertTypes": ["*"],
 "databases": ["*"],
 "type": "webhook",
 "target": "https://example.webhook.office.com/webhookb2/..."
 }
 ]
 }
}

Server Settings

The server section controls how psLens listens for incoming connections and where it stores data.

Generic SWS Alerts

Mon, 01 Jan 0001 00:00:00 +0000

Generic SWS Alerts

Generic SWS Alerts let you define alert checks in YAML using PsoftQL queries against whitelisted PeopleSoft records. Use these when you need a one-off check that the built-in alert types don’t cover.

The scheduler runs each query on the database’s checking interval and triggers alerts based on the resulting row counts.

Configuration Properties

Generic alerts are configured under the genericSWSAlerts list, either globally under alerts or overridden per-database under databases[].alerts.

Configuration on psLens

Installation

Installation

Step 1: Install the SWS Framework in PeopleSoft

Whitelist Tables

Whitelist Tables

Configuration

Configuration

Full Configuration Examples

YAML Configuration Example (config.yaml)

JSON Configuration Example (config.json)

Server Settings

Generic SWS Alerts

Generic SWS Alerts

Configuration Properties

YAML Configuration Example (`config.yaml`)

JSON Configuration Example (`config.json`)