@pega/custom-ui-components

Using Custom Components in Constellation

Overview

This project provides you with an environment to extend Constellation by giving you tools to create and publish custom components that are not available from the Constellation installation.

Prerequisites

Ensure you have access to the following in your system:

• Pega Infinity Server version 8.7 and above

• Git version 2.30 and above

• System node version 14 and above

• System npm version 6 and above

Initialize a project

Initialize the project by performing the following procedure in a terminal:

1. Enter the following commands to create a directory for your component and connect to the directory.

    mkdir <component_name>
    cd <component_name>
   

2. Enter the following command to initialize the project. npx @pega/custom-ui-components init

3. If prompted, enter y to install the Custom UI Components package. You will then be asked to set up the project by entering the required details.

4. Enter the following details:

   • Name of the project (required) Example - mycustomcomponents
   • Name of the organization (required) Example - customorg
   • Version (required) Example - 1.0.0
   • Description of the project (optional) Example - This project is intended to create and publish a custom component.
   • Git repository URL (optional) Example - https://git.custom-components.io/custom-cc.git
   • Author (optional) Example - Michelle

The workspace is now set up to create custom components and publish them to the server.

Create custom components

Create custom components using the following procedure:

1. Enter the following command to create a component: npm run create. You will then be asked to enter or review the following details of the component:

   • Name of the component (required) Example - customcomp0
   • Name of component label (required) Example - custom component
   • Name of the library (required) Example - basic
   • Component version (required) Example - 0.0.1
   • Type of component (required) Example - Field
   • Sub-type of component (required) Example - Text
   • Description of the component (optional) Example - This is a customized searchbox that filters data. The component is created in the following path: /Users/your_user_name/project_name/src/components/component_name You can also pre-configure the values for the above options in a tasks.config.json file as shown below.

   {
       "component": {
           "library": "basic",
           "type": "field",
           "subtype": "text",
           "description": "basic field for capturing textual data",
           "icon": "basic-field-text.svg"
       }
   }
   

   Note: Alternatively, you can enter the following command to skip entering the details of the component now and can manually enter the details in the config.json file after the component is created: npm run create <enter_component_name>

   A src/components folder is created and the necessary files required to build the component are initialized as seen below.

   ├── src
      ├── components
           ├── <component_name>
               ├── index.js
               ├── demo.stories.js
               ├── config.json
   

   The index.js file contains the actual component rendering logic. The demo.stories.js file contains the demo that can be viewed in the storybook. The config.json file contains the mapping of properties for configuring the auto generated property panel. This property panel appears in AppStudio when an application is being authored to use the custom component.

2. Enter the following command to start the storybook to view the demo. npm start

3. Modify the source files to build your own component. You can also install and import third-party libraries if required for your component.

The custom component is now created. We use the information provided to create uniquely namespaced components in this convention - <organization>_<library>_<component name>.

Authorize the user

Before we publish the custom component to the Pega Infinity Server, authorize the user to access the resources in the Pega Infinity Server.

Note: It is required that you configure a value for clientId, clientSecret, and accessTokenUri.

Get OAuth2 Credentials

1. Login to Pega Infinity Server

2. Navigate to Records / Security / OAuth 2.0 Client Registration landing page and open the PegaApp_<your_app_name> record.

3. Click Regenerate Client Secret

4. Download the Client Credentials (as the Client ID, Client Secret, and Access token endpoint will be needed)

5. Enable "Password credentials" checkbox and save the record.

6. Update the the the service-config object in the task.config.json file with these downloaded values

   "server-config": {
       "server": "https://127.0.0.1:8080/prweb",
       "user": "customcomponentoperator",
       "password": "pwd",
       "clientId": "<mention client ID here>",
       "clientSecret": "<mention client secret here>",
       "accessTokenUri": "https://127.0.0.1:8080/prweb/PRRestService/oauth2/v1/token"
   }
   

7. Enter the following command to initiate authorization. npm run authenticate

The user is now authorized and can proceed to either list or publish the components.

List custom components

View the available components in the local machine or the server.

Enter the following command to list custom components: npm run list

You will then be asked to enter the following details to set up the oauth 2.0 token:

• List components from Server or Local Example - Server
• Enter pega server url Example - https://127.0.0.1:8080/prweb
• Enter user ID Example - customcomponentoperator
• Enter password Example - pwd
• Enter clientId Example - <mention client ID here>
• Enter clientSecret Example - <mention client secret here>
• Enter accessTokenUri Example - https://127.0.0.1:8080/prweb/PRRestService/oauth2/v1/token

The custom components will now be listed in the terminal.

Publish custom components

Publish the finalized custom components changes to Pega Infinity Server so that it can be discoverable in view authoring.

Enter the following command to publish custom components to Pega Infinity Server: npm run publish. You will then be asked to enter the following details:

• The component to be published to Pega Infinity Server. It will be updated if the component exists.
• The server URL where the component must be published
• The client ID
• The client secret
• The access token URI
• The login ID of the Pega Infinity Server
• The password of the Pega Infinity Server
• The name of the ruleset where the component must be published
• The version of the ruleset where the component must be published
• Specify if the source map should be generated.

You can also pre-configure the values for the above options in a tasks.config.json file as shown below.

{
    "server-config": {
        "server": "http://127.0.0.1:8080/prweb",
        "user": "customcomponentoperator",
        "password": "pwd",
        "rulesetName": "TestPega-C11nGall",
        "rulesetVersion": "01-01-03",
        "sourceOfComponents": "Server",
        "devBuild": false,
    }
}

When the component is successfully published, you can use the newly published component in App Studio's view authoring.

Note: The Rule-UI-Component instance (with component name) is created on the Pega Infinity Server after publishing the component.

View existing custom components in storybook

View custom components in a storybook by performing the following procedure:

1. Enter the following command to open the project. cd <enter your project's name>

2. Enter the following command to start the storybook in development mode. npm start

The storybook is launched in a browser where you can view the components working in isolation.