SageSure First Notice of Loss components

Usage

There are three FNOL components, one for each app: MySageSure ,IPC Manager, and Agent Portal.

Props

definitionLocation: string

This is the remote location of the form definition files and other static assets the form requires. Typically, this will be the public directory in an environment-specific S3 bucket -- dev-int, ss-preview, ss-stage, and ss-prod.

policy: PolicyData

The host application provides policy and policyholder data via the policy prop.

const samplePolicyData = {
  policyId: 'FNL067484400',
  policyName: 'FedNat Homeowners Policy (HO-3)',
  policyEffectiveDate: 'July 31, 2010',
  policyExpirationDate: 'July 31, 2021',
  fullName: 'James Wallace',
  email: '[email protected]',
  phoneNumber: '(776) 040-0540',
  streetAddress: '16441 ANNA BELLE DR',
  city: 'PRAIRIEVILLE',
  state: 'IL',
  zip: '70769',
  carrierGroup: 'iat',
};

onPost: (body: any) => Promise<any>

Use the onPost prop to connect the component with the IPC Losses Channel API. The provided callback should be an async function that POSTs the body argument to the channel API and returns the response for the component to handle.

onExit: () => void

This callback will be called when it's time to leave the component. It is up to the host application to route the user where they need to go.

onEvent: (event: AnalyticsEvent) => void

Use this optional prop to record user activity inside the component. Event details are listed below.

googleMapsKey: string

Optional prop to connect to the Google Place Autocomplete API. This is the Google Maps Key used to connect to the API. If it's not included, the address field will not search the Google Places API.

export interface AnalyticsEvent {
  name: string;
  section?: string;
  step?: string;
  sectionClicked?: string | null;
  error?: string;
  hasClaimID?: boolean;
  lossType?: string;
  errorMessage?: string | null;
}

MySageSure

Install @icg360/fnol-policyholder

import React from 'react';
import PolicyholderFnol from '@icg360/fnol-policyholder';

<PolicyholderFnol
  definitionLocation="https://s3-bucket-endpoint.com/public"
  policy={samplePolicyData}
  onPost={async (body) => {}}
  onExit={() => {}}
  onEvent={(event) => {}}
  googleMapsKey="GOOGLE-PLACES-API-KEY"
/>;

IPC Manager

Install @icg360/fnol-policymanager

import React from 'react';
import PolicymanagerFnol from '@icg360/fnol-policymanager';

<PolicymanagerFnol
  definitionLocation="https://s3-bucket-endpoint.com/public"
  policy={samplePolicyData}
  onPost={async (body) => {}}
  onExit={() => {}}
  onEvent={(event) => {}}
  googleMapsKey="GOOGLE-PLACES-API-KEY"
/>;

Agent Portal

Install @icg360/fnol-policyproducer

import React from 'react';
import PolicyproducerFnol from '@icg360/fnol-policyproducer';

<PolicyproducerFnol
  definitionLocation="https://s3-bucket-endpoint.com/public"
  policy={samplePolicyData}
  onPost={async (body) => {}}
  onExit={() => {}}
  onEvent={(event) => {}}
  googleMapsKey="GOOGLE-PLACES-API-KEY"
/>;

Analytics Events

AnalyticsEvent type definition

MySageSure and Agent Portal Events

| Event Name | Trigger | Properties | | ---------------------------- | ------------------------------------------------------------ | --------------------------------------- | | FNOL Form Load Error | The FNOL form fails to load | errorMessage | | Form Page Loaded | A page in the FNOL form successfully loads | section, step, lossType | | Back Button Clicked | User clicks the back button to go back a page in the form | section, step, lossType | | Next Button Clicked | User clicks on the Next Step button | section, step, lossType | | Form Nav Clicked | User clicks the form navigation to go to a different section | section, sectionClicked, step, lossType | | Validation Error Displayed | User views a validation error on the FNOL form | section, step, lossType, errorMessage | | Review Page Viewed | User views the FNOL review page | lossType | | Confirmation Page Viewed | User views the FNOL confirmation page | lossType, hasClaimID | | FNOL Submitted | User submits FNOL form | lossType | | Exit FNOL Form | User clicks to go back to main application and exits form | section, step, lossType | | Continue In Progress Clicked | User clicks the button to continue an in progress claim | |

IPCM Events

| Event Name | Trigger | Properties | | -------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------- | | FNOL Form Load Error | The FNOL form fails to load | errorMessage | | Form Nav Clicked | User clicks the form navigation to go to a different section | questionClicked, lossType | | Validation Error Displayed | User views a validation error on the FNOL form | section, question, lossType, errorMessage | | FNOL Submitted | User submits FNOL form | lossType | | Exit FNOL Form | User clicks to go back to main application and exits form | section, lossType | | Wind/Hail Modal Displayed | The modal displaying Opterrix data is displayed | lossType, lossSubType | | Wind/Hail Modal View Details Clicked | The user clicks "View Details" to open the Wind/Hail modal | lossType, lossSubType | | Wind/Hail Modal Check Adjacent Dates Clicked | The user clicks "Check Adjacent Dates" to open the Wind/Hail modal | lossType, lossSubType | | Wind/Hail Modal Change Date | The user clicks "Change date of loss" in the Wind/Hail modal | lossType, lossSubType | | Duplicate Claim Modal Displayed | The Duplicate Claim modal is displayed | lossType | | Duplicate Claim Modal Go To Existing Claim Clicked | The user clicks "Go to existing claim" in the Duplicate Claim modal | lossType | | Duplicate Claim Modal Continue New Claim Clicked | The user clicks "Continue with new claim" in the Duplicate Claim modal | lossType | | Policy Term Modal Displayed | The Duplicate Claim modal is displayed | lossType | | Policy Term Modal Go Back Clicked | The user clicks "Go to existing claim" in the Duplicate Claim modal | lossType | | Policy Term Modal Continue New Claim Clicked | The user clicks "Continue with new claim" in the Duplicate Claim modal | lossType | | Continue In Progress Clicked | User clicks the button to continue an in progress claim | |

Development Environment

Getting Started

Install dependencies and start the Next.js dev server.

npm i
npm run dev

Queries (API Requests)

By default the application will use the mock-channels-api for local development. If you want to validate work against the live staging environment you can trigger the requests to go through the channels API via .env changes.

cp .env.example .env

Setting NEXT_PUBLIC_USE_CHANNELS_API env variable to true will make all requests go through the channels API. You will also have to supply the NEXT_PUBLIC_CHANNELS_STAGING_URL & NEXT_PUBLIC_CHANNELS_TOKEN env variables.

NOTE: must be on VPN for this to work

Debugging

If you find something isn't working right in one of the host apps you have some tools to hunt down the problem.

1. There's a version string in the footer of the component. This is good place to start, making sure you're looking at the expected component and form definition.

Example: 0.6.0 | policyholder | iat | 20210730T164318

Parsed: {component version} | {environment} | {carrier} | {def created date}

2. By default the component loads the latest form definition for the requested environment and carrier. Sometimes it can be handy to see the form using a different definition, especially if you want to know if an older version will break a new component. To override the default definition, add a querystring to the url with file name you want use. Example:

?def=form-def-policyholder-iat-20210709T165849.json

3. Knowing the state of the FNOL component at runtime can also be helpful. In any of the host applications there's a global FNOL_STATE variable that you can access from the console to view a snapshot of the component's current state.

Styled Component Organization

• If the styles are only being used in one place, keep them in the same file
• If the styles are used in multiple places but only within a single feature, keep them in the root folder for that feature in a styled.tsx file
• If the styles are related to the theme definition, place them in /components/common/theme.tsx.

Formik

WithField HOC

Every form field that needs to be registered/used with Formik has to either be wriiten as or wrapped with the Formik <Field> component. Due to the fields all being defined by the form definition (see below) each different type of field requires the same two props being given to the Formik <Field> component. The withField function automatically wraps the fields with the Formik component and takes at least two props: block & handleValidation. The output of the function supplies the component then to be used in your markup which automatically includes two props (more can be added): the block and the Formik <FieldProps> which gives you access to the field, form (formik context), and meta which is the value, error, & touched state of said field making it simpler to interact with and removes the need to use the Formik context for values, etc.

Error handling within Formik

Validation does not have to be explicitly called within a field/block. Validation will automatically run onChange, but will only show to the user if the field has been touched.

On Field Change -> field will show error message below it if there is an error

• This is done using setFieldTouched and setFieldValue or onChange

  setFieldTouched(block.id);
  setFieldValue(block.id, value); // adding a true/false as a 3rd parameter sets if form validation will run, leave this off so it uses default values

• or by using:

  handleChange(e);

On Next button (MSS & AP) -> all fields with an error message are set as touched, which will show their error messages to the user

• This prevents error messages being shown to the user too early- before the user has either touched the field or hit Next

On Submit -> all field validation should run again automatically

Form Definition

The individual components are driven by external form definitions that can updated independently of the applications. Each component pulls in the appropriate definition based on context -- application environment and carrier.

To make changes go to form-def-source.json. Once your updates are ready, run npm run compile-defs. The files will be written to the public folder. If you're ready to publish the results include the archive flag to write time stamped files -- npm run compile-defs -- --archive. See more below about releasing the forms.

For more details, see the form definition docs.

Environment and carrier transformations

Blocks can be filtered out based on environment and carrier in the source file, but for the same block to vary by context we need a transform. These are defined in form-def-transforms.json.

In this example, we would redefine the title of the exampleBlockId in FedNat's policyholder form.

[
  {
    "environments": ["policyholder"],
    "carriers": ["fnhc"],
    "blocks": {
      "exampleBlockId": {
        "title": "Override title defined in form-def-source."
      }
    }
  }
]

Preview Environment

Each merge request will create a url where the Next.js app is available as a preview of the changes. Automation will run against this preview environment. To learn more about the feature automation, see the bdd readme.

Within this environment all outside channel calls are mocked. To learn more about the calls, see Mock Channels Api. This can also be found on the info page linked on the preview env landing page.

Releasing

Component

When ready to publish PolicyholderFnol, PolicymanagerFnol, &/or PolicyproducerFnol, follow these steps

1. Locally on main run git pull origin main to get all changes
2. npm run release to bump the version, tag the release & update the CHANGELOG.
3. git push origin main --tags this will automatically trigger the pipeline to publish the package.

Form

When ready to publish changes to the form, follow these steps

Before merging, on feature branch

1. Run npm run compile-defs -- --archive to write the timestamped files

On the merge to main pipeline

The stage pre-prod has the ability to deploy to three s3 buckets - dev-int, ss-preview & ss-stage. The stage prod has the ability to deploy to the prod s3 bucket - ss-prod.

1. Manually deploy the forms to the s3 buckets in the following order - forms:dev-int, forms:ss-preview, forms:ss-stage, forms:ss-prod NOTE: Only release the forms to the environments as needed & directed by Product and QA