Assist_Design/docs/FIELD-MAPPING-MIGRATION-GUIDE.md

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 (SKU, 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:

// In catalog.service.ts
const soql = `SELECT Id, Name, ${skuField}, Portal_Category__c, Portal_Visible__c FROM Product2...`

Migrate to:

import { getSalesforceFieldMap, getProductQueryFields } from "../common/config/field-map";

// Option 1: Use helper function (recommended)
const soql = `SELECT ${getProductQueryFields()} FROM Product2 WHERE ${fields.product.portalVisible} = true`;

// Option 2: Use individual fields
const fields = getSalesforceFieldMap();
const soql = `SELECT Id, Name, ${fields.product.sku}, ${fields.product.portalCategory}, ${fields.product.portalVisible} FROM Product2...`;

2. Update Orders Service

Current mixed usage:

// 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:

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:

// In salesforce-account.service.ts
WHERE SF_Account_No__c = '${this.safeSoql(customerNumber.trim())}'

Migrate to:

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:

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 Portal_Category__c with fields.product.portalCategory
• Replace hardcoded Portal_Visible__c with fields.product.portalVisible
• 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:

# Account fields
ACCOUNT_INTERNET_ELIGIBILITY_FIELD=Custom_Internet_Eligibility__c
ACCOUNT_CUSTOMER_NUMBER_FIELD=Custom_Account_Number__c

# Product fields
PRODUCT_PORTAL_VISIBLE_FIELD=Custom_Portal_Visible__c
PRODUCT_PORTAL_CATEGORY_FIELD=Custom_Portal_Category__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