Skip to content

Commit 4fafe29

Browse files
kchen-salesforcekchen-salesforce
authored
Merge pull request #3 from SalesforceLabs/SalesforceLabs/INS/W-21148613/product-selection-lwc
Product Selection OS LWC init
2 parents 525652d + ed7f6a7 commit 4fafe29

21 files changed

Lines changed: 2134 additions & 0 deletions

‎osComponents/ProductSelection/classes/InsuranceRatingApexService.cls‎

Lines changed: 321 additions & 0 deletions
Large diffs are not rendered by default.

‎osComponents/ProductSelection/classes/InsuranceRatingApexService.cls-meta.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
3+
<apiVersion>66.0</apiVersion>
4+
<status>Active</status>
5+
</ApexClass>

‎osComponents/ProductSelection/labels/ProductSelectionLabels.labels‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<CustomLabels xmlns="http://soap.sforce.com/2006/04/metadata">
3+
<labels>
4+
<fullName>ProdSelMinComparisonValidation</fullName>
5+
<language>en_US</language>
6+
<protected>false</protected>
7+
<shortDescription>Minimum products comparison validation</shortDescription>
8+
<value>Select at least {0} products to compare</value>
9+
</labels>
10+
<labels>
11+
<fullName>ProdSelMaxComparisonValidation</fullName>
12+
<language>en_US</language>
13+
<protected>false</protected>
14+
<shortDescription>Maximum products comparison validation</shortDescription>
15+
<value>Select up to {0} products to compare.</value>
16+
</labels>
17+
<labels>
18+
<fullName>ProdSelMaxMultiSelectValidation</fullName>
19+
<language>en_US</language>
20+
<protected>false</protected>
21+
<shortDescription>Maximum multi-select validation</shortDescription>
22+
<value>Choose no more than {0} products.</value>
23+
</labels>
24+
<labels>
25+
<fullName>ProdSelMaxRootProductValidation</fullName>
26+
<language>en_US</language>
27+
<protected>false</protected>
28+
<shortDescription>Maximum root products validation</shortDescription>
29+
<value>No more than {0} root products are allowed for input.</value>
30+
</labels>
31+
<labels>
32+
<fullName>ProdSelSelectionRequiredMsg</fullName>
33+
<language>en_US</language>
34+
<protected>false</protected>
35+
<shortDescription>Selection required message</shortDescription>
36+
<value>Choose a product.</value>
37+
</labels>
38+
<labels>
39+
<fullName>ProdSelNoProductsMsg</fullName>
40+
<language>en_US</language>
41+
<protected>false</protected>
42+
<shortDescription>No products available message</shortDescription>
43+
<value>No products are available.</value>
44+
</labels>
45+
<labels>
46+
<fullName>ProdSelCompareBtn</fullName>
47+
<language>en_US</language>
48+
<protected>false</protected>
49+
<shortDescription>Compare button label</shortDescription>
50+
<value>Compare</value>
51+
</labels>
52+
<labels>
53+
<fullName>ProdSelDetails</fullName>
54+
<language>en_US</language>
55+
<protected>false</protected>
56+
<shortDescription>Details column label</shortDescription>
57+
<value>Details</value>
58+
</labels>
59+
<labels>
60+
<fullName>ProdSelNext</fullName>
61+
<language>en_US</language>
62+
<protected>false</protected>
63+
<shortDescription>Next button label</shortDescription>
64+
<value>Next</value>
65+
</labels>
66+
<labels>
67+
<fullName>ProdSelPremium</fullName>
68+
<language>en_US</language>
69+
<protected>false</protected>
70+
<shortDescription>Premium label</shortDescription>
71+
<value>Premium</value>
72+
</labels>
73+
<labels>
74+
<fullName>ProdSelPrevious</fullName>
75+
<language>en_US</language>
76+
<protected>false</protected>
77+
<shortDescription>Previous button label</shortDescription>
78+
<value>Previous</value>
79+
</labels>
80+
<labels>
81+
<fullName>ProdSelProduct</fullName>
82+
<language>en_US</language>
83+
<protected>false</protected>
84+
<shortDescription>Product column label</shortDescription>
85+
<value>Product</value>
86+
</labels>
87+
<labels>
88+
<fullName>ProdSelLoading</fullName>
89+
<language>en_US</language>
90+
<protected>false</protected>
91+
<shortDescription>Loading spinner alt text</shortDescription>
92+
<value>Loading</value>
93+
</labels>
94+
<labels>
95+
<fullName>ProdSelCheckbox</fullName>
96+
<language>en_US</language>
97+
<protected>false</protected>
98+
<shortDescription>Checkbox accessibility label</shortDescription>
99+
<value>checkbox</value>
100+
</labels>
101+
<labels>
102+
<fullName>ProdSelCompareProducts</fullName>
103+
<language>en_US</language>
104+
<protected>false</protected>
105+
<shortDescription>Compare Products modal header</shortDescription>
106+
<value>Compare Products</value>
107+
</labels>
108+
<labels>
109+
<fullName>ProdSelCancel</fullName>
110+
<language>en_US</language>
111+
<protected>false</protected>
112+
<shortDescription>Cancel button label</shortDescription>
113+
<value>Cancel</value>
114+
</labels>
115+
</CustomLabels>

‎osComponents/ProductSelection/lwc/productSelection/README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Product Selection Lightning Web Component
2+
3+
## Overview
4+
5+
The `productSelection` Lightning Web Component (LWC) is designed for Digital Insurance product selection workflows. It extends `OmniscriptBaseMixin` to integrate seamlessly with OmniScripts, and makes it easy for users to view, compare, and select rated insurance products.
6+
7+
The component supports both **single-select** and **multi-select** modes, displays product cards with pricing information, and includes a product comparison modal.
8+
9+
---
10+
11+
## Dependencies
12+
13+
- **Apex Controller**: `InsuranceRatingApexService.postRatingFromLwc`
14+
- **Mixin**: `c/omniscriptBaseMixin` (follow the steps under [Prerequisites](../../../README.md#prerequisites))
15+
- **Helper Modules**:
16+
- `dataManager.js` – Tree building and grid transformation utilities
17+
- `labelsAndConstants.js` – Validation messages, labels, and constants
18+
19+
## Components Included
20+
21+
| Component | Description |
22+
| :---- | :---- |
23+
| `productSelection` | Main component for displaying and selecting rated products |
24+
| `productSelectionCompareModal` | Modal dialog for comparing 2-3 selected products |
25+
| `productSelectionCustomTreeGrid` | Extended `lightning-treeGrid` with custom cell rendering |
26+
| `productSelectionCustomTemplate` | Custom cell template for various data types such as currency, date, and lookup. |
27+
28+
### Supporting Files
29+
30+
| File | Type | Description |
31+
| :---- | :---- | :---- |
32+
| `InsuranceRatingApexService.cls` | Apex Class | Service class that wraps the `createInsuranceRating` invocable action |
33+
| `ProductSelectionLabels.labels` | Custom Labels | UI text labels for translation support |
34+
35+
---
36+
37+
## Public Properties (`@api`)
38+
39+
| Property | Type | Default | Description |
40+
| :---- | :---- | :---- | :---- |
41+
| `additionalFields` | `Object` | `{}` | Additional fields to include in the rating request payload. |
42+
| `clearStateOnChange` | `String` | — | JSON stringified array of element names whose state should be cleared when selection changes. |
43+
| `clearStateOnPrev` | `Boolean/String` | — | When `true` or `'true'`, enables custom navigation buttons and clears state when navigating to the previous step. |
44+
| `effectiveDate` | `String` | — | The effective date for rating calculations. |
45+
| `enableMultiSelect` | `Boolean` | `false` | Enables multi-select mode allowing users to select multiple products. |
46+
| `multiSelectMax` | `Number` | `10` | Maximum number of products that can be selected in multi-select mode. |
47+
| `ratedProdDescriptions` | `Array` | `[]` | Array of description objects `{rootProductCode, rootInstanceKey, ratingDescription}` for custom product descriptions. |
48+
| `ratingInputs` | `Array` | `[]` | Array of rating input objects containing product configuration data. Supports reusable and non-reusable inputs with `instanceKeys`. |
49+
| `ratingOptions` | `Object` | `{}` | Rating options passed to the API. Defaults `executePricing` and `executeConfigurationRules` to `true`. |
50+
| `rootProductCodes` | `Array` | `[]` | Array of root product codes to rate. Define when the rating inputs are marked as reusable. |
51+
| `transactionType` | `String` | — | The transaction type for the rating request |
52+
53+
Rating inputs and options are based on the [Insurance Product Rating API](https://developer.salesforce.com/docs/atlas.en-us.insurance_developer_guide.meta/insurance_developer_guide/connect_resources_product_rating.htm%20%20).
54+
55+
## HTML Markup
56+
57+
### Product Card Layout
58+
59+
Each card displays:
60+
61+
- **Product title** – With 2-line text clamp and ellipsis overflow
62+
- **Premium amount** – Formatted using `lightning-formatted-number` with currency
63+
- **Description** – With 3-line text clamp and ellipsis overflow
64+
65+
### Conditional Custom Navigation
66+
67+
When `clearStateOnPrev` is true, the component renders custom Previous/Next buttons for state management control:
68+
69+
```html
70+
<template lwc:if={showCustomNextPrevButtons}>
71+
<lightning-button label="Previous" onclick={handleCustomPrevious} ... />
72+
<lightning-button label="Next" onclick={handleCustomNext} ... />
73+
</template>
74+
```
75+
76+
---
77+
78+
## Component Usage
79+
80+
Embed the productSelection LWC in an Omniscript by using the Custom Lightning Web Component element in a step.
81+
82+
### Adding to an OmniScript Step
83+
84+
1. Open your OmniScript in OmniStudio Designer
85+
2. Add a **Custom Lightning Web Component** element to your step
86+
3. Set the **LWC Component Name** to `c-product-selection`
87+
4. Configure the component properties (see [Public Properties](#public-properties-api))
88+
89+
If you set `clearStateOnPrev` to `true`, hide the standard Previous and Next buttons in the step by reducing their width to 0\. The productSelection LWC shows Previous and Next buttons for navigation.
90+
91+
### Data Output Structure
92+
93+
The component outputs data to OmniScript via `omniUpdateDataJson()`:
94+
95+
```javascript
96+
{
97+
errors: [{ message: "Error message" }],
98+
selectedProducts: [
99+
{
100+
contextId: "contextId-123",
101+
ratingInputs: [
102+
{
103+
productCode: "PROD_001",
104+
instanceKeys: ["key1", "key2"],
105+
reusable: false
106+
}
107+
]
108+
}
109+
]
110+
}
111+
```
112+
113+
---
114+
115+
## Customization
116+
117+
### Styling
118+
119+
The productSelection LWC uses the Salesforce Lightning Design System (SLDS) for styling.
120+
121+
### Adding Custom Product Descriptions
122+
123+
Pass custom descriptions via the `ratedProdDescriptions` property:
124+
125+
```json
126+
{
127+
"ratedProdDescriptions": [
128+
{
129+
"rootProductCode": "AUTO_POLICY",
130+
"rootInstanceKey": "policy-1",
131+
"ratingDescription": "Comprehensive auto coverage with roadside assistance"
132+
}
133+
]
134+
}
135+
```
136+
137+
If both rootProductCode and rootInstanceKey are provided, rootInstanceKey takes precedence.
138+
139+
### Constants Configuration
140+
141+
Edit `labelsAndConstants.js` to modify:
142+
143+
- `MIN_PRODUCTS_FOR_COMPARISON`: The minimum number of products that the user must select for comparison. The default value is 2\.
144+
- `MAX_PRODUCTS_FOR_COMPARISON`: The maximum number of products that the user can select for comparison. The default value is 3\.
145+
- `MAX_ROOT_PRODUCTS`: The maximum number of root products that the user can select. The default value is 10\.
146+
- `MAX_CHAR_LIMIT`: Character limit for descriptions (default: 150\) The maximum number of characters that the user can enter in the description. The default value is 150\.
147+
148+
### Custom Labels
149+
150+
These custom labels are included and can be customized or translated:
151+
152+
| Label API Name | Default Value | Purpose |
153+
| :---- | :---- | :---- |
154+
| `ProdSelMinComparisonValidation` | Select at least {0} products to compare | Validation message |
155+
| `ProdSelMaxComparisonValidation` | Select up to {0} products to compare. | Validation message |
156+
| `ProdSelMaxMultiSelectValidation` | Choose no more than {0} products. | Validation message |
157+
| `ProdSelMaxRootProductValidation` | No more than {0} root products are allowed for input. | Validation message |
158+
| `ProdSelSelectionRequiredMsg` | Choose a product. | Validation message |
159+
| `ProdSelNoProductsMsg` | No products are available. | Empty state message |
160+
| `ProdSelCompareBtn` | Compare | Button label |
161+
| `ProdSelDetails` | Details | Column header |
162+
| `ProdSelNext` | Next | Button label |
163+
| `ProdSelPremium` | Premium | Label text |
164+
| `ProdSelPrevious` | Previous | Button label |
165+
| `ProdSelProduct` | Product | Column header |
166+
| `ProdSelLoading` | Loading | Spinner alt text |
167+
| `ProdSelCheckbox` | checkbox | Accessibility label |
168+
| `ProdSelCompareProducts` | Compare Products | Modal header |
169+
| `ProdSelCancel` | Cancel | Button label |
170+
171+
## Troubleshooting
172+
173+
### Common Issues
174+
175+
| Issue | Possible Cause | Solution |
176+
| :---- | :---- | :---- |
177+
| "No products are available" | Rating API returned no products or ran into error | Verify `rootProductCodes` and `ratingInputs` are correct. |
178+
| OmniscriptBaseMixin not found on component deployment | Missing Omniscript customization package | Ensure `omniscriptBaseMixin` and utility modules are deployed by following the [Prerequisites](../../../README.md#prerequisites). |
179+
| Missing context or product details on rating call response | Wrong API version | Ensure that all components and supporting files use Salesforce API version **66.0** or later. |
180+
| State not persisting | clearStateOnPrev is not set to true | Hide step buttons by setting width to 0 and set `clearStateOnPrev` to true. |
181+
182+
### Debugging
183+
184+
1. **Debug Logs:** Enable debug logs for the `InsuranceRatingApexService` class.
185+
2. **Browser console:** The component logs errors to the console.
186+
3. **OmniScript data panel:** Check the data JSON for output values.
187+
188+
## API Version
189+
190+
All components and supporting files must use Salesforce API version **66.0** or later.

0 commit comments

Comments
 (0)