View source for Creating New Entities in PGP

{{Design pattern|Title=Creating New Entities in PGP|Description=Guide to adding a new entity to PGP|Version=8.5|Applications=Pega Government Platform|Capability Area=Government|Owner=MARRF}}

== What are PGP Entities? ==
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: 
# Entity instances are persisted to a data store like any local data type or data table
# Entity data classes are used as a type for embedded pages defined on the PGP work ancestor to support case processing

=== Persistent Data Store ===
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 ===
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 ==
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 ===
* ''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 ===
* 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 ===
* ''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 ===
* 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 ==
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 ===
Create a persistent data type and supporting rules for the new entity.

==== Create Data Type Ancestor ====
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.
# Use ''Create -> SysAdmin -> Class'' to create a new class 
## For the ''Label'' use ''Entity''
## For the ''Class Name'' use ''PGPImp-DemoPGP-Data-Entity''
## Create and open
## For ''Select class type'' use ''Abstract''
## For ''Created in version'' use the current version
## For ''Parent class (directed)'' use ''PegaPS-Data-Entity''
# Save the rule

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

==== Create View UI for the New Data Type ====
Build the basic data layer UI rules to present the data of the new ''Item'' data type.
# Create View ''ItemDetail'' with Applies-To of ''PGPImp-DemoPGP-Data-Entity-Item''
## Place all the relevant properties from the ''Item'' data type
# Create View ''ItemDetailRO'' with Applies-To of ''PGPImp-DemoPGP-Data-Entity-Item''
## Place all the relevant properties from the Item data type, with the ''Presentation -> Edit Options'' set to ''Read-Only''

=== Extend the Work Ancestor Class ===
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''.
# Use ''Create -> Data Model -> Property'' to add a new property
## For the ''Label'' use ''Item''
## For the ''Apply to'' use ''PGPImp-DemoPGP-Work''
## Create and open
## Change the Property type to Single Page
## Select ''PGPImp-DemoPGP-Data-Entity-Item'' as the ''Page definition''
## Save the rule

=== Review Entity Data Type Rules ===
Switch to App Explorer (App) and show ''PGPImp-DemoPGP-Data-Entity-Item''. Review all the rules created for the ''Item'' data entity.
{| class="wikitable"
|'''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 ==

=== Create Abstract Support Work Classes ===
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.
# Use ''Create -> SysAdmin -> Class'' to create a new class 
## For the ''Label'' use ''Entity''
## For the ''Class Name'' use ''PGPImp-DemoPGP-Work-Entity''
## Create and open
## For ''Select class type'' use ''Abstract''
## For ''Created in version'' use the current version
## For ''Parent class (directed)'' use ''PegaPS-Work-Entity''
## Save the rule
# Use ''Create -> SysAdmin -> Class'' to create a new class 
## For the ''Label'' use ''Entity Item''
##  For the ''Class Name'' use ''PGPImp-DemoPGP-Work-Entity-Item''
## Create and open
## For ''Select class type'' use ''Abstract''
## For ''Created in version'' use the current version
## For ''Parent class (directed)'' use ''PGPImp-DemoPGP-Work-Entity''
## Save the rule

=== Create Data Management Case Types ===
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 ====
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.
# 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)
## Expand the Advanced section and specify the ancestry
## Use ''PGPImp-DemoPGP-Work-Entity-Item'' as the directed ancestor
## Use ''PGPImp-DemoPGP-Work-Entity-Item'' as the patterned ancestor 
# Create a Workflow for the case type
# In the default ''Create'' stage
## Use ''+STEP'' to add a Collect Information step under the ''Create'' stage
## Name the step ''Capture Item Details''
## From the step parameters panel (right) click ''Configure the View''
###  In the View Configuration add the ''Item'' field as a field group
###   Select ''ItemDetail'' from the View dropdown to use it as the View for the ''Item'' field group
# Use ''+STAGE'' to add a new stage named ''Review''
## Use ''+STEP'' to add a Collection Information step under the ''Review'' stage named ''Review Item Details''
## From the step parameters panel (right) click ''Configure the View''
### In the View Configuration add the ''Item'' field as a field group
### Select ''ItemDetailRO'' from the View dropdown to use it as the View for the ''Item'' field group
## Use ''+STEP -> …More -> Processes'' and select ''Persist object''
## From the step parameters panel (right) configure the ''Persist object'' component
### For ''Type'' use ''Entity''
### For ''Property'' use “''.item''” (double quotes are significant)
# Change the case type rule label for ''PGPImp-DemoPGP-Work-Entity-Item-Add'' from ''Add'' to ''Add item''
# Save the Case

==== Create the ''Update'' Case Type ====

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

==== Create the ''View'' Case Type ====
In PGP the ''View'' case type for Entities shows a comprehensive snapshot of an entity instance’s data.
#  Create a new Case Type named ''View''
## Expand the Advanced section and specify the ancestry
### Use ''PGPImp-DemoPGP-Work-Entity-Item'' as the directed ancestor
### Use ''PGPImp-DemoPGP-Work-Entity-Item'' as the patterned ancestor
# Create a Workflow for the case type
# 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.
# Change the case type rule label for ''PGPImp-DemoPGP-Work-Entity-Item-View'' from ''View'' to ''View item''
# Save the case
# Override/SaveAs the ''PegaPS.Details'' section as ''PGPImp-DemoPGP-Work-Entity-Item-View.Details''
## Include the section ''PGPImp-DemoPGP-Data-Entity-Item.Details'' using the ''.Item'' property as the page context.
# Save the section
# Edit the ''pyDefault'' data transform rule for the ''View'' work type to set the initial values on the ''.Item'' page from lookup data page
## Switch to the ''Parameters'' tab and add a parameter named ''EntityID'' of type ''String''
## Add a ''Set'' action to the transform definition
### Use ''.Item'' as the ''Target''
### Use ''D_Item[pyID:Param.EntityID]'' as the ''Source''
# Save the data transform

==== Create the ''Search'' Case Type ====
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.
# Create a new Case Type named ''Search''
## a.       Expand the Advanced section and specify the ancestry
###                                                              i.     Use ''PGPImp-DemoPGP-Work-Entity-Item'' as the directed ancestor
###                                                            ii.     Use ''PGPImp-DemoPGP-Work-Entity-Item'' as the patterned ancestor
# Create a Workflow for the new case type
# 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
# Override/Save As the ''PegaPS-Work.Search'' section as ''PGPImp-DemoPGP-Work-Entity-Item-Search.Search''
# Edit the ''PGPImp-DemoPGP-Work-Entity-Item-Search.Search'' section …
# Use ''Structural -> Embedded Section'' to include the section ''PegaPS-Data.Search'' in the dynamic layout
## For ''Page context'' choose ''Use clipboard page''
## For ''Class'' enter ''PGPImp-DemoPGP-Data-Entity-Item''
## For ''Clipboard page'' select ''.Item'' from the list
## For ''Section'' choose ''By name'' and select ''Search'' from the list
## For ''PARAMETER ShowSearchType'' set ''Value'' to nothing
## Click Submit
# Save the section
# Override/SaveAs the ''PegaPS-Data.SearchCriteria'' section as ''PGPImp-DemoPGP-Data-Entity-Item.SearchCriteria'' …
## Add the key properties for ''PGPImp-DemoPGP-Data-Entity-Item'' to this section
## Save the section
# Override/SaveAs the ''PegaPS-Data.SearchResults'' section as ''PGPImp-DemoPGP-Data-Entity-Item.SearchResults''
# Edit the ''PGPImp-DemoPGP-Data-Entity-Item.SearchResults'' section …
# Use ''Structural -> Table'' to add a table layout to the section and Configure the table
## For ''Source'' choose ''Data page''
## For ''Data page'' select ''D_ItemList'' from the list
## For ''Parameters'' check ''Pass the parameter page''
## Submit
# Save the section

== Enabling for App Studio ==
* 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 =
The following is a list of rules created in this exercise.
{| class="wikitable"
|'''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
|}