Example of How to Create Report Definitions in Pega 7

This post shows how a Report Definition rule can used to create reports for case type rules. Common use cases include list-type reports that show case instances and summary-type reports on data gathered during case processing, such as summarizing customer related data such as a chart showing how many customers were serviced in each U.S. state. Pega 7.1.6 was used for all examples.

Summary

  1. Description of Pega 7 Sample Application
  2. Description of the Data Model of the Pega 7 Sample Application
  3. Viewing Instances of a Case Type Rule in the Pega 7 Designer Studio
  4. Creating a List-Type Report for a Case Type Rule in Pega 7
  5. Optimizing Properties for Reporting in Pega 7
  6. Adding Filter Criteria to a List-Type Report in Pega 7
  7. Using a Class Join in a List-Type Report in Pega 7
  8. Creating a Summary-Type Report in Pega 7
  9. Creating a Bar Chart in Pega 7
  10. Creating a Map Chart in Pega 7

Related Posts

A sample application has been created for this post to illustrate how to create reports.

  • The application defines a case type rule called Auto that contains 3 stages.
  • The Auto case represents the process of generating auto insurance quotes based on provided customer data.

Case Designer - Sample application with three stages

The 3 stages of the Auto case type are:

  1. Customer – Collect customer information such as name and address.
  2. Vehicle – Collect vehicle information such as year, make and model.
  3. Quote – Show a 6 month and 12 month quote that is calculated based on the data provided.

When running the Auto case in the Case Manager, the user navigates through these 3 stages and completes the forms shown in the following screen shots to add data to the case instances. An auto insurance quote is generated –based on the collected data– by the application in the last stage.

Stage 1: Collect Customer Information

  • The user collects the customer’s information such as name, age, address and email.
  • At this, point the status of the work item is set to Open.
  • The work item status is stored in a Pega standard property called pyStatusWork
  • This property is inherited from the Work- class.

Case Manager Portal - Create new Auto case, Customer stage

Stage 2: Collect Vehicle Information

  • The user collects information on the vehicle for which to provide an insurance quote.
  • The vehicle information includes the vehicle identification number, year, make, model and so on.
  • The status of the work item is set to Pending at this stage.
  • See Example of Cascading Drop Downs with Linked Class Key Property in Pega 7 for information on how to implement cascading drop-downs for the Make and Model controls.

Case Manager Portal - Create new Auto case, Vehicle stage

Stage 3: Show Quote

  • The application uses the collected information to calculate a 6 and a 12 months insurance quote.

Case Manager Portal - Create new Auto case, Quote stage

  • The insurance quotes are displayed and the work item status is set to Resolved-Completed when the user clicks on Submit.

The class diagram below shows the data model of the Auto case type rule.

  • The classes highlighted in blue are application specific classes that derive from the out-of-the-box abstract Pega classes Data- and Work-Cover.
  • For example, the ABC-Insurance-Data-Customer class derives from Data-Customer, which provides the properties pyCustomerID and pyEmailAddress.
  • It is a Pega best practice to extend out-of-the-box classes and to reuse properties when possible.
  • The ABC-Insurance-Work-Auto class has 2 single page type properties: Customer and Vehicle.
  • The ABC-Insurance-Work-Vehicle class has 1 single page type property that refers to ABC-Insurance-Work-Model.
  • The -Model class has a linked class key reference to -Make for referring to a car make.

Sample Application Data Model UML_Class_Diagram

The Designer Studio can be used to view all instances of a given case type rule.

  • Open the Application Explorer and right click on the case type rule.
  • In the context menu, hover over View and then click on Instances.

Application Explorer View Case Type Instances

  • This action will execute a default list view on the ABC-Insurance-Work-Auto class, showing all instances that have been created.
  • This list view is defined on the Work- class and is named InstanceList ALL.
  • For this example, 32 instances of the ABC-Insurance-Work-Auto case type rule have been created in the system:

Designer Studio View Of Case Type Instances with InstanceList ALL

  • This view is NOT a report definition. It is an out-of-the-box list view defined on the Work- class.
  • The use of custom list views is discouraged and report definitions should be used instead.
  • Alternatively, a tool such as pgAdmin for PostgreSQL can be used to look at the Pega database directly.

Using pgAdmin to view case type instances

In order to create a new list-type report definition:

  • Navigate to the Application Explorer and right click on the case type rule.
  • Select Create+ in the context menu and then Reports > Report Definition.

Designer Studio Create Report Definition from Application Explorer menu

  • In the Create Report Definition form, enter a name for the report definition, here AutoCasesListReport, and select the appropriate app layer and rule set version.
  • The Apply to drop-down should be populated properly with the class name of the case type rule.

Designer Studio Create Report Definition Form

  • Click on Create and open to continue.
  • A simple list-type report can quickly be created by adding columns on the Query tab.
  • In the below example, the following columns have been added:
pyIDthe work item ID such as A-47 – see pyID on Pega Help
pzInsKeythe instance handle key such as ABC-Insurance-Work A-47 – see pzInsKey on Pega Help
pxCurrentStageLabel – the name of the current stage such as Vehicle
pyStatusWork – the work status such as Resolved-Completed – see pyStatusWork on Pega Help
Customer.Lastname – embedded single page of type Customer – see data model in section 2
Vehicle.VehicleIdentificationNumber – embedded page of type Vehicle – see data model in section 2

Designer Studio Edit Report Definition Form - Query Tab

  • Note: The references to the Customer.Lastname and Vehicle.VehicleIdentificationNumber cause a warning message because these properties have not been optimized (see next section for optimization). Clicking on the warning shows more information.
  • Performance: For each result item, PRPC has to decode the BLOB in order to display these properties. This can result in poor performance when processing large result sets.

Designer Studio Edit Report Definition Form - Warning Display Property not optimized

  • At this point, the report definition does not have any filter criteria defined and will retrieve all 32 instances.
  • The report definition can be run by clicking on Action > Run. The results will be shown in a new window:

Designer Studio Edit Report Definition Form - Run report in Report Viewer

  • The width and format of each column can be adjusted by clicking on the gear icon next to a column definition on the Query tab of the report definition.
  • A new dialog allows to specify the width in pixels or as a percentage.

Designer Studio Edit Report Definition Form - Query tab set column formats

  • The column format can be Display Text or other default formats such as number-, percentage or currency formats. Custom formats can be created as well.

In Pega, there are standard properties and custom properties (created by developers). The standard properties have one of the following three prefixes:

px – Special properties whose values are set by PRPC, such as pxCoveredCount for keeping track of sub-cases
py – Pega common out-of-the-box properties for reuse, such as Data-Customer.pyEmailAddress
pz – Used for internal system processing, such as pzInsKey, can be read but not set by the application
  • The standard properties are stored in separate columns in the Pega system database.
  • Custom properties created by users such as the above Customer.Lastname are stored by default in a BLOB type column called pzPVStream. This DB column is also called the storage stream.
  • In order to create performance efficient reporting, custom properties that are part of a report definition need to be optimized.
  • The process of optimizing a property is done in the Designer Studio and causes the creation of a dedicated DB column in the table of the respective class.
  • When a report is executed, PRPC uses the dedicated column instead of examining the storage stream.

Running the Property Optimization Wizard

  • In Designer Studio, navigate to the Application Explorer.
  • Expand the Data Model node of the relevant class and then expand the Property node.
  • Right click on the property that should be optimized and select Optimize for reporting.

Designer Studio - Applicaiton Explorer - Optimize property for reporting

  • The Property Optimization wizard will be launched and guide the user through 3 steps.

Step 1: Properties and Classes

  • On the first step, the property that is to be optimized and the affected class and its Database table are shown. In this example, the class is ABC-Insurance-Work-Auto and the table name is pc_ABC_Insurance_Work in the PegaDATA database, containing 32 instances.
  • Select Now for the Population Schedule at and click on Next to continue.

Designer Studio - Property Optimization Wizard - Properties and Classes Form

Step 2: Properties and Classes

  • Property optimization will cause Pega to create a new column in the table of the class that contains the optimized property.
  • After optimization, the property values will be stored in a new dedicated DB column instead of in the BLOB (see storage stream). Click on Next to start the optimization.

Designer Studio - Property Optimization Wizard - Eligible Classes Form

Step 3: Optimization

  • A confirmation message should indicate that the Optimization started successfully.
  • Clicking on the button Column Population Jobs Dashboard shows the status of the optimization process.

Designer Studio - Property Optimization Wizard - Optimization Form

  • When Now was selected for the population schedule in step 1, the optimization should complete quickly. In the below screen shot, the status Completed indicates that the propery was successfully optimized.

Designer Studio - System-Database - View Column Population Jobs

  • A look at the Pega DB table pc_ABC_Insurance_Work shows that a new column named lastname_1 was created.
  • See this post on how to access the Pega database using a tool such as pgAdmin.
  • The below screen shot shows the 32 instances in the table and the new columns for the  Customer.Lastname and Vehicle.VehicleIdentificationNumber properties (…which was optimized in the same way).

pgAdmin PostgreSQL Peag database - View work object instances

  • When opening the report definition again, the warning message about the properties not being optimized is not shown anymore.

Optimizing is highly recommended for properties that are used in report definition filter criteria. In the below screen shot, a report column and filter condition has been added to query Auto case type instances by model year using Vehicle.Year, so that only instances are retrieved where the model year matches 2016.

Designer Studio - Edit Report Definition - Add Filter Criteria

  • Using this unoptimized property in a filter condition causes 2 warning messages as shown below:

Designer Studio - Edit Report Definition - Add Filter Criteria - Property Optimization Warnings

  • Performance Severe: Using an unoptimized property for a filter criteria causes very poor performance, because PRPC has to decode the BLOB of every row in the DB table in order to examine the property value.
  • Performance Caution: Displaying an unoptimized property in a report may result in poor performance, because PRPC has to decode the BLOB of every item in the result set to extract the property value.

Using Report Definition Parameters

  • After optimizing Vehicle.Year as shown in the previous section, the warnings will disappear.
  • In order to make the report definition more flexible, input parameters should be defined.
  • Switch to the Parameters tab of the report definition rule and add the desired input parameters, for example:

Designer Studio - Edit Report Definition - Add Input Parameters

  • The parameter can be referenced in the filter criteria on the Query tab, instead of using a fixed value.

Designer Studio - Edit Report Definition - Reference Input Parameters on Query Tab

  • The report definition can be run by clicking on Actions > Run.
  • To set a filter value, click on the Filters link in the upper right-hand corner of the Report Viewer.
  • This expands a section that allows to specify the filter value for the model year. Here it is 2016.
  • Click on Apply Changes to refresh the report view.

Designer Studio - Run Report Definition - Set Filter Criteria in Report Viewer

  • If multiple filter criteria are defined on the Query tab, boolean logic can be used to evaluate the filter criteria.

Designer Studio - Edit Report Definition - Multiple Filter Criteria with Boolean Logic

  • In the above example, the filter condition is set to A AND B so that a logical AND is used to select rows where the model year and state match specified parameter values.
  • The below screen shot shows the query results in the Report Viewer when setting the filter criteria to Model Year = 2016 and State = California.

Designer Studio - Run Report Definition - Set Multiple Filter Criteria in Report Viewer

  • At this point, the Save As button is used to save a copy of the report definition for the creation of a new report that will show the make and model for each Auto case type instance.
  • See the data model shown in the UML class diagram in section 2. Obtaining the make and model names requires the use of class joins.

  • According to the data model described in section 2 (see UML class diagram), the Auto case type rule has a single page property called Vehicle with a page definition of ABC-Insurance-Data-Vehicle which has a single page property called Model for storing the car model.
  • The page definition of the Model property is ABC-Insurance-Data-Model and this class has a property called make which refers to class keys of ABC-Insurance-Data-Make instances.
  • Note: See Example of Cascading Drop Downs with Linked Class Key Property in Pega 7 on this blog for details on how the make and model data is stored using data tables and a linked class key property.
  • In relational database terms, the make property is a foreign key to car makes.

Designer Studio - Edit Property - Set Automatic reference to class instances (linked) under Data Access

  • When an Auto case type instance is populated with data, the Model property stores the key of the car model in Model.id and the key of the make in Model.make.
  • The actual names such as "Honda" and "Accord" are NOT stored in the Auto case instances.
  • The make and model keys and actual names are stored in data tables as shown below.
  • For example, the car model instance MO014 refers to the make instance, M-4 with a value of Mercedes-Benz.

Designer Studio - Data Tables for Car Make and Car Model

  • The below screen shot shows a modified list-type report that shows customers in California. The report includes the car make and model key values.

Designer Studio - Run Report Definition - Add columns for instance keys

  • Running the report shows California customers and the make and model keys of their vehicles.

Designer Studio - Report Viewer - Filter Criteria for U.S. State

  • Displaying the make and model class keys in a report is not useful to users, so class joins are needed to look-up the actual make and model names.
  • In the report definition, switch to the Data Access tab. Click on Add class join and set a prefix and select the class name.

Designer Studio - edit Report Definition - Data Access Tab Add Class Join for Car Make

  • Click on the button Edit conditions and configure the filter condition to link the Vehicle.Model.make property to class keys in the ABC-Insurace-Data-Make table.

Designer Studio - edit Report Definition - Data Access Tab Filter Condition for Car Make

  • Another class join is added the same way to retrieve model names:

Designer Studio - edit Report Definition - Data Access Tab Add Class Join for Car Model

  • The filter condition links the Vehicle.Model.id to the .id property in the ABC-Insurance-Data-Model class which is prefixed with ModelTable in the class joins section.

Designer Studio - edit Report Definition - Data Access Tab Filter Condition for Car Model

  • On the Query tab, the columns that refer to the make and model keys are replaced with the prefixes for the make and model data classes specified on the Data Access tab.
  • Each class has an inherited property pyLabel that holds the actual make or model name.

Designer Studio - Edit Report Definition - Query Tab - Add Columns for Car Make and Model names

  • Running the report now shows the actual make and model names instead of class keys:

Designer Studio - Report Viewer - Show Columns for Car Make and Model names

  • If a warning message indicates that a property used in a class join is not optimized, the report definition will not run properly and an error message will be shown.
  • Make sure to optimize properties used in class joins.

  • A summary-type report is used to summarize a given property. For example, to count or to obtain min. and max. values.
  • In this example, a summary-type report is used to show the number of Auto case type instances for each U.S. state.
  • A new report definition called AutoCaseSummaryReport was created. The Query tab of the summary-report definition contains 2 columns as shown below:

Designer Studio - Edit Report Definition - Summary Report - Query Tab - Customers per State

  • Selecting Count in the SUMMARIZE drop-down, results in a GROUP BY query that will count the number of pzInsKey values for each value of Customer.State.
  • When the report is run, it will show one row for each U.S. State and the number of Auto case type instances for each one.

Designer Studio - Report Viewer - Summary Report - Query Tab - Customers per State

  • Similarly, a summary-type report can be used to show the premium totals (i.e. auto insurance policy revenue) for each state. Here, the Sum option is selected in the SUMMARIZE drop-down.

Designer Studio - Edit Report Definition - Summary Report - Query Tab - Total Premiums per State

  • Note: The second column has been configured (…click on gear icon) to use a currency formatter.

Designer Studio - Report Viewer - Summary Report - Total Premiums per U.S. State

  • Summary-type reports are needed for creating bar charts and map charts.

  • A bar chart is created based on a summary-type report. For this example, the summary-type report from the previous section (which shows the insurance premium totals per U.S. state) is used.
  • The bar chart shows the U.S. states on the x-axis and the total premiums of auto policies in each state on the y-axis.
  • On the existing summary-type report definition, here called AutoCaseSummaryReport, switch to the Chart tab.
  • Click on the Include Chart button. Drag and drop the aggregate property column on the y-axis, in this case the Total Premiums column.
  • The State column needs to be dragged to the x-axis so that a bar is shown for each U.S. state.

Designer Studio - Edit Report Definition - Chart Tab - Bar Chart

  • The gear icon next to the chart’s column names can be used to configure formatting:

Designer Studio - Edit Report Definition - Chart Tab - Bar Chart Formatting

  • For the Total Premiums column, the default US Currency format is selected and configured to not display any decimal places.

Designer Studio - Edit Report Definition - Chart Tab - Bar Chart Formatting for Currency

  • The General Settings link on the Chart tab can be used to set the text size
  • The Color Settings link can be used to define conditional coloring of the bars based on the Total Premium column values. In the below example, three conditional colors have been defined:

Designer Studio - Edit Report Definition - Chart Tab - Conditional Colors for Bar Chart

  • The chart can be viewed by running the report definition via Actions > Run.

Designer Studio - Report Viewer - Bar Chart for Total Premiums per U.S. State

  • When hovering over a bar, a tool tip shows the actual value. The tool tip section can be customized as well.

The same AutoCaseSummaryReport summary-type report can be used to create a map chart to show the total premiums for each U.S. State on a geographical map.

  • Open the report definition and navigate to the Chart tab and click on the All Chart types link.
  • This link opens a new dialog that shows all available chart types.

Designer Studio - Report Definition - Chart Tab - All Chart Types

  • In the Select Chart Type modal dialog, click on the Map icon.

Designer Studio - Report Definition - Chart Tab - View All Chart Types

  • The main Chart tab area will show a symbolic map with the Total Premiums column on the y-axis and the State column on the x-axis.
  • The values of the x-axis will be mapped to the U.S. states on the map.
  • Note: At this point, a warning message will appear since the State column values have not been properly mapped to the map chart values for U.S. states.

Designer Studio - Edit Report Definition - Map Chart - Total Premiums per U.S. State

  • Clicking on the warning message will show the following modal dialog indicating that the Group By column values need to be linked correctly to the regions or areas of the selected map:

Designer Studio - Edit Report Definition - Map Chart Warning Group By column values need to be linked to map areas

  • Navigate to Reporting > Settings > Map in order to configure the map for U.S. states:

Designer Studio - Navigate to Reporting - Settings - Maps

  • On the map settings page, select the USA By State map from the Map type drop-down and specify the class.
  • In this case, the class is ABC-Insurance-Work-Auto. Once the class is selected, the table showing the MAP REGION and PROPERTY VALUE mappings should be updated automatically as shown in the screen shot below (…here the state names already match).

Designer Studio - Reporting Settings for Map USA By State

  • Click on the Save button and navigate back to the report definition for the map chart and select the correct map name in the Map drop-down control. Here, the map’s name is USA By State.

Designer Studio - Map Report Definition - Set map chart USA By State

  • Click on Save and run the map chart by clicking on Actions > Run.
  • Hovering over a U.S. state shows a tool tip section which can be customized.
  • The conditional color settings configured for the bar chart earlier, are applied to the map areas.

Designer Studio - Map Chart - Run map chart USA By State for Total Premiums per U.S. State

How to Delete Case Type Instances in Pega 7 with an Activity

This example shows how the Designer Studio can be used to view case type instances and how an Activity can be used to delete case type instances from the PRPC database in Pega 7. The activities in this tutorial will use the Obj-Delete-By-Handle and Obj-Browse methods to either delete single instances or multiple instances. Note that case type instances should not be deleted this way in a production environment. Please refer to the Purge and Archive Wizards for information on how to delete and archive old work on production systems.

Related Posts

Summary

  1. View Instances of Case Type Rule in the Pega 7 Designer Studio or DB Tool such as pgAdmin
  2. Delete a Single Case Type Instance by Handle with Obj-Delete-By-Handle
  3. Delete Multiple Case Type Instances with Obj-Browse and Obj-Delete-By-Handle

For this example, a case type called Auto has been created to capture the processes needed for providing auto insurance quotes to customers. The Auto case consists of 3 stages as shown in the screen shot below. Customer and vehicle information is collected and used to calculate an auto insurance quote. When running the case type rule, new instances are created and stored in the PRPC database.

Case Designer Auto Case Type Stages

The Designer Studio can be used to view all instances of a given case type rule. Navigate to the Application Explorer and right click on the case type rule. In the context menu, hover over View and click on Instances as shown in the screen shot below.

Case Designer open Application Explorer and View Case Type Instances

A list type report will execute and show all instances of the case type rule. In this example, there are 44 instances of the ABC-Insurance-Work-Auto case type rule. The list report shows the unique instance names, when the instances where last updated and by what operator. In the below example, the instance names are A-2, A-3, A-4 and so on. An instance name is automatically generated by PRPC when a new case type instance is created.

Case Designer View Instances of Case Type Rule

It is also possible to use an external database client to view the case type instances. In this case, PRPC is using PostgreSQL for the database. For detailed instructions on how to use the pgAdmin client for connecting to and viewing the PRPC database, please refer to this blog post. The pgAdmin client can be used to look at the Auto case type instances stored in a database table in the PegaDATA schema.

In order to identify the table name, open the Auto class in the Designer Studio by navigating to the Application Explorer and expanding the case type rule. Next, expand the SysAdmin item and then expand the Class item and click on the actual class name of the case type rule to open the Edit Class form. Here, the class name is ABC-Insurance-Work-Auto and the class group name is ABC-Insurance-Work.

Designer Studio Edit Class Test Connection ABC-Insurance-Work-Auto

On the Edit Class form, scroll down and click on the button Test Connection. A new dialog will pop up and show the actual table name in the PegaDATA schema. In this case, since the class belongs to a class group, the instances are stored in a table for the class group class. In this example, the table name is: pc_ABC_Insurance_Work.

Class Test Connection ABC-Insurance-Work-Auto

The external DB tool, such as pgAdmin in this example, can be used to navigate the PegaDATA schema schema and open the pc_ABC_Insurance_Work table to view the case type instances.

pgAdmin navigate PRPC database schemas

In pgAdmin, right clicking on a table name allows to view the rows in that table. The below screen shot shows the instances of ABC-Insurance-Work-Auto:

pgAdmin view ABC-Insurance-Work-Auto instances in PegaDATA

An activity can be used to delete a single case type instance by its handle. To create a new activity for this purpose, right click on the case type rule in the Application Explorer and hover over +Create and then Technical and click on Activity.

Application Explorer Create new Activity

The Create Activity form will be loaded. Enter a meaningful label and leave the Apply to class so that it matches the case type rule for which instances should be deleted. Select a ruleset and click on the Create and open button.

Designer Studio Create New Activity Form

Parameters tab: On the Edit Activity form, navigate to the Parameters tab and add a mandatory input parameter instanceHandle (i.e. ID) that will hold an instance handle and then click on Save.

Application Explorer Edit Activity Parameters Tab

Steps tab: On the Steps tab, add a step that calls the method Obj-Delete-By-Handle. Expand the method and set the InstanceHandle method parameter by referring to the input parameter created earlier. Also check the checkboxes Lock, ReleaseOnCommit and Immediate to obtain a lock for the instance that is to be deleted and to commit the database operation immediately.

Edit Activity Steps Tab Obj-Delete-By-Handle

Security tab: On the Security tab, check the option Allow direct invocation from the client or a service so that the activity can be run directly in the Designer Studio.

Edit Activity Security Tab

Save the activity and unit test it by clicking on Actions > Run. Enter the instance handle on the test page. The instance handle is a string composed of the class group name and the instance name. Note that the Auto class belongs to class group ABC-Insurance-Work.

For example, the instance handle for the Auto case type instance with the name A-2 is ABC-Insurance-Work A2. Click on Execute to run the activity.

Run Activity Test Page

A confirmation message will indicate that the activity executed successfully. Use the methods described earlier to view the instances of the Auto case type rules and confirm that the instance has been deleted from the database.

Run Activity Confirmation Page

Instead of deleting a single case type instance by handle, multiple instances can be deleted as well. In this example, all instances that have not been updated since a given data time are deleted. The below screenshot shows the instances again, ordered in descending order by UPDATED ON property. There are a total of 43 instances.

The activity should delete all instances that have not been updated since 9:00 AM May 5th, 2016. In the below example, 27 instances would be deleted because the UPDATED ON property of the top 16 instances is greater than 9:00 AM May 5th, 2016.

Designer Studio View Instances of Case Type ABC-Insurance-Work-Auto

Create a new Activityin the same way as before:

Application Explorer View Case Type Instances

Give the new activity an appropriate label:

Designer Studio Create new Activity form

Click on Create and open and navigate to the Pages and Classes tab and add a page of type Code-Pega-List. Here, the page name is AutoCaseList

Edit Activity Pages And Classes Tab

Security tab: As before, check the option Allow direct invocation from the client or a service so that the activity can be unit tested. Save the changes and navigate to the Steps tab.

Edit Activity Security Tab

Steps tab: On the Steps tab, add a step that calls the Obj-Browse method and in the PageName field, enter the name of the Code-Pega-List page defined on Pages and Classes, in this case it is AutoCaseList. Also set the name of the class in the ObjClass field, here it is ABC-Insurance-Work-Auto.

  • The Obj-Browse method allows to set filter criteria. Here, we want to retrieve all instances where the UPDATED ON date is less than 9:00 AM May 5th, 2016.
  • The corresponding property is called pxUpdateDateTime. The condition is set to Is Less Than and the value is a DateTime string of the format YYYYMMDDTHHMMSS.QQQ.
  • According to that pattern the string for 9:00 AM May 5th, 2016 is "20160505T090000.000".
  • Save the activity and trace its execution by clicking on Actions > Trace and then run it by clicking on Actions > Run.

Edit Activity Run Activity

  • In this example, the Tracer will show 27 instances that match the Obj-Browse query with the filter on the last updated date.

Run Activity and view in Tracer

  • In order to delete these instances, add a loop step in the activity as shown below.
  • When clicking on the Loop button in a step, a dialog pops up.
  • Select For Each Embedded Page in the Repeat drop down and specify the class of the items in the page list, in this case it is ABC-Insurance-Work-Auto.

Edit Activity Add Loop Step For Each Embedded Page

  • Set the method to Obj-Delete-By-Handle and the step page to the page that holds the results of the Obj-Browse method and refer to pxResults, which is a list of the actual case type instances.
  • In this case, the step page for the iteration is AutoCaseList.pxResults. Check the method parameters Lock, ReleaseOnCommit and Immediate.
  • Most importantly, set the InstanceHandle dynamically using the pzInsKey value of each instance item.

Edit Activity Add Loop Step Obj-Delete-By-Handle

  • Save the changes and run the activity by clicking on Actions > Run and then on Execute on the activity test page.

Run Activity Execute Activity Test Page

  • A confirmation message will indicate that the activity was executed successfully, but returned no data.

Run Activity execution confirmation page success

  • Use the Designer Studio to view the instances again. In this case, 27 out of the original 43 instances have been deleted and only 16 instances remain in the PRPC database.

Application Explorer View Case Type Instances after delete 16 remaining

Please register and leave comments or suggestions on how to improve this example!

Creating a SOAP Web Service in Java with Eclipse IDE and Tomcat

In this example, the Eclipse Java EE IDE is used to create a new SOAP 1.1 web service. The Apache Tomcat web server is used to deploy and run the web service and SOAP-UI is used to test the service operations. The SOAP 1.1 web service in this example represents a simple product catalog and provides methods to search and insert products.

Related Posts

Summary

  1. Installation of Eclipse Java EE IDE
  2. Installation of Apache Tomcat 7 Web Server
  3. Configuration of Tomcat 7 Runtime Environment in Eclipse
  4. Setup of new Dynamic Web Project in Eclipse
  5. Setup of Service Implementation Java Class
  6. Setup of new SOAP 1.1 Web Service in Eclipse
  7. Testing the new SOAP Web Service with SOAP UI
  8. Creating a WAR File for Deployment of the SOAP Service

Software Downloads

The open-source software used in this example can be downloaded from these sources:

Java Runtime Environment from Oracle (e.g version 8, update 111)
Apache Tomcat Web Server (here version 7)
Eclipse Java EE IDE from the Eclipse Downloads page (here Kepler SR2)
SOAP-UI from the SOAP-UI open source downloads

Eclipse Java EE IDE for Web Developers - About

  • The Eclipse IDE is packaged as a ZIP file. After downloading the file, unzip it to a folder on your hard drive.

Eclipse Java EE IDE for Web Developers - ZIP file

  • In this case, Eclipse is installed in: C:\eclipse-jee-kepler.
  • After unzipping the file, the folder should contain the files shown below.
Note: Make sure that you have a Java Runtime Environment (JRE) installed before trying to run Eclipse.

Eclipse Java EE IDE for Web Developers - root folder

  • Run Eclipse by clicking on the application icon as shown in the screen shot.

  • Visit https://tomcat.apache.org/index.html and download the Apache Tomcat Web Server. For this example, version 7 was used.
  • It is recommended to download the binary distribution for your operating system (e.g. Windows 7 32-bit), which provides a ZIP file.
  • Unzip the downloaded file to a folder on your hard drive, for example to C:\tomcat7. The Tomcat 7 root folder should look like this:

Apache Tomcat 7 - Root folder

  • Start the Eclipse IDE by clicking on the Eclipse application icon shown earlier.
  • In Eclipse, navigate to: Window > Preferences.

Eclipse Java EE IDE for Web Developers - Preferences

  • In the Preferences dialog window, extend the Server node and click on Runtime Environments.
  • Then click on the Add… button to add a new runtime environment.

Eclipse Java EE IDE for Web Developers - Server Runtime Environments

  • In the New Server Runtime Environment dialog, select Apache Tomcat v7.0 and click on Next.

Eclipse Java EE IDE for Web Developers - New Server Runtime Environment

  • On the following screen, use the Browse… button to select the root folder of the Tomcat web server.
  • This is the folder into which the Tomcat ZIP file was unzipped. It contains the bin folder.

Eclipse Java EE IDE for Web Developers - Select Tomcat Installation Directory

  • Click on Finish to complete the runtime environment setup. The Apache Tomcat v7.0 web server should now be listed in the Server Runtime Environments screen.

Eclipse Java EE IDE for Web Developers - Available Server Runtime Environments

  • Click on OK to close the runtime environment setup.

  • In the Eclipse IDE, navigate to the main menu and click on File > New > Dynamic Web Project.
  • In the configuration screen, enter the project name and select the target runtime.
  • In this case, the target runtime will be the previously configured Apache Tomcat v7.0 web server.
  • Click on Finish to complete the setup.

Eclipse - New Dynamic Web Project

  • The new dynamic web project should now show up in the Project Explorer in the Eclipse IDE as shown below:

Eclipse Java EE IDE for Web Developers - Project Explorer with Dynamic Web Project

  • Right click on the project name and select New > Class in the context menu to create a new Java class that will serve as the implementation class for the web service.

Eclipse Java EE IDE for Web Developers - Create a new Java Class

  • Select an appropriate package name and complete the name of the class. Then click on Finish and open the class in the Java editor.
  • For this example, the ProductCatalogServiceImpl Java class provides 3 methods and maintains a simple product catalog as an in-memory list:
package com.pegaxchange.services;

import java.util.*;

public class ProductCatalogServiceImpl {

    private static List<Product> productCatalog;

    public ProductCatalogServiceImpl() {
        initializeProductCatalog();
    }

    public Product searchById(int id) throws Exception {
        for (Product p : productCatalog) if (p.getId() == id) return p;
        throw new Exception("No product found with id " + id);
    }

    public Product[] getAllProducts() {
        Product[] products = new Product[productCatalog.size()];
        int i = 0;
        
        for (Product p : productCatalog) {
            products[i] = p;
            i++;
        }
        
        return products;
    }
    
    public void insertProduct(Product product) {
        productCatalog.add(product);
    }

    private void initializeProductCatalog() {

        if (productCatalog == null) {
          productCatalog = new ArrayList();
          productCatalog.add(new Product(1, "Keyboard", "Electronics", 29.99D));
          productCatalog.add(new Product(2, "Mouse", "Electronics", 9.95D));
          productCatalog.add(new Product(3, "17\" Monitor", "Electronics", 159.49D));
          productCatalog.add(new Product(4, "Hammer", "Hardware", 9.95D));
          productCatalog.add(new Product(5, "Slot Screwdriver", "Hardware", 7.95D));
          productCatalog.add(new Product(6, "The British Invasion of Java", "Books", 11.39D));
          productCatalog.add(new Product(7, "A House in Bali", "Books", 15.99D));
          productCatalog.add(new Product(8, "An Alaskan Odyssey", "Books", 799.99D));
          productCatalog.add(new Product(9, "LCD Projector", "Electronics", 1199.19D));
        }
    }
}

The 3 public methods in the class are:

  • searchById – Returns the product with the given id
  • getAllProducts – Returns a list of all products
  • insertProduct – Adds a new product to the product catalog list object

Note: The initializeProductCatalog method is called in the constructor and creates an in-memory ArrayList of Product objects. In reality, the product catalog would be backed by a database or some other system of record. In addition, a Java bean class that represents a product in the catalog was created:

package com.pegaxchange.services;

public class Product {

    private int id;
    private String name;
    private String category;
    private double unitPrice;

    public Product() {}

    public Product(int id, String name, String category, double unitPrice) {
        this.id = id;
        this.name = name;
        this.category = category;
        this.unitPrice = unitPrice;
    }

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getCategory() {
        return category;
    }

    public void setCategory(String category) {
        this.category = category;
    }

    public double getUnitPrice() {
        return unitPrice;
    }

    public void setUnitPrice(double unitPrice) {
        this.unitPrice = unitPrice;
    }
}

  • In the Eclipse main menu, click on File > New > Other.
  • In the Wizard dialog, expand the Web Services node, select Web Service and click on Next.

Eclipse Java EE IDE for Web Developers - New Web Service Wizard

  • On the Web Services wizard screen, select Bottom up Java bean Web Service for the web service type and use the Browse button to select the service implementation class.
  • In this case it is the com.pegaxchange.services.ProductCatalogServiceImpl Java class created in step 5.
  • In the configuration section, leave the slider at the Start level. This will configure Eclipse to automatically deploy and start the web service on the Apache Tomcat v7 runtime.
  • Omit the client configuration for now and make sure the option Publish the Web service is checked. Click on Next to continue.

Note: Under Configuration:, the entry Web service runtime: Apache Axis refers to Axis version 1.4 which generates SOAP version 1.1 web services.

Eclipse Java EE IDE for Web Developers - New Web Service Configuration

  • The next screen lists the name of the WSDL file that will be created and the public methods available in the service implementation class that can be exposed through the SOAP web service.
  • The document type can be set on this screen as well.

Eclipse Java EE IDE for Web Developers - Web Service Java Bean Identity

  • Click on Next to continue. The Eclipse IDE will now generate the web service files. If the Apache Tomcat web server is NOT running at this point, the following Server startup screen will be shown:

Eclipse Java EE IDE for Web Developers - Tomcat Server Startup

  • Click on the Start server button to start the web server and then click on the Next button and after the service has been deployed, click on the Finish button to close the Web Service wizard.
  • The service should now be up and running on the local Tomcat web server as shown below.

Eclipse Java EE IDE for Web Developers - Tomcat v7.0 Server at localhost running

  • Confirm that the WSDL file is accessible by navigating to the following URL in a web browser:
https://localhost:8080/ProductCatalogSOAPService/services/ProductCatalogServiceImpl?wsdl

Product Catalog SOAP Web Service - Access WSDL via URL

  • Note that the namespace of the generated WSDL is https://schemas.xmlsoap.org/wsdl/soap, which indicates a SOAP 1.1 compliant web service.
  • For more information on SOAP 1.1 vs. 1.2 see this post on W3C.
  • For completeness, here is the entire WSDL file for the ProductCatalogSOAPService that was generated by Eclipse:
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="https://services.pegaxchange.com" 
    xmlns:apachesoap="https://xml.apache.org/xml-soap" 
    xmlns:impl="https://services.pegaxchange.com" 
    xmlns:intf="https://services.pegaxchange.com" 
    xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/" 
    xmlns:wsdlsoap="https://schemas.xmlsoap.org/wsdl/soap/" 
    xmlns:xsd="https://www.w3.org/2001/XMLSchema">
  <!--WSDL created by Apache Axis version: 1.4 Built on Apr 22, 2006 (06:55:48 PDT)-->
  <wsdl:types>
    <schema elementFormDefault="qualified" 
        targetNamespace="https://services.pegaxchange.com" 
        xmlns="https://www.w3.org/2001/XMLSchema">
      <element name="searchById">
        <complexType>
          <sequence>
            <element name="id" type="xsd:int"/>
          </sequence>
        </complexType>
      </element>
      <element name="searchByIdResponse">
        <complexType>
          <sequence>
            <element name="searchByIdReturn" type="impl:Product"/>
          </sequence>
        </complexType>
      </element>
      <complexType name="Product">
        <sequence>
          <element name="category" nillable="true" type="xsd:string"/>
          <element name="id" type="xsd:int"/>
          <element name="name" nillable="true" type="xsd:string"/>
          <element name="unitPrice" type="xsd:double"/>
        </sequence>
      </complexType>
      <element name="insertProduct">
        <complexType>
          <sequence>
            <element name="product" type="impl:Product"/>
          </sequence>
        </complexType>
      </element>
      <element name="insertProductResponse">
        <complexType/>
      </element>
      <element name="getAllProducts">
        <complexType/>
      </element>
      <element name="getAllProductsResponse">
        <complexType>
          <sequence>
            <element maxOccurs="unbounded" name="getAllProductsReturn" type="impl:Product"/>
          </sequence>
        </complexType>
      </element>
    </schema>
  </wsdl:types>
  <wsdl:message name="insertProductResponse">
    <wsdl:part element="impl:insertProductResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="getAllProductsRequest">
    <wsdl:part element="impl:getAllProducts" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="searchByIdRequest">
    <wsdl:part element="impl:searchById" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="getAllProductsResponse">
    <wsdl:part element="impl:getAllProductsResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="searchByIdResponse">
    <wsdl:part element="impl:searchByIdResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="insertProductRequest">
    <wsdl:part element="impl:insertProduct" name="parameters"/>
  </wsdl:message>
  <wsdl:portType name="ProductCatalogServiceImpl">
    <wsdl:operation name="searchById">
      <wsdl:input message="impl:searchByIdRequest" name="searchByIdRequest"/>
      <wsdl:output message="impl:searchByIdResponse" name="searchByIdResponse">
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="insertProduct">
      <wsdl:input message="impl:insertProductRequest" name="insertProductRequest"/>
      <wsdl:output message="impl:insertProductResponse" name="insertProductResponse"/>
    </wsdl:operation>
    <wsdl:operation name="getAllProducts">
      <wsdl:input message="impl:getAllProductsRequest" name="getAllProductsRequest"/>
      <wsdl:output message="impl:getAllProductsResponse" name="getAllProductsResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="ProductCatalogServiceImplSoapBinding" type="impl:ProductCatalogServiceImpl">
    <wsdlsoap:binding style="document" transport="https://schemas.xmlsoap.org/soap/https"/>
    <wsdl:operation name="searchById">
      <wsdlsoap:operation soapAction=""/>
      <wsdl:input name="searchByIdRequest">
        <wsdlsoap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="searchByIdResponse">
        <wsdlsoap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="insertProduct">
      <wsdlsoap:operation soapAction=""/>
      <wsdl:input name="insertProductRequest">
        <wsdlsoap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="insertProductResponse">
        <wsdlsoap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="getAllProducts">
      <wsdlsoap:operation soapAction=""/>
      <wsdl:input name="getAllProductsRequest">
        <wsdlsoap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="getAllProductsResponse">
        <wsdlsoap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="ProductCatalogServiceImplService">
    <wsdl:port binding="impl:ProductCatalogServiceImplSoapBinding" 
         name="ProductCatalogServiceImpl">
      <wsdlsoap:address 
         location="https://prpc:8080/ProductCatalogSOAP11/services/ProductCatalogServiceImpl"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

There are many options for testing a SOAP web service, including generating a test client in Eclipse. In this example, a free external tool called SOAP-UI is used to test the web service operations.

Note: Make sure that the Tomcat web server is running at this point and that the web service is deployed as described in step 6, where the service’s WSDL file is accessed in a browser.

SOAP UI - New SOAP Project

  • A new dialog window prompts for the project name and the WSDL file.
  • In this case, the URL shown earlier is copied into the Initial WSDL field:
https://localhost:8080/ProductCatalogSOAPService/services/ProductCatalogServiceImpl?wsdl
  • Check the ckeckbox Create sample requests for all operations? is checked and click on OK.

SOAP-UI - New SOAP Project from WSDL

  • SOAP-UI will automatically download the WSDL, process it and create request stubs for each service operation.
  • In order to call one of the operations of the web service, double click on the Request 1 item under that operation.
  • Then click on the green triangle inside the request window to run the request.
  • E.g.: calling the operation getAllProducts results in the following request and response XML.

SOAP UI - Execute Sample request getAllProducts

  • Similarly, calling the operation insertProduct results in the following request and response XML.

SOAP UI - Execute Sample request insertProduct

  • Calling the operation searchByID results in the following request and response XML.

SOAP UI - Execute Sample request searchById

  • A WAR file (Web Archive) can be created by exporting the dynamic web project in Eclipse.
  • The WAR file is used to deploy the SOAP web service to a Jave EE compliant application server.
  • In the Eclipse IDE, in the Project Explorer, right click on the node for the dynamic web project
  • Select Export > WAR file to launch the WAR Export dialog.

Eclipse IDE - Project Explorer - Export Dynamic Web Project as WAR file

  • In the WAR Export dialog, select the Destination using the Browse button and then click on Finish to complete the WAR export.

Eclipse IDE - Project Explorer - Export Dynamic Web Project as WAR file - Select Destination Directory

  • The generated WAR file will be copied into the specified destination directory:

Eclipse IDE - Generated WAR file