Skip to content
SparkyaiPeopleSoft

Follow a search, server by server

Here’s everything that happens between a user selecting Search and the results appearing, hop by hop, with where to look when one fails. It follows the question “Vouchers over $10,000 from Acme entered last month”, from a user who may see vouchers in business unit US001 only.

One NL search, hop by hop1 Question. 2 Run PeopleCode. 3 Plan request. 4 HTTPS, client certificate. 5 Prompt. 6 Plan. 7 Validated plan. 8 Plan. 9 Search, over REST. 10 Security callback. 11 Allowed values. 12 Matching documents. 13 Results page. 14 Open a result. The security callback goes from OpenSearch to the application server through the integration gateway.BrowserThe userWeb serverPIA, gatewayApp serverPeopleCodeNL SearchServiceLLMProvider's APIOpenSearchIndexes1 Question2 Run PeopleCode3 Plan request4 HTTPS, client certificate5 Prompt6 Plan7 Validated plan8 Plan9 Search, over REST10 Security callback11 Allowed values12 Matching documents13 Results page14 Open a result
One NL search, hop by hop. The numbers match the steps below. The security callback, 10 and 11, goes through PeopleSoft's integration gateway, and happens only when OpenSearch doesn't already have the user's security values.

Asking for a plan

Section titled “Asking for a plan”

  1. The browser sends the question. The user types it and selects Search, and the page posts it to the PeopleSoft web server, like any Fluid page action.

  2. The application server runs the Search button’s PeopleCode. The web server passes the request to the application server, whose component processor runs the button’s FieldChange PeopleCode, which calls the search application class.

    • Where to look: a PeopleCode trace for the test user, and the application server’s log.

  3. The class asks the integration gateway to call the service, with ConnectorRequest. These calls skip the integration engine, so they don’t appear in the Service Operations Monitor.

  4. The gateway calls the service over HTTPS, and presents its client certificate. nginx checks the certificate before the service sees the request.

    • Where to look: the gateway’s errorLog.html, and its msgLog.html with ig.log.level at 3 or more, in the gateway’s PSIGW.war directory; nginx’s error log on the service’s server. A request without a certificate gets 400 No required SSL certificate was sent.

  5. The service matches the question to intents, and prompts the LLM with the closest intents, today’s date, and the user’s language. It never learns who the user is.

  6. The LLM returns a plan, which the service validates. If the plan fails a check, the service asks once more.

  7. The service returns the validated plan, with its summary, or "intent": null if nothing fits.

    • Where to look: the service’s audit log, by request ID. To reproduce a plan, run the image’s plan command with the same question and date.

  8. The gateway hands the response back to the class, which logs the request ID with the user’s ID, and keeps the plan for the page.

Section titled “Running the search”

  1. The application server sends the search to OpenSearch. The Search Framework turns the category, the text, and the filters into a JSON query, and sends it to the search instance over REST, on the user’s behalf.

    • Where to look: the Search Instance page, at PeopleTools > Search Framework > Search Admin Activity Guide > Configuration > Search Instance. Its Ping, Login Test, Proxy Test, and Validate buttons test the connection.

  2. OpenSearch asks PeopleSoft for the user’s security values. PeopleSoft’s security plugin in OpenSearch calls back to PeopleSoft’s REST listening connector, through the integration gateway, to authenticate the user and fetch the values they may see.

  3. PeopleSoft returns them, from the search definition’s document filter application class: here, US001. The plugin caches them, so the user’s next searches skip steps 10 and 11.

    • Where to look: Integration Broker’s service configuration, since the callback needs the gateway URL and the default local node to be right. If a user’s access changed recently, the cached values may still be the old ones.

  4. OpenSearch returns the matching documents: Acme’s vouchers over $10,000 from last month, in business unit US001, and nothing else.

    • Where to look: a user who gets no results, whatever they ask, may have no security values at all, because the document filter class returned none for them.

Showing and opening results

Section titled “Showing and opening results”

  1. The application server builds the results page, with the summary as removable filters, and each result’s title, summary, and link, and returns it to the browser.

  2. The user opens a result. Its link opens the voucher’s page in a new request, and that component’s own security applies. A user who can find a voucher, but can’t open its page, still can’t open it.

Removing a filter repeats steps 9 to 13 from the stored plan, with no call to the service.

Where the time goes

Section titled “Where the time goes”

Steps 5 and 6, the LLM, take most of the time: usually a second or more, depending on the model. The search, steps 9 to 12, usually takes a fraction of a second, and a little longer when the user’s security values aren’t cached. If searches feel slow, time the plan first, with the image’s plan command.

When something goes wrong

Section titled “When something goes wrong”
  • The tile is missing. The user’s roles don’t include ZZ_NLS_USER.
  • Every search falls back to keyword search, and the service’s audit log is empty. Steps 3 and 4: the requests aren’t reaching the service. Check the gateway’s logs, its certificate, and nginx’s error log.
  • Every search falls back, but the audit log has the questions. Step 7: the audit log shows whether no intent fitted, or the plans failed validation.
  • Recent vouchers are missing. The index: check the incremental builds, or turn on real-time indexing.
  • A user finds nothing at all. Steps 10 to 12: their security values, and the search definition’s security.
  • A user finds vouchers they shouldn’t. Not NL Search: check the search definition’s security, and what its document filter class returns for them. They’d find the same vouchers with Global Search.