Headless data with the DX API

Is it too easy to kick-off Pega workflows headlessly? This 110s LinkedIn video took more time to make than the scenario it explores, so maybe…

HeadlessDataAtHotelBeaumont20261021

Anyway: hard-coding forms so that they match up with complex workflow steps can fragment business logic and waste resources — even with agents. It’s generally better to have a single source of truth and work from the Center-out. Pega’s architecture makes that as easy as it could possibly be.

But sometimes our needs are really simple: a trivial case kick-off, displaying a bit of data, etc. The good news is that Center-out does “simple” really well too!

The video covers the “trivial case kick-off” use case. In this thread, I’ll provide a little more technical detail around that, along with the “displaying a bit of data” use case.

Trivial case kick-off

The heart of this scenario is the POST /cases endpoint. Once you’ve acquired an auth token (I’m using password credentials for this simple prototype), the front-end code is really quite basic. At the time of this writing, the heart of the logic is in pega-headless-data.tsx, lines 133-150:

const response = await fetch(
  `${serverUrl}/app/${encodeURIComponent(config.serverConfig.appAlias)}/api/application/v2/cases`,
  {
    method: "POST",
    headers: {
      Accept: "application/json",
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      caseTypeID: config.serverConfig.appMashupCaseType,
      content: {
        GuestFirstName: firstName,
        GuestLastName: lastName,
      },
    }),
  },
);

This builds a JSON payload like:

{
  "caseTypeID": "O8SZFS-LostProp-Work-LostPropertyRequest",
  "content": {
    "GuestFirstName": "Emma",
    "GuestLastName": "Thompson"
  }
}

And posts it to a url like:

https://my-pega-instance.com/prweb/app/lost-property/api/application/v2/cases

On the Pega Infinity side, the one thing to setup (beyond auth) is an AllowedStartingFields data transform. As the name implies, this specifies which fields are allowed for submission upon receiving a call to the POST /cases endpoint.

Where this is a good fit:

  • The number of fields that needs to be captured is relatively small and static.
  • The user doesn’t need to interact with the case after submission.
  • Business logic is not involved.

A use case with these characteristics should largely be a one-time setup, and rather straightforward at that — the scenario demonstrated in the video was handled by Copilot in minutes with just a bit of guidance. A small number of fields goes hand-in-hand with business logic not being involved, so we don’t have to worry about duplicating/fragmenting that logic across our front-end channels and our Pega Infinity workflows. And because the fields are more-or-less static — that is, they aren’t often changing in the underlying Infinity workflow — we don’t have to worry about constantly keeping changes in sync.

Where I would avoid this approach:

  • The number of fields that need to be captured is relatively large and changes often.
  • The workflow is complex, continuously-evolving, and requires multiple steps of involvement from the user.
  • Business logic is involved.

This is the flipside of the above scenario. If any of these characteristics apply, it’s time to consider other options like Web Embed.

Useful links:

Displaying a bit of data

The video doesn’t go into this since it’s really the same idea as the above scenario, only even simpler. The one wrinkle I want to discuss that sometimes trips people up is where to get the data — turning to the Cases and Assignments endpoints are usually not the right answer because they are mainly for interacting with those entities.

Usually you’re going to want to use one of the Data endpoints. In particular, GET /data_views/{data_view_ID} is very common.

There’s still the question of what {data_view_ID} you need to access the Pega data you want. Personally, 99% of the time I just search for D_ in the browser network tracer while navigating my Pega portal — it’s usually obvious which result is going to supply the data I’m looking for.

For instance, if I want to grab the data from my worklist, it’s plain to see that D_pyMyWorklist is the answer:


Where this is a good fit:

  • The data is small in size and accessing it doesn’t carry performance risks.
  • There are practical reasons why the user cannot access the data in the Pega portal.

If I were to take the video scenario further, I might show a list of the guest’s most recently submitted cases in the web app. This meets the two characteristics above and would be a fine use case.

Where I would avoid this approach:

  • The data is large enough that there are serious performance considerations.
  • So many different pieces of data are being accessed that it verges on re-inventing the Pega portal.

Useful links:

What else?

This is all very much off the top of my head. If there’s anything else you want to go into just let me know. Also, if you have any other tips-and-tricks along these lines I’d love to hear them!

Love it @peter_bessman! I have added it to our constellation 101 series.

Enjoyed this article?

See suggested articles from our Constellation 101 series and view all our Knowledge Shares from our User Experience Expert Circle.