salesforce-appraiser-review-letter/docs/PRODUCT_SPEC.md

# Product Spec — Appraiser Review Letter Platform

## Purpose
This project is a Salesforce-based operator tool for generating appraiser review letters in DocuSign CLM from `Appraiser_Case__c` data, while also serving as a proof-of-concept platform for broader DocuSign API integrations across CLM and eSignature.

## Product goals
- Let a user open an `Appraiser Case` in Salesforce and generate a review letter in DocuSign CLM without using Execute Anonymous.
- Keep CLM account, folder, template, and destination selection configurable per account.
- Persist generation status and generated-document references back to Salesforce.
- Allow operators to browse and test eSignature API data from the same Salesforce app.
- Provide a clean foundation for future workflows such as template selection, envelope creation, and richer document operations.

## Primary users
- Salesforce admins configuring DocuSign connectivity and defaults
- Business users generating review letters from `Appraiser Case` records
- Technical users validating CLM and eSignature API behavior in a safe UI

## Current in-scope workflows

### 1. CLM document generation
- User opens an `Appraiser Case` record.
- User launches the `Generate Review Letter` quick action.
- User selects a configured CLM account.
- User selects a configured letter type.
- User browses CLM folders and templates or uses saved defaults.
- User generates a document through CLM `documentxmlmergetasks`.
- User checks task status.
- User attaches the generated CLM document back to Salesforce as a File.

### 2. eSignature API browsing
- User opens an `Appraiser Case` record.
- User navigates to the `Docusign eSignature` tab on the record page.
- User selects a configured account.
- User loads:
  - login information
  - OAuth user info
  - discovered eSignature accounts
  - account templates
  - recent envelopes

## Canonical Salesforce data model

### Appraiser Case
`Appraiser_Case__c` is the primary business record.

Current functional fields include:
- `Name`
- `Appraiser_Field_Review_Date__c`
- `Letter_Sent_Date__c`
- `FHA_Case_Number__c`
- `Appraiser_Name__c`
- `Appraiser_Last_Name__c`
- `Appraiser_Street__c`
- `Appraiser_City__c`
- `Appraiser_State_Province__c`
- `Appraiser_Postal_Code__c`
- `Appraiser_Country__c`
- `Property_Street__c`
- `Property_City__c`
- `Property_State_Province__c`
- `Property_Postal_Code__c`
- `Property_Country__c`

Current CLM tracking fields include:
- `Last_CLM_Account_Code__c`
- `Last_DocGen_Status__c`
- `Last_DocGen_Message__c`
- `Last_DocGen_Task_Id__c`
- `Last_DocGen_Task_Url__c`
- `Generated_Document_Id__c`
- `Generated_Document_Url__c`
- `Last_DocGen_Requested_At__c`
- `Last_DocGen_Completed_At__c`
- `Last_Template_Document_Href__c`
- `Last_Destination_Folder_Href__c`
- `Attached_File_Content_Document_Id__c`
- `Attached_File_Url__c`

### Appraiser Case Deficiency
`Appraiser_Case_Deficiency__c` is the canonical child object.

Fields:
- `Appraiser_Case__c`
- `Deficiency_Number__c`
- `Description__c`
- `Reference__c`
- `Resolution__c`

Validation:
- blank deficiency records are blocked by validation

### CLM account configuration
`CLM_Account_Setting__mdt` is the account-level configuration source of truth.

Fields include:
- account identity
  - `Account_Code__c`
  - `Account_Display_Name__c`
  - `Environment_Code__c`
  - `Active__c`
- CLM configuration
  - `CLM_Account_Id__c`
  - `CLM_Api_Named_Credential__c`
  - `CLM_Download_Named_Credential__c`
  - `Template_Root_Folder_Href__c`
  - `Destination_Root_Folder_Href__c`
  - `Default_Template_Document_Href__c`
  - `Default_Destination_Document_Name_Prefix__c`
- eSignature configuration
  - `ESignature_Auth_Named_Credential__c`
  - `ESignature_Rest_Named_Credential__c`
  - `ESignature_Account_Id__c`

Current active example accounts:
- `DTC CLM Demo`
- `DTC IAM Enterprise`
- `DTC HUD Demo`

### Letter definition configuration
`CLM_Letter_Definition__mdt` is the extensibility layer for letter types.

Each record can define:
- account code
- letter code
- display name
- default flag
- sort order
- default template href
- template root folder href
- destination root folder href
- default filename prefix

Current seeded letter definition:
- `APPRAISER_REVIEW`

Design intent:
- keep the current appraiser review letter working
- allow three additional letters to be added without redesigning the workbench
- support more letters later by metadata rather than code branching

## Canonical CLM architecture

### Payload generation
[AppraiserCasePayloadBuilder.cls](/home/paulh/.openclaw/workspace/projects/salesforce-appraiser-review-letter/force-app/main/default/classes/AppraiserCasePayloadBuilder.cls) builds the document payload from `Appraiser_Case__c` and `Appraiser_Case_Deficiency__c`.

Current payload fields:
- `AppraiserCaseNumber`
- `AppraiserFieldReviewDate`
- `LetterSentDate`
- `FHACaseNumber`
- `AppraiserName`
- `AppraiserLastName`
- `AppraiserStreet`
- `AppraiserCity`
- `AppraiserStateProvince`
- `AppraiserPostalCode`
- `AppraiserCountry`
- `AppraiserAddress`
- `PropertyStreet`
- `PropertyCity`
- `PropertyStateProvince`
- `PropertyPostalCode`
- `PropertyCountry`
- `PropertyAddress`
- `DeficiencyList[]`

### CLM callouts
[CLMDocGenCallout.cls](/home/paulh/.openclaw/workspace/projects/salesforce-appraiser-review-letter/force-app/main/default/classes/CLMDocGenCallout.cls) is the canonical CLM integration class.

Current supported operations:
- submit `documentxmlmergetasks`
- poll task status
- browse folders/documents through generic resource requests
- download generated documents

### CLM orchestration
[CLMAdminService.cls](/home/paulh/.openclaw/workspace/projects/salesforce-appraiser-review-letter/force-app/main/default/classes/CLMAdminService.cls) is the UI-facing orchestration layer.

Current supported operations:
- account selection and defaults
- case context retrieval
- folder/document browsing
- document generation
- task polling
- generated document attachment to Salesforce Files

### CLM UI
[clmDocGenWorkbench](/home/paulh/.openclaw/workspace/projects/salesforce-appraiser-review-letter/force-app/main/default/lwc/clmDocGenWorkbench/clmDocGenWorkbench.js) is the current operator UI.

Current behavior:
- launched from the `Generate Review Letter` quick action
- uses account-based CLM config
- uses account + letter-type selection
- supports template browsing
- supports destination browsing
- supports destination filename selection
- shows case deficiencies before generation
- shows task details and file attachment status

## Canonical eSignature architecture

### eSignature service layer
[DocusignESignatureService.cls](/home/paulh/.openclaw/workspace/projects/salesforce-appraiser-review-letter/force-app/main/default/classes/DocusignESignatureService.cls) is the current eSignature integration layer.

Current supported operations:
- `getAccountConfig`
- `getLoginInformation`
- `getUserInfo`
- `listAccounts`
- `getAccountInformation`
- `listTemplates`
- `listEnvelopes`

### eSignature UI
[docusignEsignWorkbench](/home/paulh/.openclaw/workspace/projects/salesforce-appraiser-review-letter/force-app/main/default/lwc/docusignEsignWorkbench/docusignEsignWorkbench.js) is the current exploratory UI.

Current behavior:
- placed on its own `Docusign eSignature` record tab
- supports account selection
- shows raw login info and user info
- shows discovered eSignature accounts
- shows templates
- shows recent envelopes filtered by `from_date`

## Named credential model

### CLM
- UAT CLM API: `CLMuatNamedCreds`
- UAT CLM download: `CLMuatDownload`
- S1 CLM API: `CLMs1NamedCreds`
- S1 CLM download: `CLMs1Download`

### eSignature
- eSignature REST: `Esignature_Demo_NamedCreds`
- OAuth/account server: `AcctDemo_NamedCreds`

## Current product behavior

### What is working now
- record-based CLM doc generation from Salesforce UI
- XML merge with repeating deficiencies
- account-based CLM config
- metadata-based letter-type selection with backward-compatible default behavior
- generated document status persistence on the case
- generated document attachment to the case as a Salesforce File
- account-based eSignature API exploration
- eSignature template listing
- eSignature envelope listing

### Known limitations
- no end-user workflow yet for creating or sending envelopes
- no template or envelope detail drill-down in the eSignature UI
- no persistent eSignature activity tracking on the case
- no dedicated admin UI yet for managing account configuration beyond Salesforce Setup
- some older docs still contain historical planning content

## Current template contract

### CLM XML merge fields
- `//AppraiserCaseNumber`
- `//AppraiserFieldReviewDate`
- `//PropertyAddress`
- `//PropertyStreet`
- `//PropertyCity`
- `//PropertyStateProvince`
- `//PropertyPostalCode`
- `//PropertyCountry`

### Deficiency repeating block
- row select: `//DeficiencyList/Deficiency`
- fields:
  - `./Number`
  - `./Description`
  - `./Reference`
  - `./Resolution`

## Near-term roadmap
- add eSignature detail calls for template detail and envelope detail
- add envelope creation and draft-send flows
- add better operator UX for large account lists and debugging output
- tighten documentation around setup and account configuration
- decide whether to retire `Property_Address__c` completely from metadata

## Out of scope for the current proof of concept
- full production-grade approval workflow
- end-user template authoring inside Salesforce
- large-scale reporting or analytics
- middleware outside Salesforce

---
Last updated: 2026-04-09