Creating New Entities in PGP

From PegaWiki
This is the approved revision of this page, as well as being the most recent.
Jump to navigation Jump to search

Creating New Entities in PGP

Description Guide to adding a new entity to PGP
Version as of 8.5
Application Pega Government Platform
Capability/Industry Area Government



What are PGP Entities?[edit]

PGP Entities are a collection of robust data structures that model data elements commonly used in government processes. The PGP Entities are persistent data classes that come pre-configured as a part of PGP.

  • Person
  • Business
  • Vehicle
  • Facility
  • Household

Entity data structures serve two distinct purposes within PGP:

  1. Entity instances are persisted to a data store like any local data type or data table
  2. Entity data classes are used as a type for embedded pages defined on the PGP work ancestor to support case processing

Persistent Data Store[edit]

An entity data class (Data- class) is managed (curated) in an independent data store (database table) by the Add, Update, View and Search case types (Work- classes).

Case Type Embedded Page[edit]

An entity data class is also used as a type for embedded pages incorporated into the PGP work ancestor. These embedded pages are used by the PGP component processes to implement PGP features.

PGP Entities follow a pattern of Persistent Data curated by Business Processes. This pattern allows for the possibility that in a customer implementation the entity datastore may be mapped to customer resource that is external to Pega and PGP. In this pattern a persistent datastore descended from PegaPS-Data-Entity is added, updated, viewed, and searched by Case Types descended from PegaPS-Work-Entity.

New Entity Overview[edit]

This guide will step through the process of extending the PGP Entity data structure addding a new entity called Item built in a PGP implementation layer.

In the following examples PGPImp is the organization name of the implementation application and DemoPGP is the name of the implementation application. The class PGPImp-DemoPGP-Work inherits (directed) from the PegaPS-Work class.

Create the Persistent Datastore[edit]

  • PGPImp-DemoPGP-Data-Entity-Item
    • Properties relevant to the entity
    • View(s) for editing, reviewing
    • Data Pages for retrieving
    • Optional: Case match rule to avoid duplicates, and validation rules for data

Extend the Work Class Properties[edit]

  • In the primary work class of the implementation application, PGPImp-DemoPGP-Work, add a page property of type PGPImp-DemoPGP-Data-Entity-Item to hold Item data during case management processing.

Create the Data Management Case Types[edit]

  • PGPImp-DemoPGP-Work-Entity-Item-Add
  • PGPImp-DemoPGP-Work-Entity-Item-View
  • PGPImp-DemoPGP-Work-Entity-Item-Search
  • PGPImp-DemoPGP-Work-Entity-Item-Update

Enable for App Studio[edit]

  • Use views and design templates to construct the user interface
  • Catalog the new Entity’s rules in Relevant Records so they will appear in the App Studio smart prompts
  • Configure whether case types will appear on +Create nav

Development Steps[edit]

While it is possible to do some of this work in App Studio, the approach discussed here is based on a Dev Studio experience. App Studio hides some development details, like class names and rulesets, in order to present a development environment that can focus on case types and business processes, but for this exercise we need full control over those details.

Create Persistent Datastore[edit]

Create a persistent data type and supporting rules for the new entity.

Create Data Type Ancestor[edit]

Add an abstract data class to the implementation layer to leverage the Enterprise Class Structure pattern and provide extension points for reusable rules common to the Entity implementation layer data types.

  1. Use Create -> SysAdmin -> Class to create a new class
    1. For the Label use Entity
    2. For the Class Name use PGPImp-DemoPGP-Data-Entity
    3. Create and open
    4. For Select class type use Abstract
    5. For Created in version use the current version
    6. For Parent class (directed) use PegaPS-Data-Entity
  2. Save the rule

Create Data Type[edit]

  1. Use Data types –> Data types -> Add data type wizard to create the new Item data type and supporting rules.
    1. Set the Label as Item
    2. Add an appropriate Description for the class
    3. Under Advanced set the parent class to PGPImp-DemoPGP-Data-Entity
    4. Submit to create the new Item data type
  2. Configure the Item data type
    1. Use the Data model tab add properties to the Item data type
      1. EntityID of type Text
      2. pyID of type Text
      3. Add additional properties as needed …
    2. Under the Sources tab Create a local source
    3. Select pyID as the Key (Use as key)
    4. Submit to create a local source for the Item data type

Create View UI for the New Data Type[edit]

Build the basic data layer UI rules to present the data of the new Item data type.

  1. Create View ItemDetail with Applies-To of PGPImp-DemoPGP-Data-Entity-Item
    1. Place all the relevant properties from the Item data type
  2. Create View ItemDetailRO with Applies-To of PGPImp-DemoPGP-Data-Entity-Item
    1. Place all the relevant properties from the Item data type, with the Presentation -> Edit Options set to Read-Only

Extend the Work Ancestor Class[edit]

Add a Page property to the implementation layer work ancestor of type PGPImp-DemoPGP-Data-Entity-Item to hold an Item instance during case management processes. Create a new Page property .Item of type PGPImp-DemoPGP-Data-Entity-Item with Applies-To PGPImp-DemoPGP-Work.

  1. Use Create -> Data Model -> Property to add a new property
    1. For the Label use Item
    2. For the Apply to use PGPImp-DemoPGP-Work
    3. Create and open
    4. Change the Property type to Single Page
    5. Select PGPImp-DemoPGP-Data-Entity-Item as the Page definition
    6. Save the rule

Review Entity Data Type Rules[edit]

Switch to App Explorer (App) and show PGPImp-DemoPGP-Data-Entity-Item. Review all the rules created for the Item data entity.

Applies -to Rule Name Rule Type Description Comment
PGPImp-DemoPGP-Data-Entity Class Abstract
Item Data Type
PGPImp-DemoPGP-Data-Entity-Item Class Concrete Key pyID
PGPImp-DemoPGP-Data-Entity-Item Database Table Persistence
PGPImp-DemoPGP-Data-Entity-Item ItemName Property Text
PGPImp-DemoPGP-Data-Entity-Item … more properties Property Text
D_Item Data Page Page Source=Lookup
D_ItemList Data Page Page List Source=Report Definition
D_ItemSavable Data Page Page
PGPImp-DemoPGP-Data-Entity-Item DataTableEditorReport Report Definition All Item Properties

Create Case Types[edit]

Create Abstract Support Work Classes[edit]

When a new implementation layer is generated by the New Application Wizard it only creates descendants for the selected concrete classes.  Manually add the missing abstract work classes to leverage the Enterprise Class Structure pattern and provide extension points for reusable rules common to the Entity and Item implementation layer work types.

  1. Use Create -> SysAdmin -> Class to create a new class
    1. For the Label use Entity
    2. For the Class Name use PGPImp-DemoPGP-Work-Entity
    3. Create and open
    4. For Select class type use Abstract
    5. For Created in version use the current version
    6. For Parent class (directed) use PegaPS-Work-Entity
    7. Save the rule
  2. Use Create -> SysAdmin -> Class to create a new class
    1. For the Label use Entity Item
    2.  For the Class Name use PGPImp-DemoPGP-Work-Entity-Item
    3. Create and open
    4. For Select class type use Abstract
    5. For Created in version use the current version
    6. For Parent class (directed) use PGPImp-DemoPGP-Work-Entity
    7. Save the rule

Create Data Management Case Types[edit]

Use Case types -> +Add a case type to add new case types to the implementation layer. Use the Advanced Settings to select the directed and patterned ancestors for the new case type.

Choose the case type name carefully as it will be used to form the work class name for the case type. After the case type has been created, you may choose to change the pyLabel for the case type rule to something more specific.

The lists of ancestor classes to choose from may not show recently added abstract classes unless you have logged out since they were added or otherwise reset the cache.

Create the Add Case Type[edit]

In PGP the Add case type for Entities collects data from the operator in a Page embedded on the work class. At an appropriate step in the case life cycle a PGP Persist component is placed which writes out the data from the embedded page on the work to a persistent data class using the persistence configuration from the Database Table rule for the embedded page’s class.

  1. Use Case types -> +Add a case type to create a new case type named Add (plan to change the label for the case type rule later)
    1. Expand the Advanced section and specify the ancestry
    2. Use PGPImp-DemoPGP-Work-Entity-Item as the directed ancestor
    3. Use PGPImp-DemoPGP-Work-Entity-Item as the patterned ancestor
  2. Create a Workflow for the case type
  3. In the default Create stage
    1. Use +STEP to add a Collect Information step under the Create stage
    2. Name the step Capture Item Details
    3. From the step parameters panel (right) click Configure the View
      1.  In the View Configuration add the Item field as a field group
      2.   Select ItemDetail from the View dropdown to use it as the View for the Item field group
  4. Use +STAGE to add a new stage named Review
    1. Use +STEP to add a Collection Information step under the Review stage named Review Item Details
    2. From the step parameters panel (right) click Configure the View
      1. In the View Configuration add the Item field as a field group
      2. Select ItemDetailRO from the View dropdown to use it as the View for the Item field group
    3. Use +STEP -> …More -> Processes and select Persist object
    4. From the step parameters panel (right) configure the Persist object component
      1. For Type use Entity
      2. For Property use “.item” (double quotes are significant)
  5. Change the case type rule label for PGPImp-DemoPGP-Work-Entity-Item-Add from Add to Add item
  6. Save the Case

Create the Update Case Type[edit]

In PGP the Update case type for Entities solicits changes to the entity data from the operator and captures these changes in a Page or Page List embedded on the work class. At an appropriate step in the case life cycle a PGP Persist component is placed which writes out the data from the embedded page on the work to a persistent data class using the persistence configuration from the Database Table rule for the embedded page’s class.

  1. Use Case types -> +Add a case type to create a new case type named Update (plan to change the label for the case type rule later)
    1. Expand the Advanced section and specify the ancestry
      1. Use PGPImp-DemoPGP-Work-Entity-Item as the directed ancestor
      2. Use PGPImp-DemoPGP-Work-Entity-Item as the patterned ancestor
  2. Create a Workflow for the case type
  3. In the default Create stage
    1. Use +STEP to add a Collect Information step under the Create stage
    2. Name the step Edit Item Details
    3. From the step parameters panel (right) click Configure the View
      1. In the View Configuration add the Item field as a field group
      2. Select ItemDetail from the View dropdown to use it as the View for the Item field group
  4. Use +STAGE to add a new stage named Review
    1. Use +STEP to add a Collection Information step under the Review stage named Review Item Details
    2. From the step parameters panel (right) click Configure the View
      1. In the View Configuration add the Item field as a field group
      2. Select ItemDetailRO from the View dropdown to use it as the View for the Item field group
    3. c.       Use +STEP -> …More -> Processes and select Persist object
    4. d.       From the step parameters panel (right) configure the Persist object component
      1. For Type use Entity
      2. For Property use “.Item” (double quotes are significant)
  5. Change the case type rule label for PGPImp-DemoPGP-Work-Entity-Item-Update from Update to Update item
  6. Save the case
  7. Edit the pyDefault data transform rule for the Update work type to set the initial values on the .Item page from lookup data page
    1. Switch to the Parameters tab and add a parameter named EntityID of type String
    2. Add a Set action to the transform definition
      1. Use .Item as the Target
      2. Use D_Item[pyID:Param.EntityID] as the Source
  8. Save the data transform

Create the View Case Type[edit]

In PGP the View case type for Entities shows a comprehensive snapshot of an entity instance’s data.

  1.  Create a new Case Type named View
    1. Expand the Advanced section and specify the ancestry
      1. Use PGPImp-DemoPGP-Work-Entity-Item as the directed ancestor
      2. Use PGPImp-DemoPGP-Work-Entity-Item as the patterned ancestor
  2. Create a Workflow for the case type
  3. In the Stage Name field for the Create stage use the smart-prompt to select PegaPS-Work-Entity.View from the list of available stage processes.
  4. Change the case type rule label for PGPImp-DemoPGP-Work-Entity-Item-View from View to View item
  5. Save the case
  6. Override/SaveAs the PegaPS.Details section as PGPImp-DemoPGP-Work-Entity-Item-View.Details
    1. Include the section PGPImp-DemoPGP-Data-Entity-Item.Details using the .Item property as the page context.
  7. Save the section
  8. Edit the pyDefault data transform rule for the View work type to set the initial values on the .Item page from lookup data page
    1. Switch to the Parameters tab and add a parameter named EntityID of type String
    2. Add a Set action to the transform definition
      1. Use .Item as the Target
      2. Use D_Item[pyID:Param.EntityID] as the Source
  9. Save the data transform

Create the Search Case Type[edit]

In PGP the Search case type collects filter criteria from the user and retrieves a list of matching entities which may then be selected for further processing.

  1. Create a new Case Type named Search
    1. a.       Expand the Advanced section and specify the ancestry
      1.                                                              i.     Use PGPImp-DemoPGP-Work-Entity-Item as the directed ancestor
      2.                                                            ii.     Use PGPImp-DemoPGP-Work-Entity-Item as the patterned ancestor
  2. Create a Workflow for the new case type
  3. In the Stage Name field for the Create stage use the smart-prompt to select the PegaPS-Work.Search stage from the list of available stages
  4. Override/Save As the PegaPS-Work.Search section as PGPImp-DemoPGP-Work-Entity-Item-Search.Search
  5. Edit the PGPImp-DemoPGP-Work-Entity-Item-Search.Search section
  6. Use Structural -> Embedded Section to include the section PegaPS-Data.Search in the dynamic layout
    1. For Page context choose Use clipboard page
    2. For Class enter PGPImp-DemoPGP-Data-Entity-Item
    3. For Clipboard page select .Item from the list
    4. For Section choose By name and select Search from the list
    5. For PARAMETER ShowSearchType set Value to nothing
    6. Click Submit
  7. Save the section
  8. Override/SaveAs the PegaPS-Data.SearchCriteria section as PGPImp-DemoPGP-Data-Entity-Item.SearchCriteria
    1. Add the key properties for PGPImp-DemoPGP-Data-Entity-Item to this section
    2. Save the section
  9. Override/SaveAs the PegaPS-Data.SearchResults section as PGPImp-DemoPGP-Data-Entity-Item.SearchResults
  10. Edit the PGPImp-DemoPGP-Data-Entity-Item.SearchResults section
  11. Use Structural -> Table to add a table layout to the section and Configure the table
    1. For Source choose Data page
    2. For Data page select D_ItemList from the list
    3. For Parameters check Pass the parameter page
    4. Submit
  12. Save the section

Enabling for App Studio[edit]

  • Use views and design templates to construct the user interface
  • Manage the new Entity’s rules in Relevant Records so that appropriate choices will appear in the App Studio smart prompts.
  • For appropriate case types set the Show in ‘New’ menu checkbox under Settings -> General to enable the case type to appear on +Create nav

Appendix A - Rule Inventory[edit]

The following is a list of rules created in this exercise.

Applies -to Rule Name Rule Type Description Comment
PGPImp-DemoPGP-Data-Entity Class Abstract
PGPImp-DemoPGP-Data-Entity-Item Class Concrete Key EntityID
PGPImp-DemoPGP-Data-Entity-Item Database Table Persistence
PGPImp-DemoPGP-Data-Entity-Item ItemName Property Text
PGPImp-DemoPGP-Data-Entity-Item ItemType Property Text
PGPImp-DemoPGP-Data-Entity-Item ItemDetail Section View
PGPImp-DemoPGP-Data-Entity-Item ItemDetailRO Section View
D_Item Data Page Page Source=Lookup
D_ItemList Data Page Page List Source=Report Definition
PGPImp-DemoPGP-Data-Entity-Item ItemList Report Definition All Item Properties
PGPImp-DemoPGP-Work .Item (PGPImp-DemoPGP-Data-Entity-Item) Page
PGPImp-DemoPGP-Work .ItemList (PGPImp-DemoPGP-Data-Entity-Item) Page
PGPImp-DemoPGP-Work-Entity Class Abstract
PGPImp-DemoPGP-Work-Entity-Item Class Abstract
Add Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add Class Concrete Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add pyDefault Case Type Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add CreateForm_Default Flow Case Type
D_Add Data Page Case Type
D_AddList Data Page Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add pyDefault Data Transform Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add pySetFieldDefaults Data Transform Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add ItemInformation_Flow Flow Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add Create Flow Action Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add Create Section Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add ItemDetails Flow Action Case Type
PGPImp-DemoPGP-Work-Entity-Item-Add ItemDetails Section Case Type