Hello,

In our first Pega post, we will introduce to Pega Web Mashup, which will increase the accessibility of our Pega applications. Of course, we need a Pega application and case type as a prerequisite.

Therefore, first, we will create a simple Pega application on App Studio, which has increased capabilities with Pega Infinity and focus on step-by-step case design, data modeling, and UI design according to our scenario. In addition to being a resource for Pega Web Mashup, this app can also be a starting point for the use of responsive UI design, screen actions, templates, and themes. It will also be used for our future posts.

In the second part, we will use Pega Web Mashup to create a mashup that embeds our Pega Platform application in another web application/pages. With Preview Mode on Case Designer, we will simulate how our app can look on an existing web page and generate the mashup code.

Let’s start by creating an application…

1. Create a New Application

1.1. Scenario

Create a new application in Dev Studio and configure two operators:

Application name:

  • MyApp

Operator IDs

  • admin@myapp will be the administrator.
  • author@myapp will be the author.

Change the security policies for the newly created users.

1.2. Credentials

  • Log in to Pega Platform 8.x with your predefined operator that created for you.

1.3. Create an Application Using Dev Studio

  1. Access the Pega Platform login page 
  2. Log in with your operator.
  3. On the top of the screen, click on Application: Pega Platform / New Application

  1. Select the custom type

  1. Click on Use this application type
  2. Click on Advanced configuration
  3. Fill in the form as follow:
    • Application ID: MyApp
    • Organization name: UICo

  1. Click on save
  2. Click on Create application
  3. Add two users:
    • admin@myapp / Administrator
    • author@myapp / Author
  4. Done

1.4. Change security policy for new users

  1. On the left-hand side, click on the Records icon to display the records explorer
  2. Expand Organization / Operator ID
  3. Select admin@myapp from the list
  4. Go to the security tab and uncheck Force password change on next login
  5. Click on Update password and type in: rules
  6. Click on Save

  1. Repeat the steps for author@myapp
  2. From the bottom left-hand side, log off

2. Create a case type in App Studio

2.1. Scenario

Create a new case type to handle car insurance policy quotes.

Create the data types used by the case type first then create the case type with the views associated with it.

Create two data types:

  • Person
  • Car

Create a case type:

  • Car Insurance

The data model will ultimately look like the following:

  • Client
    • First Name
    • Last Name
    • Date of Birth
    • Marital Status
    • Spouse – (Person)
      • First name
      • Last name
      • Date of Birth
      • Age
    • Children – (List of Person)
      • First name
      • Last name
      • Date of Birth
      • Age
    • Car – (Car)
      • Make
      • Model
      • Colour
      • Fuel type
      • Year
      • Millage
    • Address – (Data-Address)
      • Street
      • Postcode
      • City
      • Country

2.2. Credentials

  • Log in as author@myapp / rules

2.3. Create the Person, Car and Address data types

  1. From the left-hand side click on the Data icon
  2. Click on Data types
  3. From the top right-hand side click on New
    • Data type name: Person
    • Define data source: Later
    • Submit
  4. Add fields
    • First Name: Text
    • Last Name: Text
    • Date of Birth: Date only
    • Age: integer
      • Click on the gear icon and make the property to be automatically calculated
      • Custom function
      • @DateTimeDifference(.DateOfBirth+"T000000.000",@CurrentDateTime(),"Y")

Note: If you are not familiar with configuring a view from a case life cycle, this video may help: How to configure a view from a case lifecycle

  1. Click on Views and create a new view
  2. After expanding the Fields section (on the left) we can add fields to the view by clicking on each field in the list.
    • Add the four properties just created 
    • Name the view “Person Details”

  1. Submit and Save
  2. Add a new Data type
    • Data type name: Car
    • Define data source: Later
    • Submit
  3. Go to the Views tab in order to create a UI form and the fields that don’t exist yet

Note: We could define the data model first and then reuse it when creating the views or let Pega create the fields on the fly for us. 

  1. Create a new view
    • Make – Text
    • Model – Text
    • Colour – Text
    • Fuel type – Picklist [Petrol, Diesel, Hybrid, Electric]
    • Year – Text
    • Millage – Integer
    • Overall Condition – Integer
    • Mpg – Decimal

Figure-6: Car Data Type
  1. Submit and save
  2. Click on the Data Model tab, all the properties have been created
  3. Add the Address data type
  4. Create a default view Address Details
    • Street – Text
    • Postcode – Text
    • City – Text
    • Country – Text
  5. Submit

2.4. Create the Car Insurance case type

  1. From the left-hand side click on the Case types icon
  2. Click on New
  3. Name the case type “Car Insurance”
  4. Click Next
  5. Click on the Workflow tab then Add life cycle
  6. Add a stage and four steps as follow
  7. Hover your mouse over the stage and add a new Review Details process
    • Name: Review Details
    • Add a new Collect Information step named:  Review Details
  8. Save

  1. Click on the Data model tab
  2. Add a field
    • Name: Client
    • Type: Field group
    • Options: Client (Data type)
    • Click anywhere else on the form to post the changes
  3. Click on Save
  4. Click on the Client link
  5. Add fields
    • First Name – Text
    • Last Name – Text
    • Date of Birth – Date only
    • Marital Status – Picklist [Single, Married, Divorced]
    • Spouse – Person
    • Children – List of Person
    • Car – Car
    • Address – Address

Note: A field group means a single page which is an instance of a class.
A field group (list) means a page list which is a list of instances of a class, such as List()
A Data Reference means that the wizard will use an existing Data Type (Sourced data class with Data Pages) to create: 

  • A lookup control (dropdown or autocomplete) in order to select one particular entry for the data type 
  • A form based on a field group (page) that references this unique data type entry and displays it using the form reused or generated.

Data referencing allows user to quickly render the selection of one entry of the data type and dynamically display/refresh the content of this entry which is referenced by a page. 

2.5. Create the Car Insurance UI

  1. Return to the case type life cycle
  2. Configure the views for the first step of the case
    • Select Client
    • Click Configure View
    • Create a new view: Client Details
      • Delete all fields
      • Add a field: Has Children – Boolean
      • Add Children
      • Remove the Age
      • Submit and Save
    • Reconfigure the view
    • For Client, select Create new view: Client Info
      • Remove Has Children
      • Submit and Save
    • Reconfigure the view
    • For Client, select Create new view: Client Spouse Container
      • Delete all fields
      • Add Spouse and use the Person Details view
      • Submit and Save
    • Reconfigure the view
    • For Client, select Create new view: Client Details
    • Submit and save
  3. Verify your work and click on Views

 

Figure-9: Client Details
Figure-10: Client Info
  • Client Spouse Container
Figure-11: Client Spouse Container
  1. Organize the views you have just created
    • Click on Save and run
    • Click on Done
    • Hover your mouse over the view
    • Click on Configure view with the pencil icon (in orange in the right corner)
    • On the right panel, hover your mouse over the Client Details section and click on the pencil
    • Click the + for the A column
    • Add Client Spouse Container and click on X
    • Drag and drop the section at the very top of Client Details
    • Click on the pencil for Client Spouse Container
    • Add the Client Info section
    • Drag and drop it at the top
    • Submit and Save
  2. Verify your work and run a case
Figure-12: First UI for Client 
  1. Configure the view for the second step
    • Select Client
    • Create a new view: Car Details
    • Delete all the properties and add Car
    • Select Car Details
    • Submit and save
  2. Configure the view for the third step
    • Select Client
    • Create a new view: Address Details
    • Delete all the properties and add Address
    • Select Address Details
    • Submit and save
  3. For the Review Details step
    • Add the Collect Client Details View
    • Add the Collect Car Details view
    • Add the Collect Address Details view
    • Make them all Read-only
    • Remove the empty field
Figure-13: First UI for Car
Figure-14: First UI for Address
Figure-15: First UI for Review

3. Make the UI dynamic

3.1. Scenario

The first draft of UI is only using stacked templates and we want to change the appearance of the UI and give it a modern look & feel.

  • Remove the Age from the Children and Spouse UI. This should only appear in the Review Details view.
  • Display the spouse information only when the client is “Married”
  • Change the marital Status to use Radio buttons
  • Display the Children table only when the client “Has Children” 
  • Use a Slider for the Overall Condition of the Car
  • Hide Mpg when the Car is Electric 
  • Use a country picklist for the country of the Address

3.2. Credentials

• Log in as author@myapp / rules

3.3. Client UI

  1. Run a case
  2. On the top right-hand side of the UI click on Configure this view
Figure-16: Client View Configuration
  1. On the right-hand side click on Client Details – pencil
  2. Click on Client Spouse Container – pencil
  3. Click on Person Details (pencil) to edit the Spouse section
  4. At the top, click on Settings
  5. On the Visibility part select
    • Condition (Expression)
    • .MaritalStatus='Married'
    • Apply
    • Click the X to get back twice
  6. Click on Children pencil 
  7. At the top, click on Settings
  8. On the Visibility part select
    • Condition (Expression)
    • .HasChildren
    • Apply
    • Click the X to get back
    • Hover the mouse over the Children and select Modify this list
    • Put the Date of Birth at the bottom
  9. Click the X to get back
  10. Navigate back to Person Details
    • Select Married for the Marital Status so the section appears and is modifiable
    • Client Details
    • Client Spouse Container
    • Person Details
    • Click on the Age – pencil
      • Visibility: Condition (Expression)
      • Condition: .DateOfBirth!='' (these are 2 single quotes)
    • Click on Date of Birth – pencil
      • Add action sets
      • Add an event : Change
      • Add an action: Diplay: Refresh
      • Ok, Apply and click on the X twice
  11. Try the result by running a new case or refreshing the current one

Client Final Result

  1. Lite Version
Figure-17: Client Lite Version
  1. Full Version
Figure-18: Client Full Version

3.4. Car UI

  1. Change the visibility of the MPG field to be hidden when the Car fuel type is Electric
    • Use previously learned knowledge to perform this task 
    • Delete Colour
    • Move up the MPG to be just below Fuel Type
  2. Change the Overall Condition to use a slider control
    • From the Car Details section settings, delete the Overall Condition field using the 3 dots at the far right
    • Click on the + above and add a Slider control and then click on the X
    • Edit the Slider field as following
Figure-19: Slider Control Configuration

Car Final Result

Figure-20: Car UI

3.5. Address UI

  1. Change Country to be a picklist
    • Open the Address data type
    • Double click on Country
    • Click on the Change link and select Picklist
    • Save
    • Go to the Views tab and open the Address Details
    • Click on the cog
    • Select Autocomplete
    • Add countries :
      • Turkey
    • Submit and save

Address Final Result

Figure-21: Address UI

3.6. Review Details UI

  1. Change the Read-Only format of the Has Children checkbox
Figure-22: Checkbox Configuration
  1. You can search for: “checked” and “error” to find the images to associate with the value of the field

You can see the final result by running the case.

4. Change the UI Templates

4.1. Scenario

Time to change the overall display of the version sections using design templates.
We will finish off the design of the different views by ensuring all fields are rendered correctly for when both editable and read-only.

4.2. Credentials

  • Log in as author@myapp / rules

4.3. Client UI

  1. Select Married as of the Marital Status so then you can see the Spouse section when modifying the UI
  2. Check Has Children as well
  3. Click on Configure this view
  4. Open Client Details
  5. Open Client Spouse Container
    • Change the design template to 2 column
    • Drag the Person Details to the B column
  6. Open the Client Details and click on Settings
    • Remove the header
  7. Open the Client Info and click on Settings
    • Add a header “Client”
Figure-23: Client UI with column template 

4.4. Car UI

  1. Use previously learned knowledge to perform this task
  2. Change the of Car Details Template to be 2 Column (Inline Wrapping)
  3. Ensure the layout do not change when selecting Electric for Fuel type
  4. Get rid of the Client header
Figure-24: Car UI with column template 

4.5. Address UI

  1. Use previously learned knowledge to perform this task
  2. Change the of Address Details Template to be 2 Column
  3. Get rid of the Client header
Figure-25: Address UI with column template 

4.6. Review Details UI

Make sure all the numbers are displayed on the left when read-only

5. Change the UI Theme

5.1. Scenario

Time to play with themes and change the branding of the application.

This exercise let you be inventive in terms of color used

5.2. Credentials

  • Log in as author@myapp / rules

5.3. Play with the Themes

  1. On the left-hand side, click on Settings
  2. Click on Theme
  3. Check the name of the application
  4. Change the logo
  5. Change the default theme with the values you wish to style your application
Figure-26: Application Theme

After that, you can back to the portal or case and see the effect of the changes.

Before starting the Pega Web Mashup, this application will suffice for now. If you wish, you can enrich it with alternative scenarios and steps.


6. What is Mashup in the industry?

A mashup (computer industry jargon), in web development, is a web page or web application that uses content from more than one source to create a single new service displayed in a single graphical interface. Mashups are made possible via Web services or public APIs that (generally) allow free access. Most mashups are visual and interactive in nature.

7. Pega Web Mashup

Pega Web Mashup enables us to embed a Pega application within a web page or other web applications on your intranet or internet site. You create a Pega Web Mashup directly in App Studio or Dev Studio and deploy it to leverage the security and user interface features of the Pega Platform™.

Mashups generated by Pega Web Mashup provide the same rich application experience users normally have in a Pega Platform application. Common actions that can be defined inside a mashup include:

  • Opening a new case
  • Displaying a user’s worklist
  • Selecting and performing an assignment

The Generate Mashup code option opens a window that provides the necessary HTML for you to copy, paste, and view within the web page. You can modify the code to meet the specific needs of the web page or to customize the appearance of the mashup, for example, setting the width of the mashup.

Pega Web Mashup code is HTML5-compliant. The application can communicate with the host page where the mashup code is embedded, and host pages can communicate actions back to the Pega Platform application as well.

When a Pega Web Mashup displays a Pega application, the application starts by calling a flow or a harness. Anything that you can display in a harness is visible in the web mashup application, including access worklists and reports.

8. Using Mashup to expose a case type

8.1. Scenario

In our application for Car Insurance, we want to quickly expose our Service Request case type to customers through Web Self-Service (WSS) by using Pega Mashup.

Create a Mashup channel interface and expose this Mashup through a web HTML page.

8.2. Credentials

  • Pega: author@myapp / rules

8.3. Use Mashup preview in App Studio

  1. In the left navigation panel of App Studio, click Interfaces and then Mashup to create a new Mashup channel interface.
  2. Populate the form as follow:
    • Name: Car Insurance
    • Description: Create a new Car Insurance
    • URL: Leave it as is
    • Action: Leave it as is
    • Case type: Car Insurance
    • Flow name: pyStartCase
    • Thread name: Leave it as it is
    • Skin: Leave it as it is
  3. Close the form
  4. In the upper right, click Save to persist the new interface.
  5. Under “What is a Mashup?” click “Generate mashup code”.

Note: pyStartCase is the default flow name Pega uses to create any case. 

According to the configuration, the mashup code will occur in the relevant field.

Figure-27: Mashup Interface
<!-- ********************** Begin Pega content ********************** -->
<script src ='https://paex21-use.pegacloud.io/prweb/?pyActivity=pzIncludeMashupScripts'></script>
<div data-pega-gadgetname ='PegaGadget' 
data-pega-action ='createNewWork' 
data-pega-action-param-classname ='UICo-MyApp-Work-CarInsurance' 
data-pega-action-param-flowname ='pyStartCase' 
data-pega-isdeferloaded ='false' 
data-pega-applicationname ='MyApp' 
data-pega-threadname ='STANDARD' 
data-pega-resizetype ='stretch' 
data-pega-url ='https://paex21-use.pegacloud.io/prweb/' 
data-pega-tenantid ='P_RES_C1225Ex21AM_264' 
data-pega-redirectguests ='true' ></div>

<!-- ********************** End Pega content ********************** -->

Our mashup code is ready to be embedded in a host website.

  1. Copy the mashup code, we will need it in the next posts.
  2. In the App Studio header, click Back to preview to return to the preview mode.
  3. Click the Case Manager menu in the App Studio header
  4. Select the new Car Insurance channel interface. The application renders the Mashup preview.
  5. Run the case.

Note: Mashup Interface can be configured with different actions such as display specific harness, open assignment, open work item, etc. However, when the action is changed, Mashup Code must be generated again.

9. Creating a mashup demo

9.1. Scenario

Now, we want to embed the mashup within the Pega Community (or any) website.

9.2. Credentials

  • Pega: author@myapp / rules

9.3. Previewing the mashup

  1. After you configure your mashup, use the preview function to see how it is displayed on a page.
  2. In the App Studio header, click Back to preview.
  3. In the App Studio header, next to the name of your application, expand the interfaces list, and then click Car Insurance.
  4. In the Preview mode field, select the Live website from the list.
  5. In the Website URL field, enter any URL (https://community.pega.com/)
  6. Turn on the Load in a popup toggle and click Apply.
Figure-28: Place Selection
  1. In the pop-up window, click the page to display wireframes, select a place, and click to insert your mashup.
Figure-29: Embedded Mashup

..and our application interface will appear within the website as in Figure-29.

10. Result

Thus, we created a Pega Web Mashup Interface on App Studio for our sample application and simulated how our application will look on a live web page. We will use the code we created in subsequent posts to embed it in the HTML code of our sample website. We will also focus on application permissions, authentication and mashup pitfalls.

References