Explain a field with a Magic Button

A Magic Button tells the Assistant which field the user is looking at, and its value. To explain it, the Assistant needs a tool that knows what fields mean. This guide builds that tool, describe_field, on PeopleTools metadata, and adds a Magic Button to the Status field of the training request page.

You’ll build: the GET /fields/{field} operation in ZZ_ASSISTANT_HR, the describe_field tool, and a Magic Button on ZZ_TRAIN_STATUS.

Plan it

Decision	For this tool
Input	`field`, the field’s name from the page context, and optionally its `value`
Output	The field’s label and description, and for a coded field, its values and the value’s meaning
Language	The user’s, from their PeopleSoft profile, wherever a translation exists
Security	`ZZ_ASSIST_USER`. Field definitions aren’t sensitive, so every Assistant user can call it

Build the API

Read the label from PSDBFLDLABL, the field’s default label, where DEFAULT_LABEL is 1. Use PSDBFLDLABLLANG for the user’s language, when it has a row for it.
Read the description from PSDBFIELD.DESCRLONG, and its related language table for other languages.

Read the translate values that are in effect today, in the user’s language, falling back to the base language where there’s no translation:

SELECT X.FIELDVALUE, COALESCE(L.XLATLONGNAME, X.XLATLONGNAME)
  FROM PSXLATITEM X
  LEFT OUTER JOIN PSXLATITEMLANG L
    ON L.FIELDNAME = X.FIELDNAME
   AND L.FIELDVALUE = X.FIELDVALUE
   AND L.EFFDT = X.EFFDT
   AND L.LANGUAGE_CD = :2
 WHERE X.FIELDNAME = :1
   AND X.EFF_STATUS = 'A'
   AND X.EFFDT = (SELECT MAX(X2.EFFDT)
                    FROM PSXLATITEM X2
                   WHERE X2.FIELDNAME = X.FIELDNAME
                     AND X2.FIELDVALUE = X.FIELDVALUE
                     AND X2.EFFDT <= %CurrentDateIn)
 ORDER BY X.FIELDVALUE

The query takes the latest row for each value that’s in effect today, and keeps it only if it’s active, so a value inactivated in a newer row drops out.

Create the operation as the GET method of the URI template fields/{field}, with field as a base template parameter, value as an optional query parameter, and OAuth 2.0 required.

Add the tool and the button

The description tells the LLM when to call the tool, and that a Magic Button’s context holds its input:

Describe a PeopleSoft field: its label and meaning and, for a
coded field, what each code means, in the user's language. Use
it for questions about a field, such as those from a Magic
Button, whose page context gives the field's name and value.

tools:
  describe_field:
    operation: GET /fields/{field}
    progress: Looking up this field

Then add a Magic Button to the Status field, ZZ_TRAIN_STATUS, of the ZZ_TRAINING_REQ component, as Magic Buttons describes.

What happens

A manager opens a training request whose status is P, chooses Ask the Assistant on the Status field, and asks “What does this mean?”:

The turn context names the field: the page, the field ZZ_TRAIN_STATUS, and the value P, as in the turn context.

The LLM calls describe_field with {"field": "ZZ_TRAIN_STATUS", "value": "P"}, and gets:

{
  "field": "ZZ_TRAIN_STATUS",
  "label": "Status",
  "description": "Where the request is in its approval.",
  "values": [
    { "value": "A", "label": "Approved" },
    { "value": "C", "label": "Completed" },
    { "value": "D", "label": "Denied" },
    { "value": "P", "label": "Pending Approval" }
  ],
  "valueLabel": "Pending Approval"
}

The Assistant answers:

P means Pending Approval: the request is waiting to be approved. The other statuses are Approved, Denied, and Completed.

Check it

A user whose language is French gets French labels, wherever PSXLATITEMLANG and PSDBFLDLABLLANG have them.
A value you’ve inactivated, with a newer inactive row, no longer appears.
A field without translate values, such as a comment, gets its label and description only.
A field on a sensitive page has no Magic Button: its value would travel in the chat page’s URL, as Magic Buttons warns.