Getting Started on psLens

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.

psLens for System Administrators

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

The Problem

You find out about problems when users call. A batch process failed overnight. Integration Broker messages have been stuck for hours. A long-running process is blocking the queue. By the time someone notices, the impact has already spread.

Checking manually means logging into PeopleSoft, navigating to Process Monitor or IB Monitor, setting filters, and scanning for issues. Multiply that by the number of environments you manage.

How psLens Changes This

Real-Time Alerts

psLens runs background checks every few minutes and surfaces problems on the dashboard as they happen.

psLens for Business Analysts

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

The Gap

You need to understand how something works in PeopleSoft. Maybe you are writing requirements for a customization. Maybe you are trying to understand why a process behaves a certain way. Maybe you need to know what data a page collects and where it goes.

But the tools for answering these questions — App Designer, SQL Developer, PeopleSoft’s technical pages — are built for developers. They require licenses, training, and technical knowledge that is outside your role. So you ask a developer. They look it up and get back to you later. Or you wait.

Dashboard

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

Dashboard

The dashboard is the home screen of psLens. It gives you a quick health overview of all your connected PeopleSoft databases, with a focus on anything that currently needs attention.

The psLens dashboard showing database connection status and active alerts

What You See on the Dashboard

Alert Summary

The top section of the dashboard shows active alerts grouped by database. Each alert card tells you:

Deployment Options

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

Deployment Options

This page is for clients who want to host psLens themselves in a Docker container. It covers three questions in order:

How do I get the image? Distribution and authentication.
How do I upgrade without losing my config? Volumes, env vars, and the master key.
How do I do HTTPS? Six TLS options compared on the same axes.

If you just want a 5-minute install on a private network, the Installation page is enough. Come back here when you’re ready to put psLens in front of real users.

Architecture Overview

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

Architecture Overview

psLens has only two moving parts:

The SWS framework, a small Integration Broker service installed inside your PeopleSoft environment.
The psLens application, a single Docker container hosted externally (default: fly.io) or on your own infrastructure.

Everything psLens displays (search results, alerts, reports) flows over a single HTTPS connection from the psLens container into your SWS endpoint. There is no other channel.

The Short Version

Two components, nothing else. SWS inside PeopleSoft; psLens as a Docker container outside it.
Traffic only flows one way. psLens calls SWS over HTTPS. SWS never reaches out to psLens.
One protocol. REST + HTTP basic auth + psoftQL JSON queries. No database drivers, no ODBC, no jump hosts.
One scope. SWS only answers queries against PeopleTools metadata tables that you whitelist. Anything outside the list is rejected before it touches the database.
Dedicated deployment per customer. No shared psLens app, no shared storage, no multi-tenant SaaS backend.

How the Pieces Fit

%%{init: {"flowchart": {"htmlLabels": true, "padding": 16, "nodeSpacing": 60, "rankSpacing": 80, "subGraphTitleMargin": {"top": 10, "bottom": 14}}}}%%
flowchart LR
 USER(["Your team's<br/>web browser"])
 subgraph EXT["Cedar Hills Group hosted or your own infrastructure"]
 APP["psLens<br/>Docker container"]
 end
 subgraph PS["Your PeopleSoft Environment"]
 SWS["SWS Framework<br/>REST endpoint"]
 DB[("PeopleSoft DB<br/>read-only<br/>whitelisted tables")]
 SWS --> DB
 end
 USER -- "HTTPS" --> APP
 APP -- "HTTPS · Basic auth<br/>psoftQL JSON" --> SWS

 classDef ps fill:#e8f4fd,stroke:#0d6efd,stroke-width:2px,color:#000
 classDef ext fill:#fff5e6,stroke:#fd7e14,stroke-width:2px,color:#000
 classDef user fill:#e9f7ef,stroke:#198754,stroke-width:2px,color:#000
 classDef subgraphStyle fill:#fafafa,stroke:#666,stroke-width:1px,color:#000
 class SWS,DB ps
 class APP ext
 class USER user
 class PS,EXT subgraphStyle

Your team reaches psLens with any current web browser over HTTPS. There is no desktop client to install. Everything the user sees comes from the psLens container; the browser never talks to PeopleSoft directly.

Getting Started 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

psLens for System Administrators

The Problem

How psLens Changes This

Real-Time Alerts

psLens for Business Analysts

The Gap

Dashboard

Dashboard

What You See on the Dashboard

Alert Summary

Deployment Options

Deployment Options

Architecture Overview

Architecture Overview

The Short Version

How the Pieces Fit

YAML Configuration Example (`config.yaml`)

JSON Configuration Example (`config.json`)