Chapter 23
API reference
Every Pega call a real component library uses, in one place. Search it, filter it, open an entry for when to use it, what to pass, what comes back and what goes wrong.
Pega 24 – 26
Words you will meet
- PConnect
- PCore
- Actions
Before you start
How to read an entry.
This chapter extends The Pega API. That one explains the ideas. This one is the lookup you keep open while you code.
It was written by reading how a working component library uses each call, and by checking each one against the platform’s published type definitionsFiles that describe every call: its name, its arguments and what it returns. Your editor reads them to warn you about mistakes.. It was not run against a live Pega, and anything that could not be confirmed is marked “inferred”. The examples are original and use invented names.
Documented
It is in the platform’s published type definitions, so the editor can check it for you.
Not in type definitions
It works in real components but the published type definitions do not list it. Guard it with a check and retest after every upgrade.
Arguments differ
It is documented, but working code passes arguments the type definitions do not show. Prefer the documented form.
Seen in every component
Five habits before any single call.
The same five safeguards turn up in component after component. Learn them once and most of the entries below read as obvious.
- 1Never trust a booleanA setting saved in the authoring studio can arrive as the text "true" or "false". Turn it into a real boolean before you use readOnly, required, disabled or hideLabel.
- 2Question every call with ?.Storybook mocks and different Pega versions do not offer the same calls. Write pConn?.getActionsApi?.()?.refresh?.() so a missing call does nothing instead of crashing.
- 3The first render can throwOn the very first render, getPConnect(), getStateProps() and getActionsApi() can fail because the case data is not attached yet. Wrap them in try/catch and fall back to handlers that do nothing.
- 4Lists arrive in more than one shapeA dropdown’s options (datasource, listOutput) are not always the same shape. Accept an array, an object with a data array, and an object with a source.
- 5Data answers differ by versionRows are normally at response.data.data, but accept response.data or a bare array as well.
The lookup
Every call, searchable.
Type what you need (“refresh”, “modal”, “case id”) or pick a group. Use Expand all to read a whole group at once. The highlighted “Gotcha” mark tells you which entries have something to watch for.
63 of 63 calls
PConnect 25
Your component’s own handle: read values, find children, know where you are.
Actions 13
Things that do something: write a value, open a form, refresh a view.
Data 11
Ask Pega for rows and records, or save them back.
Cases and screens 10
Containers, case windows, links and landing pages.
Session and live updates 4
Who is signed in, which language, and messages from other users.
Put them together
Calls that travel together.
A single call rarely does a whole job. Pick a job to see the calls in order, and the one thing that breaks it.
A button or field that calculates something on the server and fills other fields.
- 1Gather the inputspConn.getDataObject() for the whole case, or a few getValue calls.
- 2AskgetPageDataAsync for a page, or getDataAsync for a list. Take the first row of a list.
- 3Write each answerupdateFieldValue for every returned field.
- 4RedrawrefreshCaseView with preserveClientChanges.
Watch out
Drop the system keys before you send the case. Write with Promise.allSettled so one bad field does not stop the rest. Never write a whole page into a text property.
Honest limits
Where the documents and the code disagree.
Working components sometimes pass arguments that the published type definitions do not show. Here is every case we found. When you write new code, prefer the documented form.
updateFieldValue
DocumentedThe documented option is skipDirtyValidation.
In practiceWorking code passes skipDirtyCheck, which is probably ignored (inferred). Use the documented name.
refreshCaseView
DocumentedIt takes four values: case id, view id, page reference and options.
In practiceSome code calls it with none. That is unverified. Use the full form.
showPage
DocumentedThe options are { containerName, skipSemanticUrl }.
In practiceWorking code also passes a context. It is accepted at run time, but it is not the documented shape.
openLocalAction
DocumentedTwo arguments: the action id, then the options.
In practiceOne component passes a single object. It is unclear whether that is deliberate. Use two arguments.
getLocalizationService
DocumentedOne argument.
In practiceWorking code passes two, so TypeScript needs a suppression comment.
Next: the pattern catalogue shows these calls at work inside whole components.
Your turn
Questions and comments
Stuck on something, or have a thought? Write it here. To talk about one part, use the Comment button under that section's heading.