# Requirements — Appraiser Review Letter Generator

## Purpose
Outline technical and functional requirements for Appraiser Review Letter templates in Salesforce CLM. Include assumed merge fields, integration points, edge cases, and design goals.

---

## Functional
- Reviewer completes form Q&A on Appraiser Review
- Each response drives tailored content in final letter (questions, comments, tables/blocks)
- Salesforce triggers CLM letter, merges data fields and Q&A collection

## Non-Functional
- Configurable (new Qs/fields easy to add)
- Audit and status tracking
- Support for complex/dynamic tables in output

## Key Requirements
- Support dynamic template merge fields (arrays/lists, booleans, enums)
- Render tables, paragraphs, and conditional sections
- Handle edge cases: nulls, empty lists, formatting gaps
- Provide fallback text for empty sections (e.g., 'No deficiencies found')
- Enable integration with Salesforce data model (objects: Appraisal, Deficiency, Reviewer)

## Example JSON
```json
{
  "AppraisalId": "a1b2c3",
  "DeficiencyList": [
    {
      "DeficiencyType": "Missing Docs",
      "DeficiencyDescription": "Appraisal report lacking required documents."
    }
  ],
  "ReviewerComments": ["Well organized report."]
}
```

---

## Questions/Decisions
- What is the authoritative object and field schema for merge?
- Are custom field mappings needed for relationships (e.g. lookup fields)?

## Initial Authoritative Salesforce Schema
- Appraiser_Case__c (Appraiser Case)
  - Name (label: Appraiser Case Number, AutoNumber)
  - Appraiser_Field_Review_Date__c (Date)
  - Property_Address__c (Text)
- Appraiser_Case_Deficiency__c (Appraiser Case Deficiency)
  - Appraiser_Case__c (Master-Detail -> Appraiser_Case__c)
  - Deficiency_Number__c (Number)
  - Description__c (Long Text Area)
  - Resolution__c (Long Text Area)

This schema supports CLM array merges by iterating child deficiency records tied to one appraiser case.

## CLM Integration

### Payload Structure (from AppraiserCasePayloadBuilder)
The Apex class `AppraiserCasePayloadBuilder` transforms Salesforce records into CLM-ready JSON:
- AppraiserCaseNumber (string) -> Appraiser_Case__c.Name
- AppraiserFieldReviewDate (ISO date) -> Appraiser_Case__c.Appraiser_Field_Review_Date__c
- PropertyAddress (string) -> Appraiser_Case__c.Property_Address__c
- DeficiencyList (array of objects):
  - deficiencyNumber (number) -> Appraiser_Case_Deficiency__c.Deficiency_Number__c
  - description (string) -> Appraiser_Case_Deficiency__c.Description__c
  - resolution (string) -> Appraiser_Case_Deficiency__c.Resolution__c

### CLM API Integration (CLMDocGenCallout)
- HTTP POST to DocuSign CLM API with merge payload
- Named Credentials: Securely store CLM endpoint + OAuth token
- Remote Site Settings: Whitelist CLM instance domain
- Response includes document URL and ID for tracking

See [CLM_INTEGRATION.md](CLM_INTEGRATION.md) for setup and usage patterns.
 
 ---
 _Last updated: 2026-02-26 10:35 AM_
 _Work in progress: Integration and schema expansion next._