Skip to content
SparkyaiPeopleSoft

Help users find the right page

“Where do I update my direct deposit?” is one of the questions help desks hear most. PeopleSoft already has a search built for it: navigation search, which indexes the portal registry’s content references with the delivered PTPORTALREGISTRY search definition and category. This guide builds the find_page tool on it.

You’ll build: the GET /navigation/pages operation in ZZ_ASSISTANT_HR, and the find_page tool.

Plan it

Section titled “Plan it”
Decision For this tool
Input q: a few words for the task, such as direct deposit
Output Up to five pages the user can open, each with its label and URL
Security ZZ_ASSIST_USER, and the navigation search’s own security
Section titled “Why navigation search”
  • It only finds pages the user can open. Each content reference’s document in the index carries the permission lists that grant it, as security attributes, so a user’s search leaves out pages they can’t use. The tool never offers a page that would refuse the user.
  • It keeps up with the portal. A component you register appears after the next build of the PTPORTALREGISTRY index.
  • It matches meaning from PeopleTools 8.63. Semantic search is on by default for navigation search, so “I want to add dependents” finds the Dependent/Beneficiary page. On earlier releases, it matches words, and the LLM helps by passing the words that pages use.

Build the API

Section titled “Build the API”

  1. Check the index. PTPORTALREGISTRY must be deployed and indexed, with incremental builds scheduled, as for any search definition; see Deploy and build the index.

  2. Write the operation’s application class. It searches the PTPORTALREGISTRY category as the user, with the q parameter as the query text, and returns each result’s title and URL:

    The search, in the operation's class
    Local PT_SEARCH:SearchFactory &factory;
    Local PT_SEARCH:SearchQueryService &svc;
    Local PT_SEARCH:SearchQuery &qry;
    Local PT_SEARCH:SearchCategory &cat;
    Local PT_SEARCH:SearchResultCollection &results;
    

    &factory = create PT_SEARCH:SearchFactory();
    &svc = &factory.CreateQueryService("default");
    &qry = &svc.CreateQuery();
    &cat = create PT_SEARCH:SearchCategory("PTPORTALREGISTRY");
    &qry.Categories = CreateArray(&cat);
    &qry.QueryText = &words;
    &qry.Language = %Language_User;
    &results = &qry.Execute(1, 5);

    Return GetTitle() as each page’s label, and GetUrlLink() as its URL.

  3. Create the operation as the GET method of navigation/pages in ZZ_ASSISTANT_HR, with q as a required query parameter, and OAuth 2.0 required.

Write the description for the LLM

Section titled “Write the description for the LLM”

Navigation search works best with the words that pages use, not a whole question, so the description tells the LLM what to pass:

The operation's description
Find PeopleSoft pages that the signed-in user can open, by what
they're for. Use it for questions about where to do something
in PeopleSoft. Pass the task in a few words, such as "direct
deposit" or "add dependents", not the whole question.

What happens

Section titled “What happens”

An employee asks “Where do I update my direct deposit?”:

  1. The LLM calls find_page with {"q": "direct deposit"}.

  2. PeopleSoft searches the navigation index as the employee, and returns the pages they can open:

    The result
    {
      "pages": [
        { "label": "Direct Deposit",
          "url": "https://hr.example.com/psc/ps/EMPLOYEE/HRMS/..." },
        { "label": "Paychecks",
          "url": "https://hr.example.com/psc/ps/EMPLOYEE/HRMS/..." }
      ]
    }

  3. The Assistant answers:

    You can update it on the Direct Deposit page.

When nothing fits, or the only pages that fit are ones the user can’t open, the result is empty, and the Assistant says it couldn’t find a page they can use, and suggests the help desk.

Check it

Section titled “Check it”
  • An employee asks “Where do I approve timesheets?”, and is told there’s no page they can use, because the manager pages aren’t in their results.
  • A manager asks the same, and gets the approvals page.
  • A component you’ve just registered appears after the next PTPORTALREGISTRY index build.
  • The audit log shows find_page with a few words in q, not the whole question.