Example of Cascading Drop Downs with Linked Class Key Property in Pega 7.1.6

This example shows how a foreign key type relationship can be configured between two reference data tables. A column in one data table will hold key values that refer to instances in the other data table.

  • Additionally, an example is provided that shows how two reference data tables can be used to populate cascading drop-downs using a property to hold linked class keys to instances of another class.

Related Posts

Summary

  1. Use Case Example with Two Cascading Drop-Down Controls in Pega 7
  2. Create Data Tables to Populate Drop-Down Options in Pega 7
  3. Configuring Cascading Drop-Downs in Pega 7

  • A form shows 2 drop-downs, one that allows a user to select a car make such as Honda or Audi (parent) and a dependent drop-down that allows to select a model for that car make (child), such as Accord when Honda is selected.
  • Similarly, when Audi is selected in the Make drop-down, A4, A5, A6 and so on should be displayed in the child Model drop-down.
  • Every time the parent drop-down changes, the child drop-down should be updated automatically to show the models for the selected car make.
  • The form with the 2 drop-downs that will be built in this example will look like the one in the screen shot below.

Example of UI section with cascading drop-down controls in Pega 7

  • In the screen shot, Honda has been selected in the Make drop-down and the Model drop-down shows all available models linked to the selected make.

  • One data table will hold the options for the Make drop-down and another data table will hold the options for the Model drop-down. In this example, the two data tables are named as follows:
ABC-Insurance-Data-Make for the Make drop-down (parent)
ABC-Insurance-Data-Model for the Model drop-down (child)
  • A data table can be created by navigating to DesignerStudio > Data Model > Data Tables > Data Tables.

Pega 7 Designer Studio, main menu, open Data Tables view

  • The Data Tables view lists all available data tables. A new data table can be added by clicking on the button Add new Data Table.

Pega 7 Designer Studio, Data Table view, add a new Data Table

  • The Data Table Wizard dialog for creating the ABC-Insurance-Data-Make data table is shown below. Note that it derives from  ABC-Insurance-Data and a lookup data page named D_Make and a list data page named D_Makes will be automatically generated.
  • In addition, a dedicated database table is created by checking CREATE DEDICATED DATABASE TABLE?.
  • This will cause Pega to create and use a separate dedicated DB table for storing instances of ABC-Insurance-Data-Make and allows for migration of the data when exporting/importing.

Pega 7 Designer Studio, Data Table Wizard, confirmation of new data table for ABC-Insurance-Data-Make

  • The ABC-Insurance-Data-Make class has two properties:
idunique key, of type Identifier, has to start with letter and can contain hyphens and numbers: e.g. M-1
pyLabel – of type Text, inherited from ABC-Insurance-Data, used to store the car makes: e.g. Honda
  • Insert Make Records: The cog-wheel icon in the edit column of the ABC-Insurance-Data-Make data table can be used to create records.

Pega 7 Designer Studio, Data Table view, add new instances to existing data table

  • In this example, 5 car make records have been inserted into the table.
  • The plus icon in the lower right hand corner can be used to add more instances.

Pega 7 Designer Studio, Data Table view, add car make instances ABC-Insurance-Data-Make to data table

  • Since CREATE DEDICATED DATABASE TABLE was selected in the Data Table Wizard, a separate database table was created to store the instances of ABC-Insurance-Data-Make.
  • To get the table name, open the ABC-Insurance-Data-Make class and click on the Test Connection button.

ABC-Insurance-Data-Make Class Test Connection

  • A new window will show the Pega database schema name and the table name. In this case, it is pegadata.pr_ABC_Insurance_Data_Make.

Pega database for ABC-Insurance-Data-Make class pegadata.pr_Abc_Insurance_Data_Make

  • The data can easily be viewed in the Pega database -in this case PostgreSQL is used- by using a tool such as pgAdmin.
  • Refer to this post on using pgAdmin to view the Pega DB: Example of Connecting to Pega 7 PRPC PostgreSQL DB with pgAdmin.
  • In the pgAdmin tool, navigate to the schema pegadata and locate the table pr_abc_insurance_data_model.
  • Right click on the table name and select View Data > Top 100 rows.

pgAdmin to view rows in pr_Abc_Insurance_Data_Make data table

  • For the second drop-down, a second data table called ABC-Insurance-Data-Model has been created with the Data Table Wizard. The summary is shown below.

Pega 7 Designer Studio, Data Table Wizard, confirmation of new data table for ABC-Insurance-Data-Model

  • The ABC-Insurance-Data-Model class has three properties:
id – the unique key, of type Identifier, e.g. M-001
pyLabel – inherited from ABC-Insurance-Data, used for actual model value such as Civic
make – a reference of type Identifier to an instance of ABC-Insurance-Data-Make
  • After creating the Model data table, the class ABC-Insurance-Data-Model needs to be configured further so that the Make property will hold valid class key values, pointing to ABC-Insurance-Data-Make instances.
  • Using the App Explorer, the make propery of the ABC-Insurance-Data-Model class needs to be opened as edited.

Pega 7 Designer Studio, edit make property of ABC-Insurance-Data-Model

  • In order to link the values of the make property of the ABC-Insurance-Data-Model class to ABC-Insurance-Data-Make instances, the option Automatic reference to class instance (linked) needs to be selected.
  • In this example, the linked class is ABC-Insurance-Data-Make and the source property is .make, which is linked to the id property of the ABC-Insurance-Data-Make class.
  • In addition, under Display and Validation, select pxDropdown and Class Key Value for table type.
  • The Validation Class needs to be set too, in this case it needs to be ABC-Insurance-Data-Make, so that only valid IDs (keys) of that class can be set in .make property of the ABC-Insurance-Data-Model class instances.

Pega 7 Designer Studio, Automatic reference to class instance (linked) for make (key) property

  • Use the Designer Studio navigation to return to the Data Tables view.

Pega 7 Designer Studio, main menu, open Data Tables view

  • Insert Model Records: Click on the cog wheel icon for the car models class name (ABC-Insurance-Data-Model) to insert reference data.

Pega 7 Designer Studio, Data Table view, add new instances to existing data table

  • Insert references for car models and link them to ABC-Insurance-Data-Make instances by using valid class key values values such as M-3 to refer to the car make Audi.
  • PRPC will ensure that the make property can only hold valid ABC-Insurance-Data-Make class keys.
  • If a developer tries to insert a model instance where the make value does not refer to an existing ABC-Insurance-Data-Make instance, an error message will be displayed, i.e. referential integrity is enforced by PRPC.
  • In the below screen shot, M-9 is not a valid class key in the ABC-Insurance-Data-Make data table, and a class key validation error is shown.

Pega 7 Designer Studio, Data Table view, add car model instances ABC-Insurance-Data-Model to data table, class key validation

  • The class key validation will be performed everytime the make property of ABC-Insurance-Data-Model is set in the PRPC system (e.g.: data transfor, activity).

  • In a Section rule, add a new drop-down control. In this case, the parent drop-down will be the reference for car makes.
  • When a car make is selected, a second drop-down will be automatically updated to shows all models for the selected car make.
  • Here, the Section rule applies to the ABC-Insurance-Work-Auto work object class.

Pega 7 Designer Studio, edit section, configure drop-down control

  • Click on the cog wheel icon to configure the drop-down control for car makes.
  • Set the Property to .Make, a property of the work object class. It will hold the selected car make key.
  • On the General tab, configure the drop-down List Source as follows:
Type: Data Page
Data page: D_MakesThe list data page that was created by the Data Table Wizard in step 1.
Property for value: .id – the unique identifier of the ABC-Insurance-Data-Make class.
Property for display text: .pyLabel – the text to show in the drop-down list, e.g.: Honda.

Pega 7 Designer Studio, configure drop-down control, set list source to use data page

  • In this example, the load behavior is set to At screen load (Default).
  • Click on OK and save the section rule. Then test it by clicking on Actions > Preview.
  • The car make drop-down should be properly populated with the car make values as per the underlying data table as shown below.

Pega 7 Designer Studio, preview make drop-down control

  • Before adding the second drop-down that will show the car model options based on the selected make, the Report Definition of the ABC-Insurance-Data-Model class needs to be modified in order to allow an input parameter for filtering the car models by make.
  • In the Application Explorer, open the dataTableListReport of ABC-Insurance-Data-Model.

Open Report Definition named dataTableListReport of class ABC-Insurance-Data-Model using the Application Explorer.

  • Navigate to the Parameters tab of the Report Definition and add a text parameter called MakeKey as shown below.
  • This parameter will hold the value the user selects in the make drop-down field, which represents the unique key of a selected car make instance.

Add parameter to report definition dataTableListReport of ABC-Insurance-Data-Model

  • Next, navigate to the Query tab of the Report Definition and add a filter condition.

Add filter condition on the query tab of the ABC-Insurance-Data-Model dataTableListReport report definition.

  • The filter condition will compare the input parameter MakeKey, which will hold a car make key to the linked class key .make in the ABC-Insurance-Data-Model data table so that the report only returns instances where the make keys match.
  • Make sure to Save the changes to the Report Definition. A warning message will indicate that the .make and .id properties are not optimized, resulting in poor performance.
  • They can be optimized using the Application Explorer. For details on how to optimize the 2 properties, refer to this post: Example of How to Create a Report Definition in Pega 7.
  • It is a good idea to test the report before continuing. To do so, click on Actions > Run. By default, the report will run without any filters applied and all instances will be shown.

Pega 7 Designer Studio, Run report definition dataTableListReport, no filters

  • The filter can be tested by clicking on the link next to the label Filters:. A new dialog allows to specify the value for the filter, in this case the key of a car make instance. When set to M-1 (Honda), the report will only show car model instances for that car make.

Pega 7 Designer Studio, Run report definition dataTableListReport, filter by car make

  • Next, open the data page D_Models for the car models that was automatically generated by the Database Table Wizard and navigate to the Parameters tab. Add an input parameter, in this case called MakeKey, of data type String and set REQUIRED to Yes.

Add input parameter for MakeKey to D_Models of ABC-Insurance-Data-Model

  • On the Definition tab, make sure that Report Definition is selected for the data source and that the correct report name is used. Click on the Parameters link underneath the text fiel for the report name and tick the checkbox Pass current parameter page. This option will pass the input parameter MakeKey of the data page to the specified report definition, where it will be used for the filter condition.

20_D_Models_Definition_Tab

  • Save the changes to the data page. The data page can be tested by clicking on Actions > Run.
  • The initial dialog shows the required MakeKey input parameter. Enter a valid value and click on Execute.

Pega 7 Designer Studio, Run data page D_Models, enter MakeKey parameter

  • An XML representation of the data page is shown and the matching car model instances can be seen in the pxResults structure.

Pega 7 Designer Studio, Run data page D_Models, view XML representation of result

  • Finally, open the UI section rule and add a second drop-down for the car model options.

Pega 7 Designer Studio, Add drop-down control to UI section

  • Click on the cog wheel icon to configure the car model drop-down control.
  • On the General tab, configure the List Source as follows:
Property: .Model – A propery of ABC-Insurance-Work-Auto to store the selected car model key.
Type: Data page
Data page: D_Models – The list data page that was created by the Data Table Wizard in step 1.
Parameter: .MakeProperty of the work object class holding the make key, set when selecting an option from the first drop-down.
Property for value: .id – The unique identifier of the ABC-Insurance-Data-Model class.
Property for display text: .pyLabel – The text to show in the drop-down list, e.g.: Civic.

Pega 7 Designer Studio, Edit drop-down for car model references, filter by selected make key

  • For Load behavior, select After screen renders, so that the options will be loaded when the make drop-down is rendered.
  • In addition, check the checkbox Enable Caching of Options to improve performance by preventing unnecessary loading of the data page and execution of the underlying report definition.
  • Finally, the UI section and the cascading drop-downs can be tested by clicking on Actions > Preview.

Pega 7 Designer Studio, preview UI section, cascading drop-downs for car make and car model

  • Whenever the Make drop-down is changed, the Model drop-down will automatically load the linked car model options.
  • Additional drop-downs can be added following the same steps. Here, a third drop-down could be added to show trim options such as 3.0T Quattro whenever a model is selected.

Example of Pega 7 File Service and File Listener to Parse CSV Files and Insert Rows into Data Table

This post shows how a Service and a File Listener rule can be used to automatically populate a data table based on an input text file (comma-separated values). During processing, the delimited text file is parsed and for each row, a record is created in the target data table. This setup saves manual labor when large input files are used to populate data tables.

Related Posts

Summary

  1. Setup of Data Table in Pega 7 and Description of CSV File Format
  2. Creating the Service Rule using the Pega 7 Service Accelerator
  3. Implementing the Service Rule to Parse and Process CSV Files in Pega 7
  4. File Listener Configuration in Pega 7
  5. Running the File Listener
  6. Move CSV Files to Source Location and Run File Listener and Service in Pega 7

In this example, an existing data table for a class named ABC-Insurance-Data-Adjuster is populated automatically. The data table serves as a reference for claims adjusters that are contracted for investigating insurance claims. This class has the following properties:

ID of type Identifier
Firstname of type Text
pyLabel of type TextPega standard property will be used for the last name
HourlyRate of type Decimal
PhoneNumber of type Text
  • The screen shot below shows the configuration page when this data table was created using the Data Table Wizard.
  • Note that the check box CREATE DEDICATED DATABASE TABLE? is checked so that this static reference data can be migrated with the application.

Pega Data Table Wizard - Create New Data Table

  • Initially, there is no data in the data table and the row count shows 0 in the data table view.

Pega 7 Designer Studio - Data Model - Show Data Tables

  • The gear icon in the Edit column can be used to manually insert instances.
  • However, in this example, a Service and File Listener rule are used to automatically insert instances from a sample CSV text file shown below.

Example CSV File adjusters.csv

  • Each delimited row in the file represents a claims adjuster (a person that reviews an insurance claim).
  • The structure of the rows must match the properties defined in the data table into which instances will be inserted.
  • In addition, the input file has a header row where the fields match the property names of the class of the target data table.

A Service rule needs to be created. This rule will read and parse the input CSV file(s) and then use an activity to insert instances into the specified data table for each input row.

  • Navigate to Designer Studio > Integration > Services > Service Wizard to open the Service Accelerator tool.

Pega 7 Designer Studio - Accessing the Service Wizard

Step 1: Select Service Purpose

  • Select Process input or output data for the Service purpose and File for the service type, then click the Next button.

Pega 7 Service Accelerator (Service Wizard) - Select Service Purpose

Step 2a: Provide Service Details – Select Data Class

  • This step requires the selection of the appropriate data class, i.e. the class name of the data table into which instances will be inserted.
  • In this case, the data class is ABC-Insurance-Data-Adjuster. The service name in this example is InsertAdjusters and the wizard will use this name for the generated Service.
  • Click on the Next button to continue.

Pega 7 Service Accelerator (Service Wizard) - Provide Service Details and Select Data Class

Step 3: Customize Service Data

  • This step is used to define the primary input and output properties. Click on the two check boxes labeled Select FIELD NAME in the Primary Page Input Properties and Primary Page Output Properties sections.
  • The property pyLabel is not listed here since it is inherited. This omission will NOT be a problem later on. Click on Next to continue.

Pega 7 Service Accelerator (Service Wizard) - Customize Service Data

Step 4: Select Service Resources

  • Specify a ruleset and ruleset version for the auto-generated service rules. In this case, the ruleset name is Insurance and the ruleset version is 01-01-01.
  • Use the default options Configure a new service package and Configure a new service listener and click on Next to continue.

Pega 7 Service Accelerator (Service Wizard) - Select Service Resources

Step 5: Configure Data Records

  • The next screen is used to configure the new service listener. The listener needs to be configured to monitor a specified file system directory for CSV input files. In this case, the directory on the Pega (7.1.6) instance, where input files will be located is:
/usr/share/tomcat7/webapps/prweb/data
  • This folder may be different for Pega versions other than 7.1.6.
  • The Source Name Mask is *.csv and specifies that only csv files will be picked up by the File Listener for processing.

Pega 7 Service Accelerator (Service Wizard) - Configure Data Records

Step 6: Review and Save

  • Review the configuration of the Service and File Listener rules. Individual sections can be expanded by clicking on the plus (+) signs next to the labels.
  • In this example, the service type is Rule-Service-File (see Rule-Service-File at Pega Help).
  • The service package is AdjusterDataService and the final activity that will be called from the service implementation is called InsertAdjusters (…to insert a record into the data table).

Pega 7 Service Accelerator (Service Wizard) - Review and Save

  • Scroll down in the dialog to view details of the Final Activity as shown below.
  • Note that the Access Group specifies what privileges the generated Services will have.
  • The processing mode is specified as stateless, which means that each transaction (i.e. each record read from the file and inserted into the DB table) is isolated and not related to any previous one.

Pega 7 Service Accelerator (Service Wizard) - Review and Save (continued 2)

  • Since the option Configure a new service listener was selected earlier, the Service Accelerator will also generate a service listener rule. See screen shot below for details.
  • The File Listener will monitor a specified folder on the Pega host’s file system:
/usr/share/tomcat7/webapps/prweb/data
  • …and automatically read files that match the specified pattern, here: *.csv.
  • In this example, the listener is named AdjusterDataListener.
  • The boolean Disable Startup? parameter specifies whether the listener will be started automatically when PRPC is started or whether it has to be started manually through the System Management Application (SMA).

Pega 7 Service Accelerator (Service Wizard) - Review and Save (continued 3)

  • After reviewing the configuration, click on the Finish button to complete the configuration process and to run the Service Accelerator. At this point, the Service and all associated rules will be generated.

Pega 7 Service Accelerator (Service Wizard) - The service configuration process is now complete

  • A final confirmation screen, indicating the successful execution of the Service Accelerator, will be shown. Note that Pega 7.1.6 was used for this example and it seems to still use the Pega 6 UI theme for this confirmation screen.

Open the Service rule by entering its name in the search field in the Designer Studio. In this case, the name InsertAdjusters was used during configuration.

Tab: Service

  • The PRIMARY PAGE section shows the page class and the page name.
  • The PROCESSING OPTIONS section shows the execution mode. It is set to Execute synchronously, meaning that the service processes one file at a time.
  • The other execution modes allow asynchronous processing of input files (e.g.: placing files into a queue for background processing).

Pega 7 Edit Service File - Service Tab - Set Execution Mode Execute Synchronously

Tab: Method

  • This tab used to configure how PRPC detects and processes records in the input file.
  • Processing Method: is set to record at a time, which specifies that each row in an input file is parsed and then inserted into the data table immediately.
  • Record Terminator: a row in the CSV file is delimited by a carriage return and new line character, so \r\n is used here.
  • Character Encoding: UTF-8 is selected here since this is the character encoding of the input text file. During processing, PRPC converts the input characters from the specified encoding to Java String encoding (16-bit Unicode).

Pega 7 Edit Service File - Method Tab - Set Processing Method, Record Terminator and Encoding

Tab: Request

  • This tab is used to specify the Parse Segments. By default, the properties of the page class are listed here and a Final Activity is listed.
  • The final activity will be called each time a record from the input file has been parsed.
  • In this case, it will be used to insert the record into a data table.

Pega 7 Edit Service File - Request Tab - Parse Segments and Final Activity

  • Important: In this example, a Delimited ParseRule, instead of the default parse segment settings, will be used for parsing.
  • Manually remove the parse segments: Click on one of the text fields in a parse segment and then click on the X icon that appears to the far right of the segment row.
  • Also remove the entry in the Final Activity field.

Pega 7 Edit Service File - Request Tab - Remove Parse Segments

  • In the Map To auto-complete field of the empty parse segment row, select Delimited ParseRule.
  • The Map To Key text field is used to specify the name of the delimited parse rule.
  • The naming convention of the delimited parse rule is <namespace>.<file-extension> (case sensitive)
  • It will be applied for each row in the input file. The namespace has to match the last part of the page class, e.g.: ABC-Insurance-Data-Adjuster.
  • The file extension will be CSV and in this case, the Map To Key value will be Adjuster.CSV.
  • In the Activity text field, identify the activity that will be called after the current row is parsed and the data is available on the clipboard.
  • Here, the activity InsertAdjusters, which was created by the service accelerator, is called.
  • Click on the Save button to save the current settings.

Pega 7 Edit Service File - Request Tab - Map to Delimited ParseRule

  • The next step requires the configuration of the Delimited ParseRule.
  • Click on the magnifying glass icon next to the text field in the Map To Key column. This will open a new dialog window to create the rule.

Pega 7 Edit Service File - Request Tab - Open Delimited ParseRule

  • The label, identifier and record type are pre-filled based on the Map To Key value.
  • Click on Create and open to continue.

Pega 7 Designer Studio - Create Parse Delimited Rule

  • The screen shot below shows the configuration of the parse rule. Select Comma-Separated Values (CSV) for the Field Format.
  • In the Parsing Details section, create a row for each field in the input file. The order of the parsing rows has to match the order of the fields in the input file.

Pega 7 Designer Studio - Edit Parse Delimited Rule - Set Field Format to Comma-Separated Values (CSV) and Map To Clipboard

  • So, in the file below, the column ID will be mapped in the first row, the column Firstname will be mapped in the second row and so on.

Example CSV File to be Parsed

  • The description does not have to match the header values in the input file.
  • Select Clipboard in the Map To auto-complete field and then select the property in the page class rule to which the current field will be mapped.
  • Make sure the checkbox in the Required column is checked. Complete this activity for each field in the input file as shown below.
  • Note that the Lastname field from the input file is mapped to the inherited property pyLabel. This field can be used instead of creating a separate property for the last name.
  • Click on Save to save the Parse Delimited rule and then close the dialog.

Pega 7 Designer Studio - Edit Parse Delimited Rule - Parsing Details

  • It is also necessary to implement the insert activity rule that was specified earlier on the Request tab of the Service rule.
  • Again, the activity is named InsertAdjusters. The Service > Request screen is shown below again. Click on the magnifying glass to open the activity rule.
  • Note that this activity will be called for each row in the input file, i.e. it will read one row from the file and then insert one record into the data table.

Pega 7 Designer Studio - Edit Service File - Open Parse Segment Activity

  • Open the activity and navigate to the Pages & Classes tab. A page of the class for which instances will be inserted into the data table needs to be declared here.
  • In this case, instances of the class ABC-Insurance-Data-Adjuster are inserted.

Pega 7 Designer Studio - Edit Activity - Insert Activity Pages and Classes

  • Next, navigate to Steps and use the Page-New method in the first step to create a new clipboard page of this class.
  • In the second step, select the Property-Set method and enter the name of the page (Step Page) that was created in row 1.
  • Under Method Parameters, link the properties of the step page to the properties on the primary clipboard page
  • E.g.: .ID refers to the property of the step page and Primary refers to the clipboard page that will be populated by the parse delimited rule for each record in the input file.

Pega 7 Designer Studio - Edit Activity - Steps

  • In the third step, the Obj-Save method is used to save the step page, here the ABC-Insurance-Data-Adjuster, into the data table.
  • The parameter WriteNow will cause the system to immediately commit the insert operation. Make sure to save the activity rule.

The last part of the setup concerns the configuration of the File Listener rule that was created earlier, when the Service Accelerator was run. The File Listener will be configured to automatically monitor a specified directory on the PRPC file system for input files, in this case files that match the pattern .CSV.

  • If a new file is found, the File Listener will automatically invoke the Service file rule to process the input CSV file.
  • The screen shot below shows the File Listener details from the earlier Service Accelerator execution.

Pega 7 Service Accelerator (Service Wizard) - Review and Save - New Service Listener

  • Open the File Listener by searching for the listener name, in this case, the Service Accelerator created a File Listener rule called AdjusterDataListener.
  • The properties tab shows the listener properties and is pre-filled based on the selections made when the Service Accelerator was run.
  • Make sure that the Source Location directory is set properly. This is the directory, the File Listener will monitor for input files.
  • In this example, PRPC is running as a Personal Virtual Server, utilizing the VMWare Player (Pega 7.1.6 CSA Exercise System from Pega Academy).
  • A FTP client can be used to load input files to the file system of the virtual server.
  • For an example on how to setup FTP access to a Pega 7.1.6 CSA Exercise System running on VMWare, see: Example of FTP Connection to Pega 7 PRPC for Private Virtual Server Installations.
  • Click on the Test Connectivity button to confirm that the listener is configured properly and that the file source location is accessible.

Pega 7 Designer Studio - Edit File Listener - Properties Tab - Set Source Location, Source Name Mask, Service Package, Service Class and Service Method

  • A confirmation dialog as shown below should appear and display the message Connectivity test successful.

Pega 7 Designer Studio - Edit File Listener - Test Connectivity

  • If the connectivity test fails: For Private Virtual Server installations: Use the VMWare player to log into the virtual machine (architect, password or root, install) and create the input file directory and set appropriate access privileges using the commands:
sudo mkdir /usr/share/tomcat7/webapps/prweb/data
sudo chmod 777 /usr/share/tomcat7/webapps/prweb/data
  • In the below example, the data directory is now accessible by owner, group and everybody for reading and writing.

Pega 7 - File Listener - VMWare Ubuntu - Source Directory File Permissions

  • The File Listener will start monitoring the source location as soon as it is started (…when running the Service Accelerator, there is an option to specify whether the listener will start automatically when PRPC is started. In this case this option was set to false.).
  • To start the File Listener, open the System Management Application (SMA) by navigating to Designer Studio > System > Tools > System Management Application

Pega 7 Designer Studio - Opening the System Management Application

  • In the list of Nodes, click on a node name to load the configuration for that node. In this case, there is only one node called localhost.
  • If the list of nodes is empty, the Pega node under which the Service and File Listener rules were created needs to be added.
  • This can be done by clicking on the plus (+) icon in the upper left hand corner of the SMA window.
  • In order to start the File Listener, click on Listener Management in the navigation menu that appears once a node is selected.
  • Then select the listener from the Available Listeners drop-down control and click on the Start button in the section above it.
  • Once the listener is running, it will be listed in the Running Listeners section as shown below.

Pega 7 System Management Application - Listener Management

  • Note: The File Listener can be configured further: the Process tab allows to specify the polling interval, i.e. how often the listener will check the source location for new input files.
  • The Generate report file? check box can be checked to have the listener create an XML based report file (in the specified source location). The report shows details regarding input file processing such as parsing errors.
  • The File Operation parameter in the CLEANUP section can be used to specify what the listener does with input files that have been processed. In the below screen shot Delete is selected so that the listener will remove the input files from the system.

Pega 7 Edit File Listener - Process Tab - Set polling interval, generate report file and cleanup activity

  • If changes are made while the listener is running, it is required to restart the listener in order for the changes to take effect.

At this point, there are no input files in the directory the File Listener is monitoring. A FTP client such as FileZilla or the command line can be used to copy input files to the directory. In this case, PRPC is installed as a Personal Virtual Server, so the PRPC instance is running in a virtual machine with its own IP address, here 192.168.241.128.

  • By default, the virtual machine is running a FTP server and the default architect, password or root, install credentials can be used to connect to it via FTP.
  • The screen shot below shows the FileZilla configuration to connect via FTP to the virtual machine.
  • For an example on how to setup FTP access to a Pega 7.1.6 CSA Exercise System running on VMWare, see: Example of FTP Connection to Pega 7 PRPC for Private Virtual Server Installations.

FileZilla Site Manager - Configure FTP access to PRPC instance on virtual machine

  • Copy the input CSV file(s) to the source location that was specified earlier. Here it is:
/usr/share/tomcat7/webapps/prweb/data
  • The listener will pick up the file(s) and invoke the Service to parse and process it.

FileZilla File Listener Source Folder - File Listener report

  • After processing has been completed, the same directory may contain XML files (in the case of processing errors). These files can be used to debug parsing errors etc.
  • In the System Management Application, the Request Count in the Running Listeners section will show how many files the listener has processed since it was started.

System Management Application - File Listener Request Count

  • Finally, when the Data Tables view is reloaded, the Row Count for the target data table will reflect the records that were inserted.

Pega 7 Designer Studio - Data Model - Data Tables - Updated row countshowing row count

  • Clicking on the gear icon to the right of the row count will open the data table and show the inserted records.

Pega 7 Designer Studio - View Data Table Instances

Example CSV file adjusters.csv

  • Note: If the listener was configured to generate a report file (see Process tab > Generate report file?), it will be available in the same input file directory in a subfolder called report.
  • The report file will have the name of the input file with the file extension .rpt.
  • A sample report file is shown in the screen shot below. The report contains data such as the number of rows that were inserted into the data table, the exact file size in byte and the listener name that processed the input file.

Pega 7 File Listener Report File in XML Format

  • Note: If needed, an activity can also be created to purge existing data in the data table before new data from a CSV file is imported.
  • This cleanup activity can be called using the Initial Activity field in the PROCESSING PROLOG section of the Service rule as shown below.

Pega 7 Designer Studio - Edit Service File - Request Tab - Processing Prolog Initial Activity

Example of Pega 7 Auto-Complete Control Backed by Data Table

The following example shows how to create a data table and how to use it to populate an auto-complete UI control in Pega 7. The auto-complete control allows a user to type a search term and it will present matching options in a dynamic list as shown in the screen shot below.

Pega 7 Auto Complete Control Example

Related Posts

Summary

  1. Creating a new Data Table Using the Data Table Wizard in Pega 7
  2. Populating an Auto-Complete Control from a Data Table in Pega 7

  • Open the data tables view by clicking on Designer Studio > Data Model > Data Tables > Data Tables:

Pega 7 Designer Studio - View Data Tables List

  • The data tables view shows a list of existing data tables:

Pega 7 Data Model List of Available Data Tables

  • Click on the Add a new Data Table button. This will open the Data Table Wizard.
  • In this example, a new data table will be created for storing car makes.
  • The class name should be derived from the organization name, here ABC and the application name, here Insurance and the derived class, here -Data.
  • Therefore, the class name in this example is ABC-Insurance-Data-Make.
  • The class for this data table should derive from the -Data class, so the DERIVES FROM field will be ABC-Insurance-Data.

Pega 7 Data Table Wizard - Generate Data Table

  • The check box CREATE DATA PAGES? must be checked in order to see the LOOKUP DATA PAGE and LIST DATA PAGE fields. Completing these fields will cause the wizard to create data pages that can be used to retrieve a single instance of ABC-Insurance-Data-Make or a list of instances.
  • The check box CREATE DEDICATED DATABASE TABLE? should be checked since this data tables provides reference data and should be included when migrating the application.
  • In this example, the intention is to display an auto-complete UI control that allows a user to select from a list of car makes.
  • The ABC-Insurance-Data-Make class will have 2 properties: ID and pyLabel.
  • The ID will be a unique numeric identifier and the inherited pyLabel property of type text will store the car makes such as Honda and Toyota. After entering the configuration data, click on the Generate button to continue.

Data-Table-Wizard---Make-Completed

  • The wizard generates the data table and Associated Rules such as a default data transform, a validate rule and the lookup data page (D_Make) and list data page (D_Makes) using the names specified in the configuration name.
  • After clicking on the Close button and refreshing the data table view, the new data table appears.
  • At this point, the row count is 0 since no data records have been created yet.

Pega 7 Data Table View - New Data Table Available

  • Click on the cogwheel icon in the EDIT column in order to open a view that allows adding rows to the data table.

Pega 7 Data Table View - Edit Data Table Instances

  • Click on the + icon to insert ABC-Insurance-Data-Make instances into the data table.

Pega 7 Data Table View - Insert Data Table Instance

  • Clicking on the check mark icon to the right of the Label text box will insert a new record into the data table.
  • The data table will enforce the unique constraint for the ID column and display an error icon and a tool tip when the user attempts to insert a row with an existing identifier.

Pega 7 Data Table View - Insert Instance Error - This instance already exists

  • Once the data has been added, the dialog showing the data table instances can be closed.
  • Refreshing the data table’s view shows the new row count:

Pega 7 Data Table View - Showing Row Count

  • Here, we want to set a case instance property from a selected value of an auto-complete control.
  • In the sample application, there is a case type rule called ABC-Insurance-Work-Auto that will be used to encapsulate auto policy work.
  • This case type rule has a property called Make that is a single value property of type text.

Pega 7 Application Explorer - Case Type Property

  • Create a new Section rule for the ABC-Insurance-Work-Auto case type and insert e.g. a Dynamic Layout.
  • Click on the Advanced drop down control in the Deign tab and drag and drop the Auto-Complete control into the dynamic layout.

Pega 7 Designer Studio - Edit Section - Advanced - Add Auto Complete Control

  • Click on the auto-complete control and then on the cogwheel icon in the upper right hand corner.

Pega 7 Designer Studio - Edit Section - Configure Auto Complete Control

  • This will open a dialog for configuring the auto-complete field. In the Property field, type a . (dot) to see all available properties of the ABC-Insurance-Work-Auto case type and select the Make property as shown below.

Pega 7 Designer Studio - Auto Complete Control - General tab

  • A Placeholder can be used to display a default text in the auto-complete control, when no value is selected.
  • In the LIST SOURCE section, select Data page in the type drop down field and enter the name of the list data page that was created using the Data Table Wizard, in this case: D_Makes.

Pega 7 Designer Studio - Auto Complete Control - General tab - Placeholder and List Source

  • Alternatively, instead of using the data page, the default Report Definition, here named dataTableListReport, which was also created by the Data Table Wizard can be used.

Pega 7 Designer Studio - Auto Complete Control - List Source Configuration

  • Caution: Using a data page has performance advantages since it can be configured to be cached (see Load Management tab of edit data page view), whereas the report definition is run every time the auto-complete is loaded.
  • When using a report definition, the SEARCH RESULTS CONFIGURATION section of the dialog is used to select the data source property that will be used for the search and for displaying the auto-complete suggestions list.
  • In this case, the auto-complete needs to search the pyLabel property of the ABC-Insurance-Data-Make instances in the data table.
  • The Match start of string check box causes the auto-complete search to show suggestions where the entered string matches the beginning of Makes instances.
  • E.g.: When the user enters Me in the auto-complete control, the list of suggestions should show all car makes where the pyLabel value starts with Me.

Pega 7 Designer Studio - Configure Auto Complete Control - Search Results Configuration

  • Click on OK to close the dialog and then click on Save to apply the section changes.
  • The auto-complete can be unit-tested by clicking the Actions button and selecting Preview.

Pega 7 Auto Complete Control Example

  • The section will be rendered and display the auto-complete control. Here, the user entered Me and the list of suggestions shows one item: Mercedes-Benz since it is the only make that starts with Me.
  • When the user click on an item in the suggestions list, that item’s pyLabel value is used to set the value of the Make property of the ABC-Insurance-Work-Auto instance on the Clipboard.