Project Meta

• 1: Why was SWS Created?
• 2: Terminology
• 3: SWS Assumptions and Limitations

1 - Why was SWS Created?

The genesis story for SWS now lives on the About page — the natural home for company and product backstory.

This page is preserved as a redirect so existing links continue to resolve.

2 - Terminology

See our Integration Book - Terminology Sections for a deeper Integration Broker vocabulary; this page covers just the terms that come up repeatedly in SWS documentation.

HTTP / REST Terms

HTTP

HTTP (Hypertext Transfer Protocol) is a standardized protocol used for the transfer of information on the World Wide Web. It establishes a connection between a client and a server, allowing for the request and delivery of web resources such as HTML pages, images, videos, and more. HTTP operates on a request-response model, where the client sends a request to the server, and the server responds with the requested data or an appropriate error message. It forms the foundation for web browsing, enabling the retrieval and display of web content in a user-friendly manner.

Client

An HTTP user of your API. This could be a simple command line (CLI) application like curl or wget. It will likely be some external application that needs to pull data from PeopleSoft.

PSIGW

PeopleSoft Integration Gateway - This is the web server that is running your integration broker.

Encoding

The way the data is “wrapped” and presented to the client: JSON, XML or CSV.

Request

The HTTP request made by the client. This includes the URL path, query strings, and HTTP Headers.

Response

The data that comes back from the server to the client in reply to an HTTP Request.

REST

REST (Representational State Transfer) is an architectural style for designing networked applications, particularly web services, that emphasizes a stateless, client-server communication model. It promotes the use of standard HTTP methods like GET, POST, PUT, and DELETE to perform operations on resources identified by unique URLs (Uniform Resource Locators). RESTful systems leverage the principles of scalability, simplicity, and modifiability, allowing different clients to interact with the server using a uniform and predictable interface. It facilitates the exchange of data in various formats, such as JSON or XML, and supports the separation of concerns between client and server components.

PsoftQL

A proprietary JSON and XML syntax to request data from SWS. Read more on the PsoftQL Syntax

PeopleSoft Concepts

These terms come from PeopleSoft itself. SWS uses them constantly. If you have a PeopleSoft background you can skip this section; if you’re integrating with SWS from a non-PeopleSoft perspective, the definitions below will save you a lot of context-switching.

Integration Broker (IB)

PeopleSoft’s built-in middleware for inbound and outbound web services. Everything SWS does runs through Integration Broker: the RESTListeningConnector receives the HTTP request, IB authenticates the caller, routes to the service operation, and serializes the response. The companion book Integration Broker — The Missing Manual covers IB in depth.

PSIGW

PeopleSoft Integration Gateway — the Java web application (a servlet inside PSIGW.war) deployed to the PeopleSoft web server tier. The gateway is the network edge of IB: it accepts inbound HTTP and forwards messages to the application server. Inbound REST calls hit a path like /PSIGW/RESTListeningConnector/<NODE>/<SERVICE>/....

Service

An IB grouping for related service operations. CHG_SWS is the Service name used by SWS — it appears in the request URL as the prefix segment after the listening node.

Service Operation

The specific handler within a Service that runs in response to an inbound message. SWS ships two: CHG_SWS_GET (called by every admin-configured SWS path) and CHG_SWS_PSOFTQL (the advanced caller-driven endpoint). When the docs say “configure security on the service operation,” they mean granting access to one of these two names in Security → Permissions & Roles. See also the Service vs Service Operation alert on the configuration page.

OPRID

The PeopleSoft user identifier — what other systems call a username. Stored in PSOPRDEFN. SWS authenticates inbound REST calls against an OPRID + password using HTTP Basic Authentication. Per‑user data filtering inside SQL relies on %OPERATOR (the current OPRID) and %EMPLOYEEID (the EMPLID the OPRID is associated with).

PSOPRDEFN

The PeopleSoft table that stores user accounts (OPRIDs), passwords, locked-account flags, and the link from each OPRID to its primary role. Whenever you read “OPRID and password from PSOPRDEFN,” that’s the table being checked.

Role

A named bundle of permission lists assigned to one or more OPRIDs. PeopleSoft security flows OPRID → role → permission list → access. SWS itself does not check roles directly; it checks the permission lists granted through the OPRID’s roles.

Permission List (CLASSID)

The leaf of the PeopleSoft security tree — the unit that actually grants access to service operations, components, and (for SWS) configured URL paths. Stored with column name CLASSID in the database, hence the column name in the SWS whitelist table C_SWS_REC_WL. The CLASSID is not the same string as the OPRID or the role; look it up directly in Security → Permission Lists rather than guessing.

Component

The PeopleSoft equivalent of a “page” or “form.” Configuration pages SWS delivers (for example CHG_SWS_CONF_TBL for the SWS setup grid) are components. You can grant or revoke a permission list’s access to a component to control who sees the SWS admin UI.

Record

PeopleSoft’s metadata wrapper around a database table or view — it carries the field list, field types, key definitions, prompt table references, and other attributes the application uses. SWS reads record metadata at run time to know which fields exist on a table, which fields are keys, and which fields have XLAT or prompt-table descriptions. PsoftQL requests use the record name (e.g. PSROLEDEFN), not the underlying database table name (e.g. PS_PSROLEDEFN).

XLAT

Translate values — PeopleSoft’s small-domain lookup mechanism for single-character or short codes that decode to human-readable labels (e.g. ROLESTATUS = 'A' → "Active", ROLESTATUS = 'I' → "Inactive"). Stored centrally in PSXLATITEM, keyed by field name and value. SWS can inject the decoded label into responses via includeAllDescriptions or includeDescriptionsFor on a PsoftQL request.

Prompt Table

An XLAT-style decode for codes whose value-set is large or business-specific (e.g. DEPTID → department description). Instead of central rows in PSXLATITEM, each prompt table is a separate record (e.g. DEPT_TBL decodes DEPTID). SWS resolves prompt-table descriptions the same way as XLATs when you ask for them with includeDescriptionsFor.

EFFDT

“Effective date” — a key field on PeopleSoft records that hold time-versioned data (employees, courses, configurations). Each row’s EFFDT is the date that row’s data first takes effect; the row remains in effect until a newer row with a later EFFDT arrives for the same key. SWS auto-resolves to the row that is current “today” unless you supply noEffectiveDateLogic or effectiveDateOverride.

EFF_STATUS

A character field on effective-dated records, paired with EFFDT, that marks a row as Active or Inactive. SWS auto-filters to EFF_STATUS = 'A' unless you set noEffectiveStatusLogic: true. Inactive rows exist when an organization needs to retire an EFFDT row but keep the history.

EFFSEQ

“Effective sequence” — a third key on a small number of records (notably JOB) that lets multiple rows share the same EFFDT for the same entity, ordered by sequence number. SWS auto-resolves to the highest EFFSEQ for the chosen EFFDT unless noEffectiveSequenceLogic: true is set.

Meta-SQL

PeopleSoft’s database-portable SQL macro layer — text inside SQL of the form %MACRO, %TABLE(record), %CURRENTDATEIN, %DATEIN(date), etc., that the PeopleSoft runtime expands into the correct dialect for Oracle or SQL Server before execution. SWS SQL configurations and PsoftQL sqlWhereClause strings both pass through this expansion. %TABLE(PSOPRDEFN) resolves to the physical table name (e.g. PS_PSOPRDEFN or PSOPRDEFN) at run time so your configuration survives Oracle’s release-to-release table renames.

Whitelist (SWS)

SWS-specific concept implemented in the C_SWS_REC_WL table. Each row pairs a CLASSID (permission list) with a RECNAME (record), declaring that callers with that permission list may include that record in a CHG_SWS_PSOFTQL request. Whitelist filtering applies only to CHG_SWS_PSOFTQL; CHG_SWS_GET controls access at the URL-path level instead (via the permission-list grid on each SWS configuration row). See Data Access Models.

3 - SWS Assumptions and Limitations

Assumptions

• You have a working PeopleSoft Integration Broker (IB) setup, including a configured RESTListeningConnector on PSIGW.
• You want to pull information out of PeopleSoft. SWS is read-only by design.
• PeopleTools version greater than 8.56.
• You can create custom Oracle/SQL Server objects in your PeopleSoft database (SWS ships custom records, application packages, and a service operation).

What SWS does not do

These are intentional product boundaries, not bugs. If your use case is on this list, SWS is the wrong tool and another approach is needed.

Read-only, GET-only

SWS exposes PeopleSoft data as HTTP GETs. It does not create, update, or delete PeopleSoft data. There is no PUT, POST-to-write, or DELETE pathway. To push data into PeopleSoft you still need a traditional Integration Broker service operation, a Component Interface, or a delivered web service. Generic insert/update support is discussed on the road map; it does not exist today.

PeopleSoft must be the server

SWS only works when PeopleSoft is the HTTP server answering inbound requests. If you need PeopleSoft to make an outbound call to a third-party REST API, use a standard Integration Broker outbound consumer — SWS plays no role there.

Data is returned in PeopleSoft shape

By default the response uses PeopleSoft field names (EMPLID, ACAD_CAREER, DESCR) and PeopleSoft formats (ISO dates, raw XLAT codes). Two partial mitigations exist today:

• SQL configurations can alias columns in the Output Fields Grid so the client sees friendly names (see the SQL worked example).
• PsoftQL can request decoded XLAT and prompt-table descriptions via includeDescriptionsFor and includeAllDescriptions.

Neither covers true data transformation — flattening parent/child trees, computing derived values, or reshaping the response schema for a specific vendor. A future release may add a transformation pipeline; tracked on the road map.

CSV output is SQL-only

CSV (Accept: text/csv) only works for SQL-type SWS configurations. PsoftQL responses are JSON or XML — they are nested by design and CSV has no representation for the parent/child structure. See the Syntax Types comparison on the configuration page.

IN operator in criteriaFields is not honored

The JSON schema lists IN as a supported operator value, but the current server build silently returns zero rows for every input form (comma-separated string, parenthesized list, fieldValues array). Use sqlWhereClause with native SQL IN (...) instead. See the IN operator status note on the Operator Examples page. Closing this gap is on the road map.

Aggregate queries cannot paginate or join

When isAggregate: true is set on a PsoftQL request:

• Only a single root record is allowed — no child records (parentRecordName) and no joins.
• Pagination is not supported — pageNumber must be omitted or 1. Setting it to 2 or higher returns responseCode: 400 with the message “Pagination is not supported in aggregate mode.”
• The flags includeFieldTypes, includeAllFieldLabels, and includeKeyFieldIndicators are ignored.

For the full list of what does and does not work alongside isAggregate: true, see the Aggregate Queries section of the PsoftQL syntax reference.

XML isAggregate mode

Aggregate queries in XML request format do not currently produce the same well-formed aggregate response that JSON requests do. Stick with JSON when using isAggregate: true.

Field-name typos in criteriaFields are silent

The handler does not validate that criteriaFields[].fieldName exists on the target record. A typo causes the criterion to be silently dropped and the request returns the unfiltered result. Always spot-check that the returned rows actually match the criterion you intended. See Silent behaviours on the syntax page.

Authentication options are limited

The only viable REST authentication mechanism today is HTTP Basic Authentication tied to a PeopleSoft OPRID / password stored in PSOPRDEFN. SWS does not currently support API keys, OAuth 2.0 client-credentials grants, mutual TLS, or JWT bearer tokens at the application layer. This is a PeopleSoft IB constraint, not an SWS choice — anything you read in the Integration Broker REST security reference also applies to SWS.

Caching is constrained by the IB cache

SWS exposes the PeopleTools RESTListeningConnector cache via the Minutes to Cache Response configuration field. Read the Caching article before enabling it — the cache key does not include the caller’s OPRID, so caching a response that uses %EMPLOYEEID or %OPERATOR will leak one caller’s data to the next.

Other known boundaries

• Attachment fields are not auto-handled. Records with EFFDT/EFF_STATUS/EFFSEQ are auto-handled; binary attachment fields (BLOB columns referenced by PV_ATT_* metadata) are not yet auto-rendered.
• No meta/endpoints discovery endpoint yet. There is no live “list every SWS-configured path” endpoint — the closest substitute today is querying the configuration tables (C_SWS_CONF_TBL and friends) directly.
• OpenAPI / Swagger generation is on the road map but not yet shipped.

For features under active consideration, see the Road Map.