172 lines
6.3 KiB
Markdown
172 lines
6.3 KiB
Markdown
# Field Mapping Migration Guide
|
|
|
|
This guide provides step-by-step instructions for migrating services to use the simplified centralized field mapping system.
|
|
|
|
## Overview
|
|
|
|
The simplified field mapping system in `apps/bff/src/common/config/field-map.ts` provides essential field coverage for Internet, SIM, and VPN products with a clean, maintainable structure. Complex configuration logic is handled by Salesforce flows rather than product fields.
|
|
|
|
## What's New
|
|
|
|
### Simplified Structure
|
|
- **Core Product fields**: Essential catalog fields only (StockKeepingUnit, category, visibility, pricing)
|
|
- **Service-specific fields**: Minimal fields per product type (Internet tier, SIM data size, etc.)
|
|
- **Configuration logic**: Moved to Salesforce flows for Gold/Platinum Internet plans
|
|
- **Family discount logic**: Handled in personalized catalog service
|
|
|
|
### Key Simplifications
|
|
- **Removed complex configuration fields**: Access mode, service speed, etc. determined by Salesforce
|
|
- **Streamlined VPN products**: Region selection at order time, not product level
|
|
- **Clean Internet structure**: Silver (customer configures) vs Gold/Platinum (Salesforce configures)
|
|
|
|
## Migration Steps
|
|
|
|
### 1. Update Catalog Service
|
|
|
|
**Current hardcoded usage:**
|
|
```typescript
|
|
// In catalog.service.ts
|
|
const soql = `SELECT Id, Name, ${skuField}, Product2Categories1__c, Portal_Catalog__c FROM Product2...`
|
|
```
|
|
|
|
**Migrate to:**
|
|
```typescript
|
|
import { getSalesforceFieldMap, getProductQueryFields } from "../common/config/field-map";
|
|
|
|
// Option 1: Use helper function (recommended)
|
|
const soql = `SELECT ${getProductQueryFields()} FROM Product2 WHERE ${fields.product.portalCatalog} = true`;
|
|
|
|
// Option 2: Use individual fields
|
|
const fields = getSalesforceFieldMap();
|
|
const soql = `SELECT Id, Name, ${fields.product.sku}, ${fields.product.portalCategory}, ${fields.product.portalCatalog} FROM Product2...`;
|
|
```
|
|
|
|
### 2. Update Orders Service
|
|
|
|
**Current mixed usage:**
|
|
```typescript
|
|
// Some fields use mapping, others are hardcoded
|
|
orderFields.Order_Type__c = normalizedType;
|
|
orderFields.Activation_Type__c = body.selections.activationType;
|
|
orderFields.Internet_Plan_Tier__c = body.selections.tier;
|
|
```
|
|
|
|
**Migrate to:**
|
|
```typescript
|
|
const fields = getSalesforceFieldMap();
|
|
|
|
orderFields[fields.order.orderType] = normalizedType;
|
|
orderFields[fields.order.activationType] = body.selections.activationType;
|
|
orderFields[fields.order.internetPlanTier] = body.selections.tier;
|
|
orderFields[fields.order.accessMode] = body.selections.mode;
|
|
orderFields[fields.order.serviceSpeed] = body.selections.speed;
|
|
orderFields[fields.order.installmentPlan] = body.selections.install;
|
|
orderFields[fields.order.weekendInstall] = body.selections.weekend;
|
|
```
|
|
|
|
### 3. Update Account Service
|
|
|
|
**Current hardcoded usage:**
|
|
```typescript
|
|
// In salesforce-account.service.ts
|
|
WHERE SF_Account_No__c = '${this.safeSoql(customerNumber.trim())}'
|
|
```
|
|
|
|
**Migrate to:**
|
|
```typescript
|
|
import { getSalesforceFieldMap } from "../../../common/config/field-map";
|
|
|
|
const fields = getSalesforceFieldMap();
|
|
WHERE ${fields.account.customerNumber} = '${this.safeSoql(customerNumber.trim())}'
|
|
```
|
|
|
|
### 4. Add Personalized Catalog Support
|
|
|
|
**New functionality for Account eligibility:**
|
|
```typescript
|
|
const fields = getSalesforceFieldMap();
|
|
|
|
// Query account eligibility
|
|
const accountSoql = `SELECT ${fields.account.internetEligibility} FROM Account WHERE Id = '${accountId}'`;
|
|
|
|
// Filter products by eligibility
|
|
const productSoql = `SELECT ${getProductQueryFields()}
|
|
FROM Product2
|
|
WHERE ${fields.product.portalVisible} = true
|
|
AND ${fields.product.portalInternetOffering} = '${eligibility}'`;
|
|
```
|
|
|
|
## Service-by-Service Migration Checklist
|
|
|
|
### ✅ Catalog Service
|
|
- [ ] Replace hardcoded `Product2Categories1__c` with `fields.product.portalCategory`
|
|
- [ ] Replace hardcoded `Portal_Catalog__c` with `fields.product.portalCatalog`
|
|
- [ ] Replace hardcoded `Portal_Accessible__c` with `fields.product.portalAccessible`
|
|
- [ ] Use `getProductQueryFields()` for standard queries
|
|
- [ ] Add personalized catalog support using `fields.account.internetEligibility`
|
|
|
|
### ✅ Orders Service
|
|
- [ ] Replace all hardcoded Order fields with field mapping
|
|
- [ ] Update Order query to use `getOrderQueryFields()`
|
|
- [ ] Replace hardcoded `Activation_Status__c`, `Activation_Type__c`, etc.
|
|
- [ ] Update MNP field usage to use `fields.order.mnp.*`
|
|
- [ ] Replace `WHMCS_Order_ID__c` with `fields.order.whmcsOrderId`
|
|
|
|
### ✅ Account Service
|
|
- [ ] Replace `SF_Account_No__c` with `fields.account.customerNumber`
|
|
- [ ] Add eligibility field queries using `fields.account.internetEligibility`
|
|
|
|
### ✅ User Service
|
|
- [ ] Update buildSalesforceUpdate to use field mapping for custom fields
|
|
- [ ] Ensure consistency with Account service field usage
|
|
|
|
## Environment Variable Support
|
|
|
|
All field mappings support environment variable overrides:
|
|
|
|
```bash
|
|
# Account fields
|
|
ACCOUNT_INTERNET_ELIGIBILITY_FIELD=Custom_Internet_Eligibility__c
|
|
ACCOUNT_CUSTOMER_NUMBER_FIELD=Custom_Account_Number__c
|
|
|
|
# Product fields
|
|
PRODUCT_PORTAL_CATALOG_FIELD=Custom_Portal_Catalog__c
|
|
PRODUCT_PORTAL_ACCESSIBLE_FIELD=Custom_Portal_Accessible__c
|
|
PRODUCT_PORTAL_CATEGORY_FIELD=Custom_Product2Categories1__c
|
|
|
|
# Order fields
|
|
ORDER_ACTIVATION_TYPE_FIELD=Custom_Activation_Type__c
|
|
ORDER_INTERNET_PLAN_TIER_FIELD=Custom_Plan_Tier__c
|
|
|
|
# And many more...
|
|
```
|
|
|
|
## Testing Strategy
|
|
|
|
1. **Unit Tests**: Update tests to use field mapping instead of hardcoded values
|
|
2. **Integration Tests**: Verify SOQL queries work with mapped fields
|
|
3. **Environment Tests**: Test with different field mappings via env vars
|
|
|
|
## Rollback Plan
|
|
|
|
If issues arise, you can quickly rollback by:
|
|
1. Setting environment variables to original field names
|
|
2. The field mapping defaults ensure backward compatibility
|
|
3. No database or Salesforce schema changes required
|
|
|
|
## Benefits After Migration
|
|
|
|
1. **Single Source of Truth**: All field references in one place
|
|
2. **Environment Flexibility**: Easy customization per environment
|
|
3. **Documentation Alignment**: Perfect match with portal documentation
|
|
4. **Type Safety**: Strong TypeScript typing for all field references
|
|
5. **Maintainability**: Changes only needed in field mapping file
|
|
|
|
## Next Steps
|
|
|
|
1. Migrate services one by one following this guide
|
|
2. Update unit tests to use field mapping
|
|
3. Test in development environment
|
|
4. Update documentation with new patterns
|
|
5. Consider adding field validation at startup
|