Question
Sytel Reply
IT
Last activity: 2 Jan 2025 11:37 EST
Constellation DX Components - How to add custom element in Constellation
Hi, I've some questions about Constellation DX Components, expecially its possibilty to be extended with custom component. I know, for example, that buttons are not OOTB component. Since I know that I can create my onw component I want to leverage Constellation. But I have some question:
- How can I retrieve my Constellation.js in order to edit it in local with javascript editor?
- Where can I find which component I can add and what are my limitations?
- If I use DX API V2, in order to represent a non-Pega UI, can I leverage my custom Constellation DX Component in those APIs in order to show them even in non-Pega UI?
- How can I set action in my custom component? I know is a Tradional UI way of thinking, but since I want to learn how to use Constellation architecture, I'd like also to know which step must be taken to change the mindset.
- Does exists any tutorial that show how to add a custom component for Constellation architecture?
- Let's say that I want to create a component that even on Traditional UI do not exists (like a fingerprint reader). How can I do it? It's a set of simplier component? Or I can design it in javascript?
Thanks to anyone will answer those questions.
Accepted Solution
Updated: 28 Jul 2024 10:28 EDT
Pegasystems Inc.
GB
Have you had a look at the Constellation DX components documentation?
I think that most of your questions are covered here, so if you haven't already I would suggest starting there. I have tried to start answering your specific questions below but to avoid repeating / copying what is already in the published documentation I have tried to be brief and direct you to what I think are the most relevant docs. Let us know if there is something that you can't find.
Components are created and developed locally using DX Component Builder, before being published to a Pega application. DXCB will create the starting component code of the selected component type. More information on getting your development environment setup can be discovered in the Initializing a project documentation.
Have you had a look at the Constellation DX components documentation?
I think that most of your questions are covered here, so if you haven't already I would suggest starting there. I have tried to start answering your specific questions below but to avoid repeating / copying what is already in the published documentation I have tried to be brief and direct you to what I think are the most relevant docs. Let us know if there is something that you can't find.
Components are created and developed locally using DX Component Builder, before being published to a Pega application. DXCB will create the starting component code of the selected component type. More information on getting your development environment setup can be discovered in the Initializing a project documentation.
DX Components can be of the types Field, Widget, or Layout template. You can read more in the How do Constellation DX components work article. As for the possibilities you can see an ever growing library of example components in the Constellation DX Components UI Gallery.
Actions in DX Components are achieved through Working with PCore and PConnect public APIs
There are some Constellation DX component tutorials available that walk through creating a component of each of the types mentioned above. As discussed in these docs DX Components are build using front end development technologies such as JavaScript/Typescript, VS Code, Git, Webpack, NodeJS, and NPM.
Regarding your question (2) there are various options for extending Constellation UI from the low code Constellation Portals, through DX Components, and with custom UI using either the Constellation SDKs or DX API directly. There is an overview of the options in the Extending Constellation UI options | Pega Academy module which is part of the larger Constellation Adoption | Pega Academy mission.
Overview of Constellation SDKs (pega.com)
Pega Digital Experience (DX) API Overview
Sytel Reply
IT
Thank you very much, @Marc Alderman. Those links were what I was looking for. For now I just gave a quick glance. Yet I have a question about this link Initializing a project, because I'm not familiar with those frameworks. This command
npx @pega/custom-dx-components@~24.1 init.
How should it work? It say to open a local prompt. But shouldn't be connected to the Pega Environment where is stored? Either on Cloud than on premise? Is there some pre-set that I missed? Or this command allow to work on external js package and download it on a repository, like git? By the way, I'm working on Infinity '23, so I assume that this work fine if I change the command in
npx @pega/custom-dx-components@~23 init.
Am I right? Thanks again for your kind response and for all links. Have a nice day!
Pegasystems Inc.
GB
At this stage I assume you are investigating the available options for Constellation rather than looking to develop a specific component. Before you decide to use a DX Component be sure to consider if you actually need to. Have a look at this other discussion about adding a custom button for example. You may find that the outcome you are trying to achieve can be built using OOTB Constellation features and design patterns.
How to Add a customized button in Pega constellation? | Support Center
As noted in the DX Component docs these are intended only for professional front-end developers in advanced use cases where out-of-the-box components do not meet the users' needs.
To your actual question, as you have mentioned, For Infinity 23 version you should use the aligned version of DXCB, so yes your project initialization command is correct.
At this stage I assume you are investigating the available options for Constellation rather than looking to develop a specific component. Before you decide to use a DX Component be sure to consider if you actually need to. Have a look at this other discussion about adding a custom button for example. You may find that the outcome you are trying to achieve can be built using OOTB Constellation features and design patterns.
How to Add a customized button in Pega constellation? | Support Center
As noted in the DX Component docs these are intended only for professional front-end developers in advanced use cases where out-of-the-box components do not meet the users' needs.
To your actual question, as you have mentioned, For Infinity 23 version you should use the aligned version of DXCB, so yes your project initialization command is correct.
DX Components are created and maintained in a local project. The initial project creation does not need a connection to a Pega environment. The component can be developed and tested locally in Storybook. It is only necessary to connect to a Pega Environment at a later stage when your component is ready to be published to the application for testing. The docs contain a flow diagram showing the Workflow of a Constellation DX component broken down into stages which I hope makes this clearer.
Publishing to an Pega application requires authenticating Pega Infinity Server user access using the command.
npm run authenticate
With this completed you are then able to use the commands to publish components to the Pega application.
Sytel Reply
IT
@Marc Alderman Thanks again.Your responses were precious. Your right, I'm investigating about the possbility to use a custom component, instead of a OOTB one, provided from Constellation architecture, in order to understand how far I can customize my projects.
Nevertheless I have another question. Now I better understood the power of DXCB and how to use it, in a pratical way. I get that the design of new component should be done by an FE specialist. Now let's say that I have my own component. How can I associate the relative action. I've started to read the link on PCore and PConnect. But my doubt is: where I configure the correlation between component and action. Let's say, just to have an example, that I have a button to perform a finish assignment. So let's assume now that the FE specialist managed to designed a new button in a local project using DXCB. Now, how can he associate the right action to the new button? Let's say that using PConnect, he designed this action (example taken by documentation of PConnec).
@Marc Alderman Thanks again.Your responses were precious. Your right, I'm investigating about the possbility to use a custom component, instead of a OOTB one, provided from Constellation architecture, in order to understand how far I can customize my projects.
Nevertheless I have another question. Now I better understood the power of DXCB and how to use it, in a pratical way. I get that the design of new component should be done by an FE specialist. Now let's say that I have my own component. How can I associate the relative action. I've started to read the link on PCore and PConnect. But my doubt is: where I configure the correlation between component and action. Let's say, just to have an example, that I have a button to perform a finish assignment. So let's assume now that the FE specialist managed to designed a new button in a local project using DXCB. Now, how can he associate the right action to the new button? Let's say that using PConnect, he designed this action (example taken by documentation of PConnec).
const finishAssignmentPromise = getPConnect().getActionsApi().finishAssignment("app/primary_1/workarea_1");
finishAssignmentPromise.then(() => {
// finish assignment success handling
}).catch(() => {
// finish assignment failure handling
});
The code above will be integrated in the DXCB project? Or the use of this APIs must be done in other project or other file that I have missed? The connection component - action is 1:1 or I can create an action and decide on Pega App studio how to connect a specifiic action to a custom DX component? Thanks again for your help, I really appreciate your support. Have a nice day
Pegasystems Inc.
GB
Constellation DX Components - How to add custom element in Constellation | Support Center (pega.com)
The actions for a component are built directly into the component itself making use of the PCore and PConnect public APIs in the component ReactJS code. In App Studio authoring, you do not have the option to assign different actions to components. As you say in your question it more like a 1:1 mapping of component - actions.
A developer can expose configuration options for the component that will be available in the properties pane for the component in App Studio. For example for OOTB components like a text input you will see configurations such as Edit Mode that can be set to Editable, Read-only, or Auto using a drop down menu, or the label for the field. This UI authoring experience for a component is driven by the config.json file that is generated as part of the component code by DXCB. There is some more information about this in the Component definition documentation.
Constellation DX Components - How to add custom element in Constellation | Support Center (pega.com)
The actions for a component are built directly into the component itself making use of the PCore and PConnect public APIs in the component ReactJS code. In App Studio authoring, you do not have the option to assign different actions to components. As you say in your question it more like a 1:1 mapping of component - actions.
A developer can expose configuration options for the component that will be available in the properties pane for the component in App Studio. For example for OOTB components like a text input you will see configurations such as Edit Mode that can be set to Editable, Read-only, or Auto using a drop down menu, or the label for the field. This UI authoring experience for a component is driven by the config.json file that is generated as part of the component code by DXCB. There is some more information about this in the Component definition documentation.
It sounds like you are looking for something along the same lines as Action Sets from traditional UI where you can pick and choose different actions and assign those actions to a UI control at design time. This is not possible in constellation by design. Actions sets can lead to complex custom configuration that is difficult to maintain (and support!). The goal is to enable you to achieve your desired outcome using existing workflows, patterns and components provided by Constellation, and for you to only need to choose a DX Component in rare cases when there is a more advanced, or highly customized use case. Of course, following a prescribed UI approach such as Constellation means that you can't always achieve the UI exactly as you imagine it, but it does mean you benefit from consistent design, improved usability, faster development times, and adherence to best practices in accessibility and user experience.
I'm linking a blog post and some previous discussions below that are relevant here:
Goodbye to action sets in Cosmos React? Yes, but for good reason. | Pega
how to configure Actions set in constellation | Support Center (pega.com)
Action sets in Pega Constellation | Support Center
Updated: 10 Jul 2024 3:30 EDT
Sytel Reply
IT
@Marc Alderman I must thank you again.
So, as I supposed, if I have 10 button which each one a different action, I have to create 10 button each one with different action, even if the graphical experience is the same.
I have another question about actions: I'd like to understand how component can bind with rule on Pega. Let's say that Customer ask a button that make a run time computation, that only an Activity or a Data Transform can perform. How can I accomplish this requirement? Since button are not OOTB I should create it with DXCB, and so I have to connect an Action (with PConnect API I suppose, since I need to know my context). Yet I'm not able to find anything to accomplish this. I think I'm losing something. But it's also a chance to understand better the bonding between Custom DX Component and the PRPC.
Anyway I'm exploring the Constellation architecture opportunities in order to understand better how to implement very specific CX requirement that in Traditional Architecture we would have created in the usual way. I understand the advantage of configuration above customization. Yet, since for your admission, you cannot cover all the possible business experience (that would be impossible!) I'm exploring way to use Custom DX Component, that, before your kind answers, was not too clear in my mind.
@Marc Alderman I must thank you again.
So, as I supposed, if I have 10 button which each one a different action, I have to create 10 button each one with different action, even if the graphical experience is the same.
I have another question about actions: I'd like to understand how component can bind with rule on Pega. Let's say that Customer ask a button that make a run time computation, that only an Activity or a Data Transform can perform. How can I accomplish this requirement? Since button are not OOTB I should create it with DXCB, and so I have to connect an Action (with PConnect API I suppose, since I need to know my context). Yet I'm not able to find anything to accomplish this. I think I'm losing something. But it's also a chance to understand better the bonding between Custom DX Component and the PRPC.
Anyway I'm exploring the Constellation architecture opportunities in order to understand better how to implement very specific CX requirement that in Traditional Architecture we would have created in the usual way. I understand the advantage of configuration above customization. Yet, since for your admission, you cannot cover all the possible business experience (that would be impossible!) I'm exploring way to use Custom DX Component, that, before your kind answers, was not too clear in my mind.
Of course, like you suggested, we would prioritize the use of the OOTB Components.
Thank you very much for your patience and your kindness. Best regards
Updated: 8 Jul 2024 6:03 EDT
Pegasystems Inc.
GB
Let's say that Customer ask a button that make a run time computation, that only an Activity or a Data Transform can perform. How can I accomplish this requirement?
This is not really a requirement. This is a customer asking for a specific technical implementation. Again, take a look at the discussion How to Add a customized button in Pega constellation. Here we should push back and ask *WHY* does it need a button? What is the business outcome that customer wants to achieve? It is very likely that you will be able to achieve most outcomes via a center-out approach (configuring the outcomes you need with App Studio, not in UI).
As an example, rather than a custom button to execute a data transform and refresh the UI we can configure form refresh settings that will call a data transform when a particular field changes to, for example, support conditional suggested values based on user entry. See: Configuring dynamic field behavior (pega.com)
Let's say that Customer ask a button that make a run time computation, that only an Activity or a Data Transform can perform. How can I accomplish this requirement?
This is not really a requirement. This is a customer asking for a specific technical implementation. Again, take a look at the discussion How to Add a customized button in Pega constellation. Here we should push back and ask *WHY* does it need a button? What is the business outcome that customer wants to achieve? It is very likely that you will be able to achieve most outcomes via a center-out approach (configuring the outcomes you need with App Studio, not in UI).
As an example, rather than a custom button to execute a data transform and refresh the UI we can configure form refresh settings that will call a data transform when a particular field changes to, for example, support conditional suggested values based on user entry. See: Configuring dynamic field behavior (pega.com)
The intention is that each DX Component would address a particular use case. In theory, a developer could create a configurable button with different actions that can be enabled/disabled via the property panel in App Studio using the config.json to expose these configurations that they then build into their component code.
However, if you find that you need 10 different buttons, I would humbly suggest that the design of the application is likely too complex and should be reevaluated. A DX Component should generally be the exception rather than the rule. Simplifying the design to take advantage of OOTB patterns and letting Constellation generate the experience for you as much as possible will reduce maintenance challenges that can be introduced by large amounts of customization, and give a more consistent and intuitive user experience with Accessibility and Front-end best practices built in.
Sytel Reply
IT
@Marc Alderman I see your point. And you're right. I also though that something I stated would be achievable with a refresh upon a change of a variable. I understood that I should not mix Views with logic, in order to adhere to centre-out approach. Mine was just an extreme case. But It could happen that customer wants a button for their own reason.
So again: how can I bind to a custom DX Component an activity or a Data transform created on Pega environment?
Thanks again for all your kind support and for helping me to improve on this new architecture.
Pegasystems Inc.
GB
You can't directly trigger an activity or data transform from a DX Component. Look at when this activity / data transform is required to execute an see how you can build this into the application using the constellation design patterns. For example, the dynamic field behavior mentioned above, or using activity / data transform pre / post-processing for a Flow Action (pega.com), or using a Data Transform automation automation step in the case lifecycle.
In your component you make use of the PCore / PConnect APIs to get access to state management, actions, events etc. For example you can use the APIs in the ActionsApi class to take actions.
You can't directly trigger an activity or data transform from a DX Component. Look at when this activity / data transform is required to execute an see how you can build this into the application using the constellation design patterns. For example, the dynamic field behavior mentioned above, or using activity / data transform pre / post-processing for a Flow Action (pega.com), or using a Data Transform automation automation step in the case lifecycle.
In your component you make use of the PCore / PConnect APIs to get access to state management, actions, events etc. For example you can use the APIs in the ActionsApi class to take actions.
If you want to get hold of some data and manipulate it with a data transform or activity then you could for example use a data page and have it load from an activity, or provide a post processing data transform rule to manipulate the properties on the data page as required to meet your usage needs. You could further manipulate the data as needed in the DX component itself.
Sytel Reply
IT
@Marc Alderman Thanks a lot for all your kind support. Now I better understand the use of DXCB and constellation. Thanks
ING
NL
I've a question creating the custom DX component in framework application
Do you have any document, how to create and add the component in fw
we are using cs fw.
Thanks
UM
