Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Change Policy Address Microjourney

Updated on August 7, 2023

These topics describe how to configure and extend the Change Policy Address Microjourney™, which is part of the Pega Customer Service™ for Insurance application. When the policy update process requires sales rep assistance, this microjourney also connects to Pega Sales Automation™ for Insurance.

Business value

The Change Policy Address Microjourney enables insurance policyholders to easily update an address online or through a representative, and to have changes propagate to multiple policies. This Microjourney, or use case, enables insurance companies to manage retention risk by providing immediate information about premium changes to customers who change an address. Additionally, it allows customers and companies to manage updates to multiple policies with one interaction.

Pega Customer Service for Insurance offers a best-in-class self-service interaction that allows customers to quickly and easily change their address online, which improves customer satisfaction and decreases costs for insurance carriers. 

Personas, channels, and use cases

The following table shows the personas and channels for each use case in this Microjourney.

Persona (Actor)ChannelUse case
CustomerSelf-service websiteUpdate a home or mailing address for one or multiple policies at one time in less than five minutes. 
Customer service representative (CSR)Assisted channel through the Interaction portalWith one interaction, support customers who need to change a home or mailing address for one or more policies.
Sales representativeAssisted channel through the Sales rep portalSupport and retain customers who don’t understand rate changes or want advice on policy changes that are required due to an address change.

Customer self-service website example

Insured customers can log in to the insurance self-service portal and change their address. The Change Address case appears in the insurance carrier’s self-service portal, allowing for quick and easy updates to home or mailing addresses for one or more policies. 

Select reason for changing address

After selecting the type of address change, select the policy or policies you want to update.

Select policy


Because an address change may impact the policy rate, you immediately see the details and can accept the new rate. The following figure shows the an update to the policy rate that does not require sales rep assistance.

Policy quote based on address change


After accepting, you see a page that confirms the changes.

Address & policy change comfirmation


Sales rep assistance example (alternate path)

In this microjourney, an alternate path is that the customer requests assistance from a sales rep. If the customer contact record is shared by both the Pega Customer Service for Insurance application and the Pega Sales Automation for Insurance application, then the Quote screen includes a Contact your agent link. The customer clicks the link, enters a description of their issue, and then selects how they want to be contacted, by email or phone.

Contact your agent link and related fields


The sales agent receives a notification about the customer request, in the notification format they have selected in their preferences (for example, a push notification on their mobile phone) The notification includes the description entered by the customer and the customer information (email or phone number) from their contact record.

Mobile notification example


Clicking the contact details either calls the contact or opens the email composer window.

Email reply example


Clicking the notification opens the contact record so that the sales rep can view all of the contact information.

Stages and steps

The project team can modify and extend this Microjourney in App Studio, allowing business users to Build for Change™. This screen capture shows the stages and steps in the Microjourney.

Stages and steps for Change Policy Address


Data model

The data model refers to a set of rules that work together to populate the data in your application. This data is displayed on the user interface, which can help users process cases and automate business decisions. Quickly understand and update your data model by using the visual data model tool in App Studio. View your application's data model, see how its entities are related, update and delete fields, and add fields to the model without exiting the visual data model. You can find the visual data model for the Change address case type within App Studio.  

View and export the data model

  1. Log in as the csinsurancesysadmin operator.
  2. Open App Studio.
  3. From the navigation pane, click Case types > Change address.
  4. Click the Data model tab.
  5. Click View data model.
Data model


  1. To export the data model, click Actions menu > Export data model.
  2. Select the output format (Excel or Word), and then click Generate.
  3. When the document is complete, click Download to download the document.
Download data model

 View external data entities

To access external data entities within Dev Studio, go to Configure > Data Model > View external data entities. The following figure shows the external data entities.

External Data Entities


Enabling the Microjourney

Extension Points

We have designed the Change address case with common insurance scenarios. Extension points allow you to get up and running as quickly as possible and to maximize time-to-value. Extension points also allow carriers to quickly and easily upgrade, thus reducing future maintenance costs.

Most policy details are sourced from an external policy administration system.  Extension points related to policies in the case design can fetch policy details, contact details of the policy, and household member details related to the policyholder. Extension points can also extend to other lines of business if you intend to expand beyond auto, life, and travel. The highlighted steps in the figure below show the extension points that require configuration.

Steps with extension points


Extending email and SMS notifications for Pega Customer Service for Insurance

When a customer initiates a change of address, a customer notification is sent to ensure that the policyholder initiated the change.  A confirmation is also sent when the address change is complete

Steps to modify to extend Email and SMS notifications


Data page D_RecipientList is an editable page of class PegaIns-Data-Party-Person, which includes the recipients who are notified about the policy address change.

  • The results should be comma-separated value set in Recipient property which would be sent as a parameter to the Send email utility.
  • SendSimpleEmail application-provided activity is used to send emails to multiple recipients.
  • Comma-separated value of recipients from the data page will be set to Param.To as in parameter for SendSimpleEmail.
  • Notifycustomer flow has SendEmail and SendSMS utilities using application-provided activities to send emails to multiple recipients.

Extension points for email and SMS notifications

  • Extend the data page by replacing the source to fetch the email address and contact number from the external system in the highlighted field in the following figure.
  • Extend the data transform CreateRecipientList to customize the logic to fetch email address/list of recipients from the external system and form a comma separated value.
Extend the data transform

Replace the source of the data page in App Studio as described in the following steps:

  1. From the navigation pane of App Studio, click Data > Data types and integrations.
  2. Click the simulated source system and update with the server name and details that your company uses.
Extending extension points


Extending contact details

In most implementations, Pega is not the system of record related to policyholder contact information. This section shows how to integrate, retrieve, and display the contact information from an external system. 

Steps to edit to extend Contact details


Data page D_contact_details of class PegaCA-Interface-Contact s used to fetch contact details such as address, effective date for address change, email address, and contact number.

  • CustomerID is the mandatory parameter for this data page to fetch the details of that specific customer.
  • Whenever a user wants to display any details related to the customer such as their mailing address on the UI in the flow, this data page can be extended and used for the same.
  • Address lines, name, gender, DOB and change address effective date will be used to display the contact details.

Extension Points for contact details

  • Contact details are fetched from Contact_SOR,which can be an internal or external source.
  • If the source is external, extend the integration point by replacing the source.
  • Steps to replace the source from App Studio are shown in the following figure.
Steps to replace the source - Contact details
Double-click the image to enlarge it.


The expected output is shown in the following figures:

Extension point contact details


Contact details (continued)


Extending household members

An integration point allows address updates for one, multiple, or all household members. For example, an entire household might be moving or one member might be moving and taking a vehicle to college. 

Steps to edit to extend household members

Data page D_HouseholdMembers of class PegaIns-Data-Party-Person populates the list of the insured members of the policyholder, in case insured individuals require different addresses.

  • ContactID is a required parameter for this data page. Based on the contactID, the related household members are retrieved for each contact within the household.

Extension points for household members

  • Add external integration source for D_HouseholdMembers data page to source it from an external system as shown in the following figure.
  • Extend the data transform SetHouseholdMembers to customize the logic.
  • Steps to replace the source from App Studio are shown in the following figure:
Steps to replace the source - Household members
Double-click the image to enlarge it.


Expected output from data page D_Household_Members

The expected structure of the response from the data page is shown in the following figure.  

Response structure - Household members


Extending policy details

Typically, a policy admin system outside of Pega is the system of record for policy details.  A policy integration point exists to retrieve policy details. 

Steps to modify to extend Policy details


The Data PageD_Policy_Details in class PegaIns-Interface-InsurancePolicy is used to retrieve the details related to the policy.The data page contains policy details such as policy type, billing details, and policy data including covered vehicles for that policy.

  • PolicyID is a required parameter for this data page to fetch the policy details.
  • Retreive the list of policy IDs and pass it as a parameter to this page.

Extension points for policy details

  • Add the external integration source for D_Policy_Details data page to the “Data Source Details” section in the bottom left of the screenshot below.
  • Add the name of the system next to the system name shown in the bottom right of the screen shot below. 
Example of modifications for Policy details
Double-click the image to enlarge it.


Expected output for policy details

Policy type, billing details, and policy data, including commercial coverages and covered vehicles, are received as a response from the data page. The changes can be made for each policy type from the response for different policy IDs.

Extension points for policy type


Data page for policy details


Extending the rating engine for quote updates

Depending on the line of business for which you are enabling an address change, a rating engine integration may be required. For example, if you are an insurance carrier that provides automobile insurance, you can use an integration point to a rating engine to get rate and premium changes impacted by address or garage-location changes. 

Steps to modify to extend rating engine for quote updates


Data page D_PolicyPremium of class PegaIns-Data-InsurancePolicy is used to compute the policy total premium value.

  • PolicyID can be sent as a parameter to D_PolicyPremium to get the premium for a specific policy ID.
  • When the ratings system data source is modified, total premium, total vehicle premium, and discounted premium is expected as the response.
  • If no value appears for discounted premium, then no discount applies to that policy.

Extension Points to integrate a rating system

  • The data page is sourced from a rating system. In the case of an external system, extend the data page by replacing the source.
  • Update the extension data transform to customize logic to retrieve the premium value from the rating system.
Data transform changes
Double-click the image to enlarge it.


Expected output to integrate a rating system

Total Premium for the policy and total vehicle premium of each covered vehicle under the policy is displayed as the response.

Expected output for Rating engine extension


Extending to update the contact address

When the change of address is completed by the CSR or by the customer, an integration point is provided to update the customer contact address within the contact system of record (SOR).

Steps to modify to extend Saving updated contact address


Savable Data page D_UpdateContactAddress of class Work- is used to save the updated address in the contact SOR.

  • pyID of the case that initiated the address change can be passed as the parameter to the data page to update the address for the specific service case.
  • Use the activity OpenWorkForLandingPage to copy the case data to the primary context of the data page.

Extension Points for updating contact information

  • To update the address for the contact and save it to the external source, extend the data page to replace the source for the same.
  • Extend the activity SyncContactAddressData used to save the changes made during the service case depending on the options selected in the contact table.
  • Steps to replace the source from App Studio appear earlier in this topic.
Example of extending Saving updated contact address
Double-click the image to enlarge it.


Extending to update policy details

When the change of address is completed by the CSR or by the customer, an integration point is provided to make the change within the policy administration system or systems.

Steps to modify to extend Saving updated policy details


SavableData page D_SavePolicyDetails of class Work- is used to save the policy details.

  • The updated address for each policy is committed to the policy administration source system.
  • The premium value recomputed based on several parameters is updated for each policy in the source system.
  • The subcase is created for each of the cases that the user has partially updated and is processed, irrespective of the main case.

Extension points for updating policy details

  • To update the address and premium details when the source system is external, extend the data page to handle any additional processing.
  • Extend the activity SavePolicyDetails used to save the changes made during the service case depending on the options selected.
  • Steps to replace the source from App Studio are shown in the following figure:
Example of extending Saving updated policy details
Double-click the image to enlarge it.



Are all the integration points required?

The rating integration point is not required if you do not need to “re-rate” a policy based on an address change.  As the insurance carrier, you may offer only life insurance policies and allow a change of address within a certain geography without a need to “re-rate” the policy as one example.  If “re-rating” is not needed, a business user within App Studio would delete the rating step within the case workflow.   

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us