QBE OmniChannel Portal Application

The objective the Personal Lines Omni Channel project is provide a new portal that allows different partners (including QBE Direct) to sell policies via the new portal. Partners should be on boarded as smoothly as possible, by making the product and solution as configurable as possible.

• QBE OmniChannel Portal Application
  • Getting Started
    • Prerequisites
    • Installing
  • Environment Variables
  • Available Scripts
    • npm run corsproxy
    • npm start
    • Start using VSCode Run
    • npm run build
  • Running the tests
    • npm run test -- -u
    • npm run test
    • npm run cypress
  • Folder Structure
  • Useful links
  • Architectural Overview
    • Managing styles
    • Managing multiple external API calls
      • Relationship between sitecore content and code
    • Managing state between the form and the saved quote
    • An approach to generating dynamic components based on external content
    • Handling business rules and errors from Guidewire.
      • Triaging issues for the GW team
      • Validation Error
      • UWIssues
  • More detailed concepts:
  • Making changes
  • Deployment
  • Built With
  • Versioning
  • Product Model Configuration
  • System Inventory
  • Additional Notes
  • Technical debt register
  • DevSecOps
    • TODOS

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

• BitBucket Repository - Project repository access required
• Nodejs - Javascript environment for building project
• npm - Node Package Manager for downloading dependent packages and build project

Installing

To get the development environment running

1. Create SSH-key (https://confluence.atlassian.com/bitbucket/set-up-an-ssh-key-728138079.html)
2. Link SSH-key to your QBE ID (https://bitbucket.corp.qbe.com/projects/ANQUI/repos/plomnichannel-prw-core)
3. Clone the repository

git clone ssh://[email protected]:7999/anqui/plomnichannel-prw-core.git

Note that the clone location above is different to the one provided by bitbucket if you just click the 'clone project' button. Use the one above. Install dependencies Make sure you are running an administrator powershell and install the build tools used:

npm install -g --production windows-build-tools

The above command will take a long time to run and will look like it has hung - just leave it and it should finish eventually. Now you should be able to run:

npm install

Environment Variables

Only environment variables prefixed with REACT_APP_ are accessible via ReactJS.

| Variable Name | Type | Required | Description | |-------------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------| | TEST_PRODUCT_CODE | String | | Used exclusively for testing purposes, this variable short circuits the windows global variable window.qbeTrack.meta.appProduct |

Available Scripts

In the project directory, run:

npm run corsproxy

before:

npm start

Runs the app in the development mode. Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits. You will also see any lint errors in the console.

Start using VSCode Run

npm start will start the app but it won't have the correct environment variables set. Use VSCode Run to run the app as you would expect.

npm run build

Builds the app for production to the build folder. It correctly bundles React in production mode and optimizes the build for the best performance.

Running the tests

npm run test -- -u

To run snapshots and test suites.

npm run test

To run tests and generate unit test coverage report.

npm run cypress

To open the cypress test runner UI and execute the cypress e2e tests. There are currently tests for happy and unhappy paths for Homeowners and Landlords and the cypress tests can also be a useful tool for debugging issues and getting through the journey rapidly if you need to test something on one of the later pages.

Folder Structure

After creation, your project should look like this:

plomnichannel-prw-core/
  README.md
  docs/
  eslint/
  node_modules/
  scripts/
  package.json
  package-scripts.js
  jsdoc.config.json
  jest.config.json
  version.txt
  public/
    manifest.json
    index.html
    favicon.ico
  src/
    assets/
    common/
    config/
    constants/
    containers/
    core/
    modules/
    motor/
    muComponents/
    muiTheme/
    products/
      QPHHome/
      QPHLandlord/
      QPMMotorVehicle/
    testUtils/
    themes/
    utils/
    App.css
    App.js
    index.css
    index.js
    logo.svg
    reduxStore.js
    setupTests.js
    styleComponents.js

• public/index.html is the page template;
• src/index.js is the JavaScript entry point.

You may create subdirectories inside src. Only files inside public can be used from public/index.html.

You can, however, create more top-level directories. They will not be included in the production build so you can use them for things like documentation.

Useful links

• Test Data Confluence Page - this page holds a lot of useful information around test environments (including URLS) as well some examples of data and addresses that can be used to trigger certain Guidewire rule scenarios. It also has the test payment info for the payment gateway.
• Portal Business Requirements - this page is the first step to tracking down the expected requirements for page and componet behaviour. It can sometimes be a bit tricky to find what you're actually looking for, but generally the pages should correlate to the steps of the site.
• Householder Guidewire Business Rules - this spreadsheet is the source of truth for how Guidewire rules should behave and be displayed in the frontend. Again, the tabs in the sheet should correlate to the steps in order to help find the specific rules you're looking for.
• Front End Architecture contains some useful insights into origins of the architectural design decisions, coding practices and environments.

Architectural Overview

The implementation of the frontend SPA is designed to be a dumb shell over the business rules that come from the Guidewire system merged with the content that comes from the Sitecore CMS. This means that the little business logic within the frontend is primarily concerned with merging these two sources of information and neccessitates a few architectural approaches.

Managing styles

There are four ways to do the styles through the whole project 1, *.css, e.g.: App.css - not recommeded to add style here; 2, *.scss, e.g.: style.scss - not recommeded to add style here; 3, material-ui - recommended to add style here, this project uses a lot material-ui components, and also done customizations based on those components; 4, style-component - recommended to add style here, this project uses style-component for the non masterial-components, and also, in some cases, we use the style-component to style the material ui component.

Managing multiple external API calls

Because the site is a white label product that is intended to allow use by multiple brands there is an identifier in the index.html file that indicates what content and rules should be loaded and used through the site. The identifier looks like: <div id="root" data-spaid="{A3C2498D-0F45-494E-BC60-40E2F3A48ADB}"></div> and the spaid is then used in subsequent API calls

API calls are managed through sagas and can mostly be found in the customSagas.js file under /src/modules/sagas/ The getting of the Sitecore and Guidewire data for populating the App is handled through the Higher Order Component (HoC) withQuestions.js The saving and retrieving of the Quote object is handled through the HoC withQuote.js

Relationship between sitecore content and code

The sitecore content is served to the frontend as a large json file when the App is initially loaded. The App then parses the json content based primarily on the ids of the content inside. This means that often the simplest way to find where a piece of code you're trying to touch is located is first to find the content being displayed is located in sitecore and then search the codebase for the correlting content identifier.

Managing state between the form and the saved quote

The quote is saved when moving from one url to the next by the 'Next' button. This doesn't happen on every 'Next', but can be configured to occur by passing the forceSave: true, property in the Next button. The form state is managed in redux and tries, as much as possible, to reflect the most up-to-date version of the Quote returned from Guidewire. This means that property names have specific meaning outside the context of the SPA and shouldn't be changed without understanding the impact. When debugging you can find the current state of the user selected form answers in the console.log under the following object path: next state > formEvents.formValue and you can find the current representation of the Quote object under: next state > quote.quote As part of the nature of the form it's possible that the Users journey may be prevented by disabling the Next button until certain conditions are met (a question is answered, an error is resolved or other similar events). The determination for allowing navigation is handled in the HoC withNavigation.js

An approach to generating dynamic components based on external content

For the most part, as much as possible, the components rendered by system are generic - that is their differences are managed by configuration rather than the implmentation of bespoke differences in their rendering and functionality. The approach taken is to use specific 'step' files that corelate to views of the site. In general there are views that correlate to a single desktop url or page view and may contain multiple sections each with their own components and rendering rules. For example certain fields may remain disabled or invible until others are answered - this is all handled in step.desktop.js and step.mobile.js files that can be found in config//steps/ directories.

Step files usually have access to Guidewire content, Sitecore content and the saved Quote object that contains the currently most up-to-date saved response from Guidewire. Usually this Quote object is used to check existing answers provided bty the user in order to show or hide specific question. Sometimes dynamic manipluation of the components needs to be done on a form level rathe than the Quote - usually when answering a specific question on a page cascades certain changes to other components on the page

Properties are passed in to the components directly from the step files. The type of component is dictated by the type property and the fields property details the various interactive and visual components to display for that particular view or component.

Handling business rules and errors from Guidewire.

When the form sends a Quote to be saved the calculation for the properties of that quote (how much? are you a customer they want to take on? what kind of risks are associated with your answers?) are done by the Guidewire system that returns either a quote response with the current known values for both the users answers and the current information from GW. GW may also return an Error that indicates a problem with the supplied answers or a response indicating too much risk or some other resaon for GW to block the user. These GW errors are not displayed to the user, but instead the associated key property returned with the error is used to look up the associated content error message within Sitecore content that is then displayed to the User. This merging together of messages is performed within the SPA.

Triaging issues for the GW team

Often bugs or issues will come back from the business or users that aren't the responsibility of the frontend application and these need to be passed to the backend team with Guidewire for support. We generally try to provide the backend team with as much information as possible regarding the payload related to the bug so we will use chrome developer tools to capture the request/response details of the failing interaction. To do this

1. open chrome dev tool to the network tab.
2. Find the failing network request and copy/paste the Response result.
3. Click Headers for the failing network request and find Request Payload
4. Click 'view source' to get a text version
5. Scroll down clicking 'Show more' until there's no more options to show more
6. Copy and paste the Request Payload to a txt file for the GW team

Example:

There are two types of errors:

• Validation Errors
• UWIssues

Both errors are returned on a saveQuote call whether the rating is set to true (get a price) or false (just save the quote so it can be retrieved later)

Validation Error

{
	"customerParty": {
		"contactList": [
			{
				"primaryEmailAddress": "[email protected]"
			}
		]
	},
	"partnerId": "AUSPOST",
	"quoteId": "PLOC1000001469",
	"validationErrors": [
		{
			"description": "DECLINE: Unable to offer cover as part of the home is rented to tenants (such as a room or granny flat). ",
			"code": "HomeLocation19"
		},
		{
			"description": "DECLINE: Unable to offer cover as part of the home is rented to tenants (such as a room or granny flat). ",
			"code": "HomeLocation19"
		}
	]
}

UWIssues

{
	"UWIssues": [
		{
			"blockingPoint": "BlocksQuote",
			"code": "HMContSumInsPLOmni",
			"longDescription": "REFER: The sum insured value of your contents is over my authority level.",
			"shortDescription": "REFER: Contents sum insured exceeds authority"
		}
	],
	"customerParty": {
		"contactList": [
			{
				"primaryEmailAddress": "[email protected]"
			}
		]
	},
	"partnerId": "AUSPOST",
	"quoteId": "PLOC1000001469"
}

More detailed concepts:

• Step Configuration
• Show and Hide questions in config
• Pre Pop
• Building and Contents Sum Insured

Making changes

Make sure you branch for each story being worked on. Branch from the appropriate development branch (ask the team if you're not sure which is currently appropriate). Branch naming convention: "{ticket-type}/PR-{ticket-nr}/{brief-ticket-description}" where ticket-type is "story" or "defect" and brief-ticket-description is losely based on the title of the ticket (some defect-tickets have very long titles). When you're finished with your branch, do a git pull origin , resolve any conflicts, then create a pull-request with the Tech Lead as reviewer plus at least one other developer

Deployment

Portals for dev and system testing (ST) are hosted in IIS Server. All other environments are hosted in Sitecore.

Details about deployment process can be found at the Deploy SPA to SiteCore Content Delivery Server ( Omni Channel ) Confluence page.

The deployment scripts for different environments are configured in the file src/package-scripts.js

Also, an env folder includes API base URLs and environment-specific configurations.

Deployment scripts are meant to run on using the the command ### npm run deploy to deploy in dev enviornment. To deploy in environments such as ST, SIT, UAT5 etc use npm run deploy:st, npm run deploy:sit and so on.

Built With

• Material UI - UI component framework
• Styled Components - CSS-in-JS styling framework
• React - JavaScript library for building user interfaces
• This project was bootstrapped with Create React App
• Redux - For managing application state
• Redux Saga - For managing application side effects
• Jest - JavaScript Testing Framework
• Enzyme - JavaScript Testing utility for React components
• ESLint - JavaScript code analysis utility

Versioning

Versioning information

Product Model Configuration

• A global data-structure is used for driving the questionnaire.

• The SPA config into following levels: Steps, Views, Panels, Components

• There are separate configurations for desktop and mobile that are defined in src/products/{product-code}/desktopConfig.js and src/products/{product-code}/mobileConfig.js respectively.

• Details on the Global Data Structure that drives the questionnaire can be found at https://qbe-appservices.atlassian.net/wiki/spaces/PLDPR/pages/720801825/Global+data-structure+used+for+driving+the+questionnaire

System Inventory

• Sitecore - Hosts the portal site and is the content manager for the portal site
• Mulesoft - Integration layer between the Single Page Application and Guidewire and other shared services
• Guidewire - Policy, billing, claims management

Additional Notes

• There are different layout setting for desktop / mobile display
• Static content is mapped for steps and components in SiteCore CMS

Technical debt register

• [High] - Vehicle needs to be moved into R2
  • I believe this is possible under the current structure. Regression testing is just the biggest hurdle at the moment.
• [High] - Get rid of step configuration files
  • Use component language (RXJS) to describe how steps are interlinked.
  • Events and CSS should not live in configuration
• [Medium] - Get rid of reduxForm.js
  • Unfortunately dont have a plan other than get rid of it. It's a layer ontop of redux that shouldnt really be there. Changes to the store should be actions fired from the components itself.
• [Medium] - Make the components to be accessiable
  • There are still a lot components using wrong accessible/Semantic html, e.g.: buttons in select boxes, which are needed to refactor.
• [Medium] - Refactor all the qbe hardcoded varaible names to be user friendly names
  • Currently, this app uses a lot qbe hardcoded variable names, e.g.: azure color, stag font, when it goes with white labelling, it becomes confusing, therefore, those should be refactored to be, primary colour, secondary colour, base font, etc...
• [High] - TYC and Quote Summary component files are too big.
  • They need to be reduced and standardised to avoid confusion.
• [Low] - Move the sitecore config into each component.
  • Each component should know where the sitecore content is stored (session or store) and then pull out relevant information from it that the component needs through an abstracted mechanism. At the moment each component is fed the data and no default state (QBE Partner English language) can be rendered if the sitecore site goes down.
• [Low] - Sitecore content post go live rarely changes.
  • It could be stored and retrieved differently, instead of every page load. (Save ~820kB after it has loaded once and not changed)
• [Low] - Guidewire product definition post go live rarely changes.
  • It could be stored and retrieved differently, instead of every page load. (Save ~175kB after it has loaded once and not changed)
• [Low] - The app performance needs to be improved
  • The React Performance Analysis has been done long times ago, it needs to be done in the future, it documented here: https://qbe-appservices.atlassian.net/wiki/spaces/PLDPR/pages/769786243/React+Performance+Analysis+WIP

DevSecOps

TODOS

• Change deploy folder to environment name rather than source branch in env var files
• appVersion auto generated