Getting Started

• 1: Architecture Overview
• 2: Installation
• 3: Whitelist Tables
• 4: Configuration
• 5: Deployment Options
• 6: IP & CIDR Allowlist
• 7: SSO & OIDC Discovery

Getting Started with psLens

Install SWS in PeopleSoft, run the psLens container, point it at SWS, log in. The pages in order:

Overview

psLens is a single self-contained application: a Go binary that serves the web interface and stores report data locally. There is no separate database to manage. It connects to your PeopleSoft environment through the SWS (Secure Web Services) framework, which must be installed and configured in PeopleSoft first.

Hosting psLens in production? Read Deployment Options for HTTPS, version pinning, backups, and upgrade paths.

Setup Steps

1. Read the Architecture Overview to see how the pieces fit together
2. Install the SWS Framework in your PeopleSoft environment
3. Install psLens on your server
4. Configure psLens with your database connection details
5. Start psLens and open the dashboard in your browser

Quick Start

Once the SWS framework is installed in PeopleSoft:

# Create a directory for psLens
mkdir pslens && cd pslens

# Create config.yaml with your PeopleSoft connection details
# (see Configuration for full details)

# Start psLens with Docker
docker compose up -d

# Open http://localhost:8080 in your browser

Not Ready to Install Yet?

If you are still evaluating architecture, security, or operator workflow, see it running first. A live demo is the quickest way to answer fit questions before you commit to an install path.

Book a Demo Security & Trust

1 - Architecture Overview

Architecture Overview

psLens has only two moving parts:

1. The SWS framework, a small Integration Broker service installed inside your PeopleSoft environment.
2. 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 <br/>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.

Inside Your PeopleSoft Environment: SWS

The SWS framework is a small Integration Broker service Cedar Hills Group provides. Your PeopleSoft team installs it once, alongside everything else PeopleSoft already runs. It exposes a single REST endpoint that accepts a structured query language called psoftQL and returns JSON.

What SWS gives you control over:

• The whitelist. Your PeopleSoft admins decide which PeopleTools metadata tables SWS is allowed to read. psLens cannot ask for anything off the list.
• The credentials. SWS authenticates incoming requests with HTTP basic auth. Your team owns the token; rotating it is a config change on both ends.
• The audit trail. Calls land on your Integration Broker like any other inbound service, visible in the tooling your team already monitors.

No PeopleSoft database username or password is ever shared with psLens.

Outside Your Environment: psLens Container

psLens itself is a single Docker container: one Go binary, with embedded NATS for storing alert history and report output. That’s the entire runtime.

• Default deployment is on fly.io as a managed instance dedicated to your organization.
• Self-hosting is fully supported. Docker, docker-compose, bare-metal, and air-gapped environments are all covered in the installation guide.
• Stateless toward PeopleSoft. psLens does not copy your business data. The only things it persists are alert history and report output, both inside its own dedicated storage. See the Security & Trust page for details on what is and isn’t stored.

When you upgrade psLens, you pull a new container image. Nothing inside PeopleSoft changes.

Server-Driven Hypermedia Architecture (Zero Client-Side Storage)

psLens renders pages on the server with Go templates and streams updates over Server-Sent Events using Datastar. There is no React, no Angular, no JSON API. The browser receives HTML fragments over SSE (TLS at the transport layer) and renders them.

Two consequences fall out of this:

• Nothing from PeopleSoft is stored in the browser. psLens does not write to LocalStorage, SessionStorage, or IndexedDB. Closing the tab takes the active session data with it.
• No JSON wire format. The server sends pre-rendered HTML; there is no client-side data structure for an attacker to scrape or tamper with. Page transitions are server round-trips of a few KB of HTML, and the browser tab holds no result set.

Why This Shape

• Bounded blast radius. Even in a worst case where the psLens container were compromised, the SWS whitelist is the ceiling on what an attacker could read. They cannot drop into PeopleSoft, run PeopleCode, or pivot to other tables.
• Easy to upgrade and operate. New psLens features ship as a new container image. No PeopleSoft change request, no App Designer migration, no downtime on the PeopleSoft side.
• Multi-environment from day one. A single psLens deployment can connect to DEV, TEST, and PROD at the same time. Point at the SWS endpoint in each environment via separate database entries in config.yaml.

Where Next

• Installation installs SWS in PeopleSoft and runs the psLens container.
• Configuration wires psLens to your PeopleSoft environments.
• Security & Trust covers the read-only design, dedicated deployment, and what psLens does and doesn’t store.

2 - Installation

The psLens web application connects to your PeopleSoft environments with a limited version of our SWS framework.

You will install a PeopleSoft Application Designer project (CHG_PSLENS) with two web services that expose a REST API for reading data from PeopleSoft tables. psLens calls the web services instead of talking to the database directly. Most of the work is performed by the CHG_PSLENS_SWSPQL service operation. There is a secondary service operation, CHG_PSLENS_METADATA_GET, that returns miscellaneous metadata about the PeopleSoft environment that cannot be read from the database tables and relies on proprietary PeopleCode functions.

We do NOT deliver the full SWS framework to customers for psLens. The full SWS framework is a commercial product that includes a query language, a web service framework, and a set of tools for building and managing REST APIs on top of PeopleSoft. psLens uses a small subset of the SWS framework to read data from PeopleSoft tables.

This installation guide assumes that Cedar Hills Group, Inc. is hosting the psLens web application. If you are hosting psLens yourself, please see Deployment Options for instructions on how to install and configure psLens in your own environment. The option where we host psLens is the simplest and fastest way to get started, and is the recommended option for most customers.

%%{init: {"flowchart": {"htmlLabels": true, "padding": 16, "nodeSpacing": 60, "rankSpacing": 80, "subGraphTitleMargin": {"top": 10, "bottom": 14}}}}%%

flowchart LR

  subgraph EXT["Cedar Hills Group hosted <br/>or your own infrastructure"]
    psLens[psLens Web Application]
  end
  subgraph PS["Your PeopleSoft Infrastructure"]
    IB.DEV["DEV Integration Broker"]
    DB.DEV[("DEV PeopleSoft DB<br/>read-only<br/>whitelisted tables")]
    IB.DEV --> DB.DEV
    IB.TST["TST Integration Broker"]
    DB.TST[("TST PeopleSoft DB<br/>read-only<br/>whitelisted tables")]
    IB.TST --> DB.TST
    IB.PROD["PROD Integration Broker"]
    DB.PROD[("PROD PeopleSoft DB<br/>read-only<br/>whitelisted tables")]
    IB.PROD --> DB.PROD
end

  psLens -->|SWS https| IB.DEV
  psLens -->|SWS https| IB.TST
  psLens -->|SWS https| IB.PROD

The high-level installation steps are:

• You will be given a zip file containing the CHG_PSLENS Application Designer project.
• Import the project into your PeopleSoft DEV environment. Detailed instructions are included below.
• Run the “whitelist” inserts to allow psLens to read the tables it needs. Detailed instructions are included below.
• Configure the required service account for psLens API access and grant it the required permissions to read the tables psLens uses. Detailed instructions are included below.
• Ensure that your instance of psLens can reach the PeopleSoft Integration Gateway. This often requires a firewall rule to allow the psLens server to reach the PeopleSoft Integration Gateway on port 443 (or your configured port).
• Work with Cedar Hills Group to configure the psLens web application to connect to your PeopleSoft environments.

PeopleSoft Project Installation

You will repeat these steps for each PeopleSoft environment you want to connect to psLens (DEV, TST, PROD). We recommend starting with DEV first, then TST, then PROD. The steps are the same for each environment. You can follow your standard change management process for importing the project into TST and PROD.

• You will be given a zip file containing the CHG_PSLENS Application Designer project.
• Using Application Designer, import the project into your PeopleSoft environment.
• After importing the project, you need to build the CHG_PSLENS_WL table.
  • This holds the list of whitelisted tables that psLens can read. You will run the whitelist inserts to populate this table.

• Compile all the project PeopleCode to ensure that the project was fully imported. There should be no errors. If there are errors, please contact Cedar Hills Group for assistance or try to re-import the project.

Whitelist Inserts

You will need to run the whitelist inserts to allow psLens to read the tables it needs. Please see the Whitelist Tables page for the full list of inserts. You will need to run these inserts in each PeopleSoft environment you want to connect to psLens (DEV, TST, PROD).

PeopleSoft Service Account

psLens uses a dedicated PeopleSoft operator ID (OPRID) for API access. This is the account that psLens uses to authenticate to the SWS framework.

The naming convention for the account is CHG_PSLENS_API_USER. You can use a different name if you prefer, but you will need to update the psLens configuration to match.

• Create OPRID: CHG_PSLENS_API_USER
  • Add a complex password that meets your security requirements. This password will be used in the psLens configuration. Use a password manager to generate a strong password.
• Grant the following permissions to the account:
  • ID Type: NONE
  • Role: CHG_PSLENS_API_USER
    • Permission List: CHG_PSLENS_API_USER

The account should NOT have any other permissions or roles. It should only have the permissions required to read the whitelisted tables. If you have any sort of dynamic security roles, make sure that they do not grant any additional permissions to this account. The account should be as limited as possible. The permission list that we deliver in the project is the entire set of permissions that psLens needs to read the whitelisted tables. If you have any questions about the permissions, please contact Cedar Hills Group.

psLens to PeopleSoft Connectivity

We will cover the most common configuration where Cedar Hills Group, Inc. hosts the psLens web application and you have a network team that can allow the psLens server to reach the PeopleSoft Integration Gateway.

The default configuration for psLens is to connect to the PeopleSoft Integration Gateway over HTTPS from the internet. The psLens server must be able to reach the PeopleSoft Integration Gateway on port 443 (or your configured port). This often requires a firewall rule to allow the psLens server to reach the PeopleSoft Integration Gateway. The hostname of your PeopleSoft Integration Gateway must be resolvable from the psLens server. This is often an entry in your public DNS. Most organizations do NOT expose the PeopleSoft Integration Gateway to the public internet.

If your organization exposes the PeopleSoft Integration Gateway to the public internet, you likely will not need to make any changes to your firewall.

The psLens server will be identified by a custom egress IP address that Cedar Hills Group, Inc. will configure for your instance of psLens. You will need to work with your network team to allow this IP address to reach the PeopleSoft Integration Gateway on port 443 (or your configured port). If you have any questions about the connectivity, please contact Cedar Hills Group.

%%{init: {"flowchart": {"htmlLabels": true, "padding": 16, "nodeSpacing": 60, "rankSpacing": 80, "subGraphTitleMargin": {"top": 10, "bottom": 14}}}}%%

flowchart LR
  psLens[psLens Web Application]
  subgraph PS["Your Infrastructure"]
    DNS["External DNS"]
    FW["Firewall / Network Team"]

    IB.DEV["DEV Integration Broker"]
    DB.DEV[("DEV PeopleSoft DB<br/>read-only<br/>whitelisted tables")]
    IB.DEV --> DB.DEV
    FW --> IB.DEV
  end

  psLens -->|SWS https| FW
  psLens -->|DNS lookup| DNS

Curl Testing

PeopleSoft administrators often want to smoke test the connectivity between psLens and the PeopleSoft Integration Gateway before we configure the psLens web application. The following curl command can be used to test the connectivity. You will need to replace the placeholders with your actual values.

• PS_LENS_API_USER - The PeopleSoft operator ID that psLens uses to authenticate to the SWS framework. This is the account that you created in the previous step. The default value is CHG_PSLENS_API_USER.
• PS_LENS_API_PASSWORD - The password for the PeopleSoft operator ID that psLens uses to authenticate to the SWS framework. This is the password that you set when you created the account.
• PS_HOST - The hostname of your PeopleSoft Integration Gateway. This is the hostname that psLens will use to connect to the PeopleSoft Integration Gateway. This must be resolvable from the psLens server.
• PS_PORT - The port your Integration Gateway listens on. 8000 is the PeopleSoft default for HTTP; HTTPS is frequently on 8443.
• PS_NODE - The name of the PeopleSoft node that fronts the REST listening connector. The default value is PSFT_CS; use the node that matches your environment.

PS_LENS_API_USER='CHG_PSLENS_API_USER'
PS_LENS_API_PASSWORD='your-password-here'
PS_HOST='psft.example.com'
PS_PORT='8000'
PS_NODE='PSFT_CS'

curl --request POST \
  --url "https://${PS_HOST}:${PS_PORT}/PSIGW/RESTListeningConnector/${PS_NODE}/CHG_PSLENS_SWSPQL/" \
  -u "${PS_LENS_API_USER}:${PS_LENS_API_PASSWORD}" \
  --header 'Content-Type: application/json' \
  --data '{
  "isDebugMode": false,
  "includeFieldTypes": true,
  "includeAllDescriptions": true,
  "includeKeyFieldIndicators": true,
  "includeAllFieldLabels": true,
  "records": [
    {
      "recordName": "CHG_PSLENS_WL",
      "includeDescriptionsFor": [],
      "excludeFields": []
    }
  ]
}'

Keep the single quotes on the variable assignments. PeopleSoft passwords often contain !, $, or a space, and an unquoted value gets mangled by the shell before curl ever sees it. In bash and zsh, an unquoted ! triggers history expansion, the assignment fails with event not found, and curl then authenticates with an empty password.

A successful call returns HTTP 200 with a data.CHG_PSLENS_WL.fields array listing the whitelisted RECNAME values. Two common failures:

• 401 - the operator ID or password is wrong, or the account is locked.
• 404 - the node name or service operation path is wrong. Check PS_NODE against the node you created and confirm the CHG_PSLENS_SWSPQL service operation is active.

3 - Whitelist Tables

Whitelist Tables

psLens controls which PeopleSoft tables can be queried through a global whitelist table (CHG_PSLENS_WL). 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.

PeopleTools Tables Common to All Features

Run all of the inserts below. Each block matches a category in the Reference page. If you add new functionality to psLens that queries a new record, add it here too.

-- Whitelist record itself (optional: CHG_PSLENS_WL is always readable by the framework)
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('CHG_PSLENS_WL');

-- Security tables
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAUTHAS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAUTHBUSCOMP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAUTHITEM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAUTHPRCS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAUTHSIGNON');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAUTHWS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSCLASSDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMENUITEM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOBJGROUP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPRDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPROBJ');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSROLECLASS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSROLEDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSROLEUSER');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_ACC_GRP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_QUERY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PTACM_ACCESSTBL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPTSCRTY_ADS_A');

-- Metadata tables
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSBCDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSBCITEM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSDBFIELD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSDBFLDLABL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSKEYDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMENUDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSXFERITEM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPNLDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPNLFIELD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPNLGROUP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPNLGRPDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPROJECTDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPROJECTITEM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPRSMATTRVAL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPRSMDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPRSMPERM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPRSMSYSATTR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPRSMSYSATTRVL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSRECDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSRECFIELD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPTSF_SD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPTSF_SD_ATTR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPTSF_SD_DCATR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPTSF_SRCCAT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPTSF_SRCCATAT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSRECDDLPARM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIDXDDLPARM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSSPCDDLPARM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSDDLMODEL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSDDLDEFPARMS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPTIONSADDL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSTBLSPCCAT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSRECTBLSPC');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSFLDDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSFLDSEGDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSFLDFIELDDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSXLATITEM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SQLSTMT_TBL');

-- Integration Broker tables
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAPMSGPUBCON');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAPMSGPUBHDR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAPMSGSUBCON');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAPMSGDOMSTAT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAPMSGDSPSTAT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBLOGHDR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBRTNGDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBAPPLDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBAPPLOPR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBAPPURI');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBAPPMETHOD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBPARAM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBBASEPARAM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBTEMPLPARAM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBBASETMPLPRM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBAPPLSTATES');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSIBAPPLHDRPROP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGNODEDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSNODECONPROP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSNODEURITEXT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSNODESDOWN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPERATION');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPERATIONAC');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPERATIONURI');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPRHDLR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPRVERDFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPRVERDFNPARM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQUEUEDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQUEUEPART');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSRTNGDFNPARM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSRTNGDFNPROP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSSERVICE');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSSERVICEOPR');

-- Process Scheduler tables
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSDEFNGRP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSDEFNPNL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSJOBDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSJOBGRP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSJOBITEM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSJOBPNL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSJOBMESSAGE');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSMUTUALEXCL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSRECUR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSRECURDATE');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSRECUREXEMPT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPRCSRQST');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSDEFNNOTIFY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSDEFNCNTDIST');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSJOBNOTIFY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PRCSJOBCNTDIST');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SERVERDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSSERVERSTAT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SERVERCATEGORY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SERVERCLASS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SERVERNOTIFY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SERVEROPRTN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('DAEMONGROUP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('DAEMONGROUP_VW');

-- Developer tables
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAEAPPLDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAEAPPLSTATE');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAEAPPLTEMPTBL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAESECTDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAESTEPDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSAESTMTDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSCONTDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSCONTENT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGATTR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGCATDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGFLDOVR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGPARTS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGREC');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGSETDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSMSGVER');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPACKAGEDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPCMNAME');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPCMPROG');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPCMTXT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYFIELD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYRECORD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYSTATS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYEXECLOG');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYSELECT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYCRITERIA');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYEXPR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSQRYBIND');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSSQLDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSSQLTEXTDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSTREEDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSTREENODE');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSURLDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PT_URL_PROPS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSXPRPTDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSXPDATASRC');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSXPTMPLDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSXPTMPLFILEDEF');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSXPRPTVIEWER');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSCHGCTLDEF');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSCHGCTLLOCK');

-- Audit & user profile tables
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPTLOGINAUDIT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSPRUFDEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSUSEREMAIL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPRALIAS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('PSOPTIONS');

Campus Solutions Specific Tables

Only run these in a Campus Solutions database. If you run them in a non-CS database, you will get errors about missing tables.

-- Campus Solutions row-level security tables
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('ES_SECURITY_DTL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('ES_SECURITY_TBL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('OPER_ROLE_DEFN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('OPR_DEFAULT_TBL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('OPR_DEF_TBL_CS');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('OPR_GRP_3C_TBL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('RUNCNT_USERPROF');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('RUN_CNTL_HR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('RUN_CNTL_SECVWU');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SAA_SCRTY_AARPT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SAD_TEST_SCTY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCCPU_SRTY_TBL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCC_GE_SCRTY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCC_NTF_OPR_CON');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCC_SCRTY_RLCAT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCC_SCRT_RUNCTL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCC_SL_TRN_SCTY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCC_STY_TBL_CMP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCC_VLTCNV_RCTL');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_ADM_ACTN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_APPL_CTR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_PROG_ACTN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_RECR_CTR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_ACAD');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_CAR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_INST');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_MLSTN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_PLAN');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_PROG');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_SRVC');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TBL_STGP');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SCRTY_TSCRPT');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SEV_PRG_SP_SCTY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SEV_SCHLCD_SCTY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SSR_AIR_OPRSCTY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SSR_ANID_SCRTY');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SSR_APT_ACT_SCR');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SSR_SCRTY_EXAM');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SSR_SCRTY_GRSTA');
INSERT INTO PS_CHG_PSLENS_WL (RECNAME) VALUES ('SSR_SCRTY_TSRPT');

4 - Configuration

Configuration

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

Configuration Synchronization

Active configuration is synchronized automatically between config.yaml and the embedded NATS KV store:

• Bare-Minimum Boot: The server can boot with zero configured database connections. Database connections can be added later directly through the Settings UI at /settings.
• Disk Edit Recognition: On boot, if config.yaml has been modified on disk more recently than the active NATS KV store snapshot, psLens automatically syncs the file changes into NATS KV.
• UI Auto Write-Back: Changes made via the Settings UI update NATS KV and automatically write back to config.yaml on disk.

Password & Secret Security Options

psLens provides three secure methods for passing database and server credentials:

1. 1Password Secret References (op://...): Pass 1Password Secret URIs directly in config.yaml or JSON configurations:

   databases:
     - name: "PROD"
       username: "PSLENS_API"
       password: "op://Employee-Vault/PeopleSoft-Prod-API/password"
   
   smtp:
     host: "op://Employee-Vault/SMTP-Mailtrap/host"
     port: "op://Employee-Vault/SMTP-Mailtrap/port"
     username: "op://Employee-Vault/SMTP-Mailtrap/username"
     password: "op://Employee-Vault/SMTP-Mailtrap/password"
     fromName: "op://Employee-Vault/SMTP-Mailtrap/from_name"
     fromEmail: "op://Employee-Vault/SMTP-Mailtrap/from_email"
   
   auth:
     oidc:
       issuerUrl: "op://Employee-Vault/OIDC-Okta/issuer_url"
       clientId: "op://Employee-Vault/OIDC-Okta/client_id"
       clientSecret: "op://Employee-Vault/OIDC-Okta/client_secret"
       redirectUrl: "op://Employee-Vault/OIDC-Okta/redirect_url"
   

   Set OP_SERVICE_ACCOUNT_TOKEN in the environment. Secrets resolve in-memory at boot using the 1Password SDK and are never written back to disk or KV storage in plaintext.

2. Master Key Encryption (PSLENS_MASTER_KEY): Set PSLENS_MASTER_KEY (a 64-character hex AES-256 key). Passwords entered in the Settings UI or stored in NATS KV/YAML are stored as encrypted strings (ENC[...]).

3. Environment Variable Overrides: Override passwords dynamically via environment variables without editing files:

   export PSLENS_DB_PROD_PASSWORD="YourPasswordHere"
   

Bare Minimum Configuration Example

To start psLens with zero pre-configured database connections, use the following minimal config.yaml:

server:
  port: 8080

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"
  traceStoreDir: "./data/traces"
  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_PSLENS_SWSPQL/"
    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_PSLENS_SWSPQL/"
    username: "PSLENS_API"
    password: "dev-api-password"
    timezone: "America/Chicago"
    production: false
    downtimes:
      - name: "Nightly Downtime"
        enabled: true
        startTime: "22:00"
        endTime: "06:00"
        daysOfWeek: [1, 2, 3, 4, 5]
      - name: "Weekend Maintenance"
        enabled: true
        startAt: "2026-07-04T00:00:00Z"
        endAt: "2026-07-05T23:59:59Z"

alerts:
  enabled: true
  intervalMinutes: 5
  checks:
    long_running_processes:
      enabled: true
      thresholdMinutes: 20
      anomalyMultiplier: 4.0
      anomalyMinBaselineMinutes: 10
    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/..."

reports:
  - id: "security-full-access-permlists"
    enabled: true
    dbNames: ["PROD"]
    schedule:
      interval: "daily"
      timeOfDay: "02:00"
    emailTarget: "psoft-alerts@example.com"

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",
    "traceStoreDir": "./data/traces",
    "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_PSLENS_SWSPQL/",
      "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_PSLENS_SWSPQL/",
      "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,
        "anomalyMultiplier": 4.0,
        "anomalyMinBaselineMinutes": 10
      },
      "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/..."
      }
    ]
  },
  "reports": [
    {
      "id": "security-full-access-permlists",
      "enabled": true,
      "dbNames": ["PROD"],
      "schedule": {
        "interval": "daily",
        "timeOfDay": "02:00"
      },
      "emailTarget": "psoft-alerts@example.com"
    }
  ]
}

Server Settings

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

Tip: Storage directories (natsStoreDir, traceStoreDir, etc.) can also be configured via environment variables (PSLENS_TRACE_STORE_DIR, PSLENS_PROJECT_STORE_DIR, etc.) and should be placed on persistent storage.

Database Connections

You can configure one or more PeopleSoft databases under the databases list. psLens monitors the health of each connection and shows status on the dashboard.

Scheduled Downtimes

Downtimes allow silencing alerts and pausing connection health checks for non-production environments that go offline regularly (e.g., overnight or on weekends).

Each entry in the downtimes list supports the following settings:

startTime/endTime are wall-clock times in the connection’s timezone (UTC if unset). Rules are validated when the configuration is saved; a rule must define a recurring window (startTime + endTime) and/or a one-off range (startAt/endAt).

When a database is in a scheduled downtime, the connection manager sets its status to Downtime on the dashboard, background alert checks are skipped (including the Integration Broker down check), email/webhook notifications are suppressed, and the database does not count against overall health. When the window ends, psLens rechecks the connection immediately and treats the first failed check as a real outage — size windows to cover the system’s boot time.

A weekend window that spans from Saturday evening to Monday morning is composed of two rules, since an overnight window belongs to its start day:

downtimes:
  - name: "Weekend nights"
    enabled: true
    startTime: "22:00"
    endTime: "06:00"
    daysOfWeek: [6, 0]   # Sat night -> Sun morning, Sun night -> Mon morning
  - name: "Sunday all day"
    enabled: true
    startTime: "00:00"
    endTime: "24:00"
    daysOfWeek: [0]

The baseURL Format

The baseURL is the Integration Broker REST endpoint for the SWS service. It follows this pattern:

https://{igw-host}:{port}/PSIGW/RESTListeningConnector/{database-name}/CHG_PSLENS_SWSPQL/

The trailing slash is required.

Environment Variable Overrides

Sensitive settings like passwords can be overridden with environment variables to avoid storing them in config.yaml. The override format is:

PSLENS_DB_{NAME}_{FIELD}

Where {NAME} matches the name field of the database in config.yaml.

For Fly.io and Docker container compatibility, non-alphanumeric characters (such as dashes - or dots .) in database names are automatically converted to underscores (_) and uppercased.

For example, for a database named COOL-DB-FOR-DEV, you can use:

export PSLENS_DB_COOL_DB_FOR_DEV_PASSWORD="my-secure-password"

The raw name PSLENS_DB_COOL-DB-FOR-DEV_PASSWORD remains supported for backward compatibility where supported by your shell.

1Password Secret References

You can place 1Password secret references (op://...) directly in config.yaml or through the Settings UI. Supported fields include:

• Database Connections: baseURL, username, password, piaURL
• Database Notifications: notifications.emailTarget, notifications.webhookTarget
• Database WebLib Health Checks: alerts.checks[].weblibTestTargets[].url, username, password
• SMTP Mailer: smtp.host, smtp.port, smtp.username, smtp.password, smtp.fromName, smtp.fromEmail
• Authentication (OIDC): auth.oidc.issuerUrl, auth.oidc.clientId, auth.oidc.clientSecret, auth.oidc.redirectUrl
• Notifications & Subscriptions: notifications.email_lists[].emails, notifications.webhooks[].url, notifications.subscriptions[].target

databases:
  - name: "PROD"
    baseURL: "op://VaultName/ItemName/base_url"
    username: "PSLENS_API"
    password: "op://VaultName/ItemName/password"

To resolve 1Password secret references at boot, set a 1Password Service Account token in the environment:

export OP_SERVICE_ACCOUNT_TOKEN="op_service_account_token_here"

If OP_SERVICE_ACCOUNT_TOKEN (or PSLENS_OP_SERVICE_ACCOUNT_TOKEN) is set, psLens resolves all op:// references on boot using the 1Password SDK. If the environment variable is not set, 1Password resolution is skipped.

Database-Specific Notifications

By default, alert notifications for all databases are routed using global subscription rules (see Notifications & Webhooks Settings).

However, you can configure database-specific notifications under the notifications property of a database entry. Doing so acts as a complete override: all alerts (regardless of severity level) and resolutions for that specific database are routed directly to the database-level targets, bypassing global subscriptions entirely.

Each entry in the notifications block supports the following settings:

Example database connection configuration with inline notifications:

databases:
  - name: "PROD"
    description: "Production Environment"
    baseURL: "https://psft.example.com:8000/PSIGW/RESTListeningConnector/PSFT_HR/CHG_PSLENS_SWSPQL/"
    username: "PSLENS_API"
    password: "securepassword"
    notifications:
      emailEnabled: true
      emailTarget: "prod-alerts@example.com"
      webhookEnabled: true
      webhookTarget: "https://hooks.slack.com/services/..."

Alerts Configuration

The alerts section controls the background alert checking system. See the Alerts section for details on what each alert detects.

Top-Level Alert Settings

Alert Check Settings

Each alert type under checks supports some or all of the following settings:

Available Alert Checks

Authentication Settings

The auth section configures native authentication (email-based magic link or native OpenID Connect SSO). Authentication is enabled by default. To disable authentication, set enabled: false explicitly in config.yaml. Authentication settings are file-authoritative and cannot be modified or turned off from the web interface.

SMTP Settings

The email server is edited in the app under Settings → Notifications (Email Server card). Changes apply to alert and report emails immediately; login (magic link) emails pick them up after the next server restart. A blank password on save keeps the stored password.

The smtp block in config.yaml seeds the email server on first boot only; after that, the settings saved in the UI are authoritative. PSLENS_SMTP_* environment variables override both and make the card read-only in the UI.

Outbound email can be tested on the same card: enter a recipient address under Send Test Email and click Send Test. The result is recorded in Alert Delivery History.

Notifications & Webhooks Settings

Notification rules decide where alert messages are dispatched. They are managed in the app under Settings → Notifications, where email distribution lists, webhook destinations (Slack, Microsoft Teams, and custom endpoints), and subscription routing rules can be configured and live-tested.

Email Distribution Lists (notifications.email_lists)

Predefined recipient lists referenced by notifications and reports:

notifications:
  email_lists:
    ops_team:
      name: "Operations Team"
      emails: "ops@company.com, pager@company.com"

Webhooks (notifications.webhooks)

Predefined incoming webhook URLs for Slack, Microsoft Teams Workflows (Adaptive Cards), or custom JSON receivers:

notifications:
  webhooks:
    slack_alerts:
      name: "Slack Alert Channel"
      url: "https://hooks.slack.com/services/..."
    teams_ops:
      name: "Teams Operations Channel"
      url: "https://default...powerautomate.../invoke"

Subscriptions (notifications.subscriptions)

Routing subscriptions matching fired alerts and dispatching them to email or webhook targets:

Note: psLens automatically detects Slack and MS Teams Adaptive Card webhook URLs and formats native payloads accordingly.

Reports Scheduling Settings

The reports section allows you to define static scheduling configs and completion notifications directly in the configuration file.

Report Properties

Under reports, define a list of scheduled report objects:

Schedule Recurrence Properties

Under reports.schedule, define when the job should run:

JSON Schema Validation

To enable autocompletion, tooltips, and real-time schema validation within your IDE (such as VS Code), use the built-in JSON schema:

Option A: Live URL (Online)

If your psLens server is running locally (e.g., on port 8080), you can add the $schema parameter to the top of your JSON config file:

{
  "$schema": "http://localhost:8080/static/config-schema.json",
  "server": {
    "port": 8080
  }
}

Option B: Local File Reference (Offline)

To configure your workspace offline, reference the schema file directly. In VS Code, add this to your .vscode/settings.json:

{
  "json.schemas": [
    {
      "fileMatch": ["config.json"],
      "url": "./static/config-schema.json"
    }
  ],
  "yaml.schemas": {
    "./static/config-schema.json": ["config.yaml"]
  }
}

Securing psLens

For production deployments, you should restrict access to the psLens interface.

Recommended Security Controls

1. Enable Built-In Magic Link Auth: Turn on auth.enabled and configure SMTP credentials and authorizedUsers to require code validation on login.
2. Setup a Master Key (PSLENS_MASTER_KEY): Provide a 32-byte (64 hex characters) key in the PSLENS_MASTER_KEY environment variable. All database and SMTP passwords entered in the UI or configuration are then encrypted at rest using AES-256-GCM.
3. Reverse Proxy / VPN: Place psLens behind a reverse proxy (e.g., Cloudflare Access, oauth2-proxy, nginx, Tailscale) to delegate authentication to your company’s Identity Provider (SAML/OIDC). When using an external SSO proxy, you can keep auth.enabled disabled and restrict the psLens binary to bind only on 127.0.0.1 or internal networks.

Warning: Never expose psLens to the public internet without either turning on the built-in magic-link auth or placing an authenticated reverse proxy in front of it. Doing so exposes read access to PeopleSoft system metadata.

Active Configuration and Hot-Reloading

psLens keeps its settings in two places:

1. Active configuration (embedded key-value store): when you edit connections, credentials, email settings, alert schedules, or notification rules in the web interface, changes are saved here and take effect immediately without a server restart. Every change is kept as a numbered revision under Settings → Change History, where any revision can be viewed or restored.
2. config.yaml on disk: the bootstrap file that seeds the active configuration on first boot. Saved changes are also written back to it as a backup on the persistent storage volume.

Configuration Seeding

On initial boot, or when the environment variable PSLENS_FORCE_SEED_CONFIG=true is set, the application seeds the active configuration from config.yaml.

If the active configuration drifts from config.yaml, the Settings → Advanced page shows a “Settings differ from the config.yaml file on disk” notice. To resolve it:

• Click Load settings from config.yaml on the Advanced page to overwrite the active configuration with the file contents (this discards changes made in the UI).
• If the file path is writable, click Overwrite config.yaml on disk to write the active configuration to the file. On containerized or ephemeral deployment models (like fly.io without persistent storage volumes), these local file changes will be lost when the container restarts or is re-deployed.
• Alternatively, copy the Active Configuration YAML from the Advanced page into your config.yaml file to bring the disk file in sync.

Secret Key Management (Encryption at Rest)

When the PSLENS_MASTER_KEY environment variable is set with a 32-byte hex-encoded key, all database and SMTP passwords entered in the UI are encrypted at rest. If the master key is not configured, passwords are saved in plaintext.

Rotating the Master Key

To rotate the cryptographic key used for credential encryption:

1. Enter a new 32-byte hex key in the Rotate Encryption Key field.
2. Click Rotate Master Key. The server decrypts all stored credentials using the old key and re-encrypts them with the new key in NATS KV.
3. Update the PSLENS_MASTER_KEY environment variable in your deployment configuration (e.g., Fly.io secrets or .env file) to match the new key before restarting the container. If the container restarts with a mismatched key, it cannot decrypt the configuration.

5 - Deployment Options

Deployment Options

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

1. How do I get the image? Distribution and authentication.
2. How do I upgrade without losing my config? Volumes, env vars, and the master key.
3. 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.

1. Image Distribution

psLens is published to the GitHub Container Registry (GHCR) as a private package. Cedar Hills Group issues a read-only token to each client.

Authenticating

1. Cedar Hills Group sends you a GitHub fine-grained personal access token (PAT) scoped to read:packages on the pslens package only.

2. On the Docker host:

   echo "YOUR_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
   

   The credentials are stored in ~/.docker/config.json. They persist across host reboots.

3. Verify the pull works:

   docker pull ghcr.io/cedarhillsgroup/pslens:latest
   

Image Tags

The release pipeline publishes four tag flavors for every release:

Recommended: Pin production to vMAJOR.MINOR. You’ll automatically pick up patch fixes when you re-run docker compose pull, but never get an unexpected breaking change from a minor or major version bump.

When You Can’t Reach ghcr.io

If the Docker host can’t make outbound HTTPS to ghcr.io (common in segmented enterprise networks), use the air-gapped flow documented in Installation:

# On a machine with internet access:
docker pull ghcr.io/cedarhillsgroup/pslens:v1.4.2
docker save ghcr.io/cedarhillsgroup/pslens:v1.4.2 | gzip > pslens-v1.4.2.tar.gz

# Transfer the .tar.gz to the target host (USB, internal artifact repo, etc.), then:
docker load < pslens-v1.4.2.tar.gz

You can also mirror the image into your own private registry (Harbor, AWS ECR, Azure ACR, GitLab Registry). Pull it once, retag, push, and reference the mirrored image in your docker-compose.yml. Cedar Hills Group is happy to provide a one-time pull script if you need to automate this.

Troubleshooting Pull Failures

2. Configuration and Secrets

The most failure-prone part of self-hosted deployment is preserving configuration and secrets through upgrades. This section is explicit about what survives docker compose pull && docker compose up -d and what doesn’t.

What Persists, What Doesn’t

Persistent (must be on a volume):

• /data/nats — NATS JetStream store. Contains the recently-viewed objects KV, the report store (generated markdown reports), alert state, and, if you use the in-app config UI, the AES-256-encrypted database passwords KV.
• /data/projects — project store for uploaded .zip project archives.
• /app/config.yaml — bind-mounted from the host filesystem.

Ephemeral (re-created on every container start):

• Whitelist cache (re-fetched from PeopleSoft on startup).
• PIA URL discovery cache.
• In-memory session state.

The default docker-compose.yml in Installation already wires the persistent items correctly: a named volume pslens_data mounted at /data, and config.yaml bind-mounted at /app/config.yaml:ro. As long as you don’t docker volume rm pslens_data, your data survives any number of image upgrades.

Three Configuration Modes

There are three ways to source configuration. Pick one based on how many people will administer the system and how you manage secrets.

Mode B example (recommended)

config.yaml:

server:
  port: 8080
  host: "0.0.0.0"
  appBaseURL: "https://pslens.example.com"
  natsStoreDir: "/data/nats"

databases:
  - name: "PROD"
    description: "Production HCM"
    baseURL: "https://psft.example.com:8000/PSIGW/RESTListeningConnector/PSFT_HR/CHG_PSLENS_SWSPQL/"
    username: "PSLENS_API"
    password: "placeholder"      # Overridden by PSLENS_DB_PROD_PASSWORD
    timezone: "America/Chicago"

.env (sibling of docker-compose.yml, chmod 600, gitignored):

PSLENS_DB_PROD_PASSWORD=actual-password-here
PSLENS_MASTER_KEY=base64-encoded-32-byte-key

docker-compose.yml references env_file: .env; Docker injects every variable into the container at startup.

Tip: The env-var override convention is PSLENS_DB_{NAME}_PASSWORD where {NAME} is the database name from config.yaml, uppercased. For a database named DEV_HR, the variable is PSLENS_DB_DEV_HR_PASSWORD.

About PSLENS_MASTER_KEY

In production, psLens requires PSLENS_MASTER_KEY to be set. It’s used to encrypt database passwords stored in the NATS KV bucket. Generate one once:

openssl rand -base64 32

Critical: back this key up out-of-band in your password manager, AWS Secrets Manager, HashiCorp Vault, or wherever you keep root-of-trust secrets. If you lose the master key, the encrypted password blob in /data/nats becomes unrecoverable and you’ll have to re-enter every database password.

Backups

Daily backup of the data volume is one line:

docker run --rm \
  -v pslens_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/pslens-data-$(date +%F).tar.gz -C / data

What to back up where:

• Data volume (pslens_data) — daily tarball, retain 14-30 days. Captures reports, alert state, and encrypted passwords KV.
• config.yaml — check into your infrastructure-as-code repo (gitignore the password fields, or use the placeholder pattern from Mode B).
• .env — store in your secrets manager. Never check this into git.

To restore: stop psLens, docker volume create pslens_data, untar into the volume, restart.

3. TLS / HTTPS Options

psLens does not terminate TLS in the binary by default. It listens on plain HTTP and expects either a reverse proxy, an in-binary TLS configuration, or a tunnel to provide HTTPS.

There are six viable options. They’re compared below on the same axes: certificate source, automation, operational complexity, and the scenario each fits best.

Quick recommendation

Details on each option follow.

Option 1: Go-native TLS via crypto/tls (cert files)

psLens loads a PEM cert + key from disk and serves TLS directly. No reverse proxy, no extra container, no external dependencies.

Status: This requires a small code change to psLens (currently the binary only listens on plain HTTP). Contact Cedar Hills Group if you need this option — it’s roughly 30 lines of Go and a config block. Tracked in the backlog.

How it works once implemented:

server:
  tls:
    enabled: true
    certFile: "/certs/pslens.crt"
    keyFile: "/certs/pslens.key"

Mount /certs as a read-only bind from the host where your PKI tooling drops renewed certs.

Option 2: Go-native TLS via acme/autocert (Let’s Encrypt)

psLens fetches and renews Let’s Encrypt certs in-process using the golang.org/x/crypto/acme/autocert library.

Status: Like Option 1, this requires a small code addition to psLens. Contact Cedar Hills Group.

How it works once implemented:

server:
  tls:
    autocert:
      enabled: true
      hostnames: ["pslens.example.com"]
      email: "admin@example.com"
      cacheDir: "/data/acme"

Cert cache lives in /data/acme so it survives container restarts as long as the pslens_data volume does. psLens listens on :80 for the ACME HTTP-01 challenge and :443 for TLS.

Option 3: Caddy sidecar

Run Caddy as a second service in the same docker-compose.yml. Caddy terminates TLS and reverse-proxies to psLens on the internal Docker network.

Caddyfile (5 lines for the public-internet case):

pslens.example.com {
    reverse_proxy pslens:8080
    encode gzip
}

For an internal-only deployment (no public DNS, no Let’s Encrypt), use Caddy’s built-in CA:

pslens.internal.example.com {
    tls internal
    reverse_proxy pslens:8080
}

You’ll need to add Caddy’s root cert to client browsers (push it via MDM) so they trust the internal cert.

docker-compose.yml addition:

services:
  pslens:
    image: ghcr.io/cedarhillsgroup/pslens:v1.4
    expose:
      - "8080"      # no longer "ports:" — only Caddy needs an external port
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - pslens_data:/data
    env_file: .env
    restart: unless-stopped

  caddy:
    image: caddy:2-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

volumes:
  pslens_data:
  caddy_data:
  caddy_config: