paulh
/
salesforce-appraiser-review-letter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
salesforce-appraiser-review.../docs/PRODUCT_SPEC.md

9.4 KiB
Raw Blame History

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 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 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 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 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 is the current eSignature integration layer.

Current supported operations:

  • getAccountConfig
  • getLoginInformation
  • getUserInfo
  • listAccounts
  • getAccountInformation
  • listTemplates
  • listEnvelopes

eSignature UI

docusignEsignWorkbench 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