328 lines
14 KiB
Markdown
328 lines
14 KiB
Markdown
# Project Specification — Phase 2: eSignature Envelope Creation
|
|
|
|
---
|
|
|
|
## 1. Project Overview
|
|
|
|
### What are we building?
|
|
|
|
Connecting the CLM document generation workflow to DocuSign eSignature. After a review letter is generated and attached to an `Appraiser_Case__c` record, the operator can click "Send for Signature" to create a DocuSign envelope (using a pre-built eSignature template), send it, and have the envelope ID, status, and sent timestamp written back to the case.
|
|
|
|
### Why does it matter?
|
|
|
|
Phase 1 produces the review letter. Phase 2 delivers it for signature. Without this, the operator must manually log into DocuSign to send the envelope — a workflow gap.
|
|
|
|
### Success criteria
|
|
|
|
- [ ] Five eSignature tracking fields exist on `Appraiser_Case__c` and deploy cleanly
|
|
- [ ] `DocusignESignatureService.createEnvelope()` calls the eSignature REST API and returns a structured result
|
|
- [ ] Envelope ID, status, and sent timestamp are persisted to the case after a successful send
|
|
- [ ] `clmDocGenWorkbench` exposes a "Send for Signature" button that activates after attach succeeds
|
|
- [ ] All Apex changes are covered by tests in the existing test classes; all tests pass in appraiser-dev
|
|
|
|
---
|
|
|
|
## 2. Technical Foundation
|
|
|
|
### Tech stack
|
|
|
|
- **Language:** Apex (Salesforce), LWC (JavaScript/HTML)
|
|
- **Framework:** Salesforce DX / SFDX source format
|
|
- **Test framework:** Apex Test (deployed and run via sf CLI)
|
|
- **Package manager:** N/A — Salesforce metadata deployment
|
|
- **Org alias:** `appraiser-dev`
|
|
|
|
### Project structure
|
|
|
|
```
|
|
force-app/main/default/
|
|
├── classes/
|
|
│ ├── CLMAdminService.cls
|
|
│ ├── CLMAdminServiceTest.cls
|
|
│ ├── DocusignESignatureService.cls ← primary change target
|
|
│ └── DocusignESignatureServiceTest.cls ← test target
|
|
├── lwc/
|
|
│ └── clmDocGenWorkbench/ ← UI change target
|
|
└── objects/
|
|
└── Appraiser_Case__c/
|
|
└── fields/ ← 5 new fields
|
|
```
|
|
|
|
### Build and test commands
|
|
|
|
```bash
|
|
NODE=/home/paulh/.nvm/versions/node/v22.22.0/bin/node
|
|
SF=/home/paulh/.nvm/versions/node/v22.22.0/lib/node_modules/@salesforce/cli/bin/run.js
|
|
|
|
# Deploy
|
|
$NODE $SF project deploy start --source-dir force-app --target-org appraiser-dev
|
|
|
|
# Run tests
|
|
$NODE $SF apex run test \
|
|
--target-org appraiser-dev \
|
|
--class-names DocusignESignatureServiceTest,CLMAdminServiceTest \
|
|
--result-format human \
|
|
--synchronous
|
|
```
|
|
|
|
### Coding standards
|
|
|
|
- Follow existing Apex class structure — inner DTO classes, `@AuraEnabled` methods, `with sharing`
|
|
- Follow CLM tracking pattern: service layer method → result object → persist to case in `CLMAdminService`
|
|
- All HTTP callouts mocked in tests using `HttpCalloutMock` (see `CLMDocGenCalloutTest` for the pattern)
|
|
- LWC: follow existing `clmDocGenWorkbench` patterns (wire adapters, async/await handlers, tracked properties)
|
|
- Field API names use `__c` suffix; field-meta.xml follows Salesforce DX format
|
|
|
|
---
|
|
|
|
## 3. Requirements
|
|
|
|
### FR-001: eSignature Tracking Fields on Appraiser_Case__c
|
|
|
|
**Description:** Five custom fields to track the envelope lifecycle on the case record.
|
|
|
|
**Fields:**
|
|
- `ESignature_Envelope_Id__c` — Text(255), label "eSignature Envelope ID"
|
|
- `ESignature_Envelope_Status__c` — Text(50), label "eSignature Envelope Status" (values: created / sent / delivered / completed / voided)
|
|
- `ESignature_Sent_At__c` — DateTime, label "eSignature Sent At"
|
|
- `ESignature_Completed_At__c` — DateTime, label "eSignature Completed At"
|
|
- `ESignature_Envelope_Url__c` — URL(255), label "eSignature Envelope URL"
|
|
|
|
**Acceptance criteria:**
|
|
- [ ] All 5 field metadata XML files exist under `objects/Appraiser_Case__c/fields/`
|
|
- [ ] Fields deploy cleanly to appraiser-dev with no errors
|
|
- [ ] `package.xml` is updated to include the new fields (or already covers `CustomField` members)
|
|
|
|
---
|
|
|
|
### FR-002: createEnvelope() in DocusignESignatureService
|
|
|
|
**Description:** An Apex method that creates a DocuSign eSignature envelope using Option A (template-based). The caller provides a case ID, account code, and template ID. The method resolves the named credential from the account setting, calls `POST /v2.1/accounts/{accountId}/envelopes` with the template ID and a signer role populated from the case's appraiser fields, and returns a structured result.
|
|
|
|
**API call shape:**
|
|
```json
|
|
POST /v2.1/accounts/{accountId}/envelopes
|
|
{
|
|
"templateId": "<templateId>",
|
|
"templateRoles": [
|
|
{
|
|
"email": "<Appraiser_Email__c>",
|
|
"name": "<Appraiser_Name__c or Appraiser_Salutation__c + Appraiser_Last_Name__c>",
|
|
"roleName": "Signer"
|
|
}
|
|
],
|
|
"status": "sent"
|
|
}
|
|
```
|
|
|
|
**Result class:** `EnvelopeCreateResult` — inner class on `DocusignESignatureService`:
|
|
- `Boolean success`
|
|
- `String envelopeId`
|
|
- `String status`
|
|
- `String envelopeUri`
|
|
- `String errorMessage`
|
|
|
|
**Method signature:**
|
|
```apex
|
|
@AuraEnabled(cacheable=false)
|
|
public static EnvelopeCreateResult createEnvelope(
|
|
Id caseId,
|
|
String accountCode,
|
|
String templateId
|
|
)
|
|
```
|
|
|
|
**Acceptance criteria:**
|
|
- [ ] Method is `@AuraEnabled` and callable from LWC
|
|
- [ ] Resolves `eSignatureAccountId` and `eSignatureRestNamedCredential` from `CLM_Account_Setting__mdt` via `accountCode`
|
|
- [ ] Queries `Appraiser_Email__c`, `Appraiser_Name__c`, `Appraiser_Last_Name__c`, `Appraiser_Salutation__c` from the case
|
|
- [ ] POSTs correct JSON body to the eSignature API
|
|
- [ ] Returns `EnvelopeCreateResult` with `envelopeId` and `status` on success
|
|
- [ ] Returns `EnvelopeCreateResult` with `success=false` and `errorMessage` on failure (non-2xx or exception)
|
|
- [ ] Does NOT throw uncaught exceptions — catches and wraps in result
|
|
|
|
---
|
|
|
|
### FR-003: persistEnvelopeResult() in CLMAdminService
|
|
|
|
**Description:** After a successful `createEnvelope()` call, write the result back to `Appraiser_Case__c`. Follows the same pattern as `persistDocGenResult`.
|
|
|
|
**Method signature:**
|
|
```apex
|
|
@AuraEnabled(cacheable=false)
|
|
public static void persistEnvelopeResult(
|
|
Id caseId,
|
|
String envelopeId,
|
|
String envelopeStatus,
|
|
String envelopeUri
|
|
)
|
|
```
|
|
|
|
**Fields written:**
|
|
- `ESignature_Envelope_Id__c` = envelopeId
|
|
- `ESignature_Envelope_Status__c` = envelopeStatus
|
|
- `ESignature_Sent_At__c` = Datetime.now()
|
|
- `ESignature_Envelope_Url__c` = envelopeUri (if not blank)
|
|
|
|
**Acceptance criteria:**
|
|
- [ ] Method updates the correct case record (by `caseId`)
|
|
- [ ] Sets `ESignature_Sent_At__c` to current datetime
|
|
- [ ] Does not overwrite `ESignature_Completed_At__c` (only set when status = completed)
|
|
|
|
---
|
|
|
|
### FR-004: Extend CaseContext with Envelope Fields
|
|
|
|
**Description:** The `CaseContext` inner class in `CLMAdminService` (and its `getCaseContext()` query) must include the 5 eSignature tracking fields so the LWC can display current envelope status.
|
|
|
|
**Fields to add to CaseContext:**
|
|
- `String eSignatureEnvelopeId`
|
|
- `String eSignatureEnvelopeStatus`
|
|
- `String eSignatureEnvelopeUrl`
|
|
- `Datetime eSignatureSentAt`
|
|
- `Datetime eSignatureCompletedAt`
|
|
|
|
**Acceptance criteria:**
|
|
- [ ] `getCaseContext()` SOQL query includes all 5 fields
|
|
- [ ] `CaseContext` DTO maps all 5 fields with `@AuraEnabled`
|
|
|
|
---
|
|
|
|
### FR-005: "Send for Signature" Button in clmDocGenWorkbench
|
|
|
|
**Description:** After the "Attach Generated Document" step succeeds, a "Send for Signature" button becomes enabled. Clicking it calls `createEnvelope()` and then `persistEnvelopeResult()`, and displays the result (envelope ID and status, or error message) in the workbench UI.
|
|
|
|
**Behavior:**
|
|
- Button is disabled until `attachedFileContentDocumentId` is populated (i.e., attach has succeeded)
|
|
- Button shows a spinner while in progress (same pattern as generate/attach buttons)
|
|
- On success: display envelope ID and status; update envelope fields displayed from `caseContext`
|
|
- On error: display error message
|
|
- Button does NOT automatically select a template — the operator must provide `templateId` via a text input field in the UI
|
|
|
|
**New UI elements:**
|
|
- Text input: "eSignature Template ID" (maps to `templateId` parameter)
|
|
- Button: "Send for Signature"
|
|
- Status display: envelope ID, status, sent timestamp (read from refreshed `caseContext`)
|
|
|
|
**Acceptance criteria:**
|
|
- [ ] Button is disabled when `attachedFileContentDocumentId` is blank
|
|
- [ ] Button calls `DocusignESignatureService.createEnvelope()` with the case ID, account code, and template ID from the input
|
|
- [ ] On success, calls `CLMAdminService.persistEnvelopeResult()` and refreshes the case context display
|
|
- [ ] On failure, displays the error message from `EnvelopeCreateResult.errorMessage`
|
|
- [ ] Template ID input is cleared after a successful send
|
|
- [ ] Spinner shown during the callout; button disabled during in-flight request
|
|
|
|
---
|
|
|
|
### NFR-001: Test Coverage
|
|
|
|
- [ ] `DocusignESignatureServiceTest` covers `createEnvelope()` — at minimum: success path (mock HTTP 201), failure path (mock HTTP 400), missing template ID guard
|
|
- [ ] `CLMAdminServiceTest` covers `persistEnvelopeResult()` — at minimum: fields written correctly, `ESignature_Sent_At__c` is set
|
|
- [ ] All existing tests continue to pass after each change
|
|
|
|
### NFR-002: No Hardcoded Credentials
|
|
|
|
- [ ] All DocuSign API calls go through named credentials (never hardcoded tokens or passwords)
|
|
- [ ] Named credential API name is sourced from `CLM_Account_Setting__mdt`
|
|
|
|
---
|
|
|
|
## 4. Data Model
|
|
|
|
### New fields on Appraiser_Case__c
|
|
|
|
| API Name | Type | Length |
|
|
|----------|------|--------|
|
|
| ESignature_Envelope_Id__c | Text | 255 |
|
|
| ESignature_Envelope_Status__c | Text | 50 |
|
|
| ESignature_Sent_At__c | DateTime | — |
|
|
| ESignature_Completed_At__c | DateTime | — |
|
|
| ESignature_Envelope_Url__c | URL | 255 |
|
|
|
|
### Existing fields read by createEnvelope()
|
|
|
|
| API Name | Used for |
|
|
|----------|----------|
|
|
| Appraiser_Email__c | templateRoles[0].email |
|
|
| Appraiser_Name__c | templateRoles[0].name (prefer this) |
|
|
| Appraiser_Salutation__c | fallback for name |
|
|
| Appraiser_Last_Name__c | fallback for name |
|
|
|
|
---
|
|
|
|
## 5. Architecture Decisions
|
|
|
|
### Constraints
|
|
|
|
- **MUST:** Use `CLM_Account_Setting__mdt` to resolve named credentials — never hardcode
|
|
- **MUST:** Follow the `persistDocGenResult` pattern in `CLMAdminService` for `persistEnvelopeResult`
|
|
- **MUST:** Mock all HTTP callouts in tests using `HttpCalloutMock`
|
|
- **MUST NOT:** Modify the CLM document generation flow (Phase 1) — leave it untouched
|
|
- **MUST NOT:** Create new Apex test classes — add to existing ones
|
|
- **MUST NOT:** Add eSignature template browsing in this phase — the operator inputs the template ID directly
|
|
- **PREFER:** Option A (template-based envelope) for `createEnvelope()` — simpler, already decided
|
|
- **ESCALATE:** If the eSignature named credential does not exist in the org, stop and flag it
|
|
- **ESCALATE:** If `Appraiser_Email__c` is blank on the queried case, stop — do not silently send with a blank email
|
|
- **ESCALATE:** If the spec does not cover a required decision — do not fill gaps silently
|
|
|
|
### Dependencies
|
|
|
|
- `CLM_Account_Setting__mdt` — provides `ESignature_Account_Id__c`, `ESignature_Rest_Named_Credential__c`
|
|
- DocuSign eSignature REST API v2.1 — `/v2.1/accounts/{accountId}/envelopes`
|
|
- Named credential (AcctDemo_NamedCreds or equivalent) — must exist in appraiser-dev
|
|
|
|
### Known Challenges
|
|
|
|
- The named credential for eSignature REST may differ from the CLM named credential — check `CLM_Account_Setting__mdt` for `ESignature_Rest_Named_Credential__c`
|
|
- DocuSign template roles: the `roleName` must match the role name defined in the eSignature template — "Signer" is the default, but the actual template may use a different name. If tests fail with a 400 from DocuSign about role name, escalate.
|
|
- LWC must use `async/await` for imperative Apex calls (not wire adapters) for the send action — matches the existing attach pattern
|
|
|
|
### Rejected Approaches
|
|
|
|
| Rejected option | Why rejected |
|
|
|-----------------|-------------|
|
|
| Option B (upload CLM document as envelope document) | More complex, requires downloading the blob and managing recipients in code. Option A with a matching template is simpler and sufficient. |
|
|
| Creating a new Apex test class for eSignature | Not needed — `DocusignESignatureServiceTest` already exists and is the right home |
|
|
| Automatic template selection via API | Out of scope for Phase 2 — operator inputs template ID directly |
|
|
|
|
---
|
|
|
|
## 6. Reference Materials
|
|
|
|
### Existing code to learn from
|
|
|
|
- `CLMAdminService.persistDocGenResult()` — the exact pattern to replicate for `persistEnvelopeResult()`
|
|
- `CLMAdminService.getCaseContext()` — how case fields are queried and mapped to a DTO
|
|
- `CLMDocGenCalloutTest` — the HTTP mock pattern to follow in `DocusignESignatureServiceTest`
|
|
- `clmDocGenWorkbench` — the LWC pattern (async handlers, spinner, button enable/disable) to follow for the send button
|
|
|
|
### Anti-patterns
|
|
|
|
- Do not use `HttpRequest.setBodyAsBlob()` for the JSON envelope payload — use `setBody()` with `JSON.serialize()`
|
|
- Do not trust the `status` field in the LWC to determine if all prior steps completed — check the specific field (e.g., `attachedFileContentDocumentId`) that the button should gate on
|
|
|
|
---
|
|
|
|
## 7. Evaluation Design
|
|
|
|
### Test cases
|
|
|
|
#### TC-001: createEnvelope() success path
|
|
**Input:** Valid caseId, valid accountCode, valid templateId; mock HTTP returns 201 with `{"envelopeId":"abc-123","status":"sent","uri":"/envelopes/abc-123"}`
|
|
**Expected output:** `EnvelopeCreateResult.success = true`, `envelopeId = "abc-123"`, `status = "sent"`
|
|
**Verification:** `System.assertEquals(true, result.success)` in `DocusignESignatureServiceTest`
|
|
|
|
#### TC-002: createEnvelope() failure path
|
|
**Input:** Valid caseId/accountCode/templateId; mock HTTP returns 400 with error body
|
|
**Expected output:** `EnvelopeCreateResult.success = false`, `errorMessage` is non-blank
|
|
**Verification:** `System.assertEquals(false, result.success)` and `System.assertNotEquals(null, result.errorMessage)`
|
|
|
|
#### TC-003: persistEnvelopeResult() writes correct fields
|
|
**Input:** Existing case record, envelopeId = "test-env-id", envelopeStatus = "sent", envelopeUri = "/envelopes/test-env-id"
|
|
**Expected output:** Re-queried case has `ESignature_Envelope_Id__c = "test-env-id"`, `ESignature_Sent_At__c` is non-null
|
|
**Verification:** Re-query case after call and assert in `CLMAdminServiceTest`
|
|
|
|
---
|
|
|
|
_Last updated: 2026-04-09_
|