Chapter 16
The Pega API
Sooner or later your button needs to do something real: open a form, fetch a list, close a case. Here is how a component asks Pega for things, one piece at a time.
Pega 24 – 26
Words you will meet
- PConnect
- PCore
- getData
The first rule
Your component lives behind glass.
Picture the component as a shop assistant standing behind a glass wall. It can see the customer (the screen) and it can pass notes through a slot. It never walks into the stockroom, which is the Pega server, and fetches things itself.
In practice: a component never calls the server directly. No fetch, no axios. It asks PCorePega’s client-side runtime. A global object created when the page loads. It holds the data store and talks to the server for you. or its own PConnectA personal handle into Pega that each component receives. It knows which case, screen and container the component lives in., and they add the sign-in, the right case, caching and error handling.
The cast
Four things in every component.
Open the tabs in order: what you are handed, then your handle, then the things you can do, then the wider services.
What Pega hands your component. Your config.json settings, plus a few runtime values.
- Your settings
- Every entry in config.json properties arrives as a prop of the same name.
- value, label, disabled, readOnly, required
- Field components get these from the property the author bound the field to.
- testId, helperText, validatemessage
- Extras for testing and messages on fields.
- children
- Templates get one child per region (CONTENTPICKER), in declared order.
- getPConnect
- A function returning this component’s handle into Pega. Call it inside handlers.
Play
When you need something.
You rarely read API lists top to bottom. You arrive with a need. Pick yours and see the exact call.
PConnect · needs: Nothing extra
pConn.getValue('.Name')
const name = pConn.getValue('.CustomerName');Takes a property reference. The leading dot means “on the current page”.
The most common request
Asking for rows.
Most real components show a list. Lists come from a data pageA server-side, parameterised, cacheable data source. Think of a GET endpoint with query values, defined inside Pega. By convention its name starts with D_.. You ask for one with getData, and what you put in the payload decides what comes back.
const res = await PCore.getDataApiUtils().getData( 'D_CustomerList', { dataViewParameters: { Region: 'North' }, }, pConn.getContextName(),);The payload can also carry a query (filter, sort, select). Rows come back at response.data.data.
Put it together
One click, end to end.
A designer drops your component on a view and fills in its settings. Those are saved as view metadata, plain JSON. When a person opens the case, Constellation reads that metadata, finds your registered component, builds its props from the saved settings and renders it. The person clicks. Your handler runs, and this is the whole story in four lines:
async function onClick() { const pConn = getPConnect(); // 1. get my handle const PCore = window.PCore; // 2. the global services (may be missing in tests) const ctx = pConn.getContextName(); // 3. which case am I in? await PCore?.getDataApiUtils?.()?.getData('D_SomeList', {}, ctx); // 4. ask, never fetch}Next: the habits that repeat across a whole library of 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.