229 lines
12 KiB
Markdown
229 lines
12 KiB
Markdown
# Design — Composite Envelope Builder (Updated)
|
||
|
||
**Project**: Salesforce Composite Envelope Builder
|
||
**Version**: 2.0
|
||
**Date**: 2026-03-25
|
||
**Author**: (auto-generated; update author/owner as needed)
|
||
|
||
---
|
||
|
||
## 1. Summary
|
||
|
||
This document describes the current implementation of the Composite Envelope Builder: how Screen Flows, Apex, and the dfsle toolkit collaborate to build and send a single DocuSign envelope composed from multiple DocuSign templates. It reflects the latest code and metadata in the repository (March 2026), including:
|
||
|
||
- Flow V3 (existing, email-only path) and Flow V4 (new, SMS collection path when recipient email is blank)
|
||
- Apex invocable: `DocusignCompositeEnvelopeBuilder.sendCompositeEnvelope` and supporting classes
|
||
- SMS delivery support for recipients without an email (via `dfsle.Recipient.withSmsDelivery()`)
|
||
- Multi-copy support for the "Authorization to Release Information" template (up to 5 copies)
|
||
- Email subject & body composition rules: prefix `Docusign: `, truncation, greeting/signoff handling and Spanish detection
|
||
- Key constants: `SMS_PLACEHOLDER_EMAIL`, `MULTI_COPY_TEMPLATE_NAME`
|
||
|
||
This is the canonical design doc for developers, release engineers, and reviewers.
|
||
|
||
---
|
||
|
||
## 2. Architecture Overview
|
||
|
||
High-level flow:
|
||
|
||
- User launches Screen Flow (Flow V3 or V4)
|
||
- User selects language (English/Spanish) and templates
|
||
- Flow optionally collects SMS phone when recipient email is blank (V4)
|
||
- Flow invokes Apex action `Send Composite Docusign Envelope` with inputs
|
||
- Apex builds compound envelope JSON using selected templates (expands multi-copy templates as configured)
|
||
- Apex uses dfsle toolkit to send envelope; returns envelopeId and success/error
|
||
|
||
Components:
|
||
|
||
- Screen Flows: `Docusign_Envelope_Templates_V3` (email path), `Docusign_Envelope_Templates_V4` (collect SMS phone when needed)
|
||
- Apex:
|
||
- `DocusignCompositeEnvelopeBuilder.cls` (invocable entrypoint + implementation)
|
||
- `DocusignEnvelopeRequest.cls` (invocable request contract)
|
||
- `DocusignEnvelopeResult.cls` (invocable result contract)
|
||
- `DocusignAPIService.cls`, `DocusignCredentials.cls` (service & credential management)
|
||
- DocuSign: Composite Templates API (via dfsle toolkit integration)
|
||
|
||
---
|
||
|
||
## 3. Flow Behavior (V3 and V4)
|
||
|
||
### 3.1 Shared behavior (V3 & V4)
|
||
|
||
- Language selection screen: user selects `English` or `Spanish`.
|
||
- Template selection screen: multi-select list of templates filtered by selected language.
|
||
- After selection, a loop scans selected templates to detect the multi-copy template ("Authorization to Release Information").
|
||
- If detected, a copies screen appears (radio 1–5) that sets `authReleaseFormCopies`.
|
||
- Flow gathers `compositeTemplateIds` (selected template IDs) and passes them to Apex action.
|
||
|
||
### 3.2 Flow V3
|
||
|
||
- Used when standard email delivery is expected.
|
||
- No SMS collection screen is present.
|
||
- Behavior is unchanged from previous releases except choices include 1–5 copies.
|
||
|
||
### 3.3 Flow V4 (SMS-aware)
|
||
|
||
- Added pre-send recipient lookup path:
|
||
- `Get_Records` (Client_Case__c) → `Get_Recipient_Contact` (Contact lookup)
|
||
- `Is_Recipient_Email_Blank` decision checks Contact.Email
|
||
- If email is blank → `SMS_Phone_Screen` (field `smsPhoneInput` required, E.164 format recommended) → `Store_SMS_Phone` assignment assigns to `recipientSmsPhone` variable → continue
|
||
- If email present → skip SMS_Phone_Screen and continue
|
||
- The `recipientSmsPhone` variable is passed into the Apex action; when non-blank the Apex sets up SMS delivery for Docusign Recipient #1.
|
||
- Flow element names to reference in code and docs: `SMS_Phone_Screen`, `smsPhoneInput`, `Store_SMS_Phone`, `recipientSmsPhone`.
|
||
|
||
Note: Flow metadata must keep element blocks contiguous (assignments, decisions, screens, etc.) to avoid deployment errors. The committed `Docusign_Envelope_Templates_V4.flow-meta.xml` already follows these rules.
|
||
|
||
---
|
||
|
||
## 4. Apex Implementation Details
|
||
|
||
### 4.1 Invocable contract (`DocusignEnvelopeRequest`)
|
||
|
||
Key input fields (invocable variables):
|
||
- `List<String> templateIds` (required) — list of selected DocuSign template IDs
|
||
- `String recordId` (required) — Salesforce Client Case Id
|
||
- `String language` (optional) — e.g., `en`, `es`, `Spanish`, `Español` (language detection is normalized in Apex)
|
||
- `String emailSubject` (optional) — optional override; Apex still prefixes with `Docusign: ` and truncates to 100 chars
|
||
- `Integer authReleaseFormCopies` (optional) — 1–5; counts for Authorization template
|
||
- `String recipientSmsPhone` (optional) — when provided, Apex will enable SMS delivery for Docusign Recipient #1
|
||
|
||
Outputs:
|
||
- `String envelopeId`
|
||
- `Boolean success`
|
||
- `String errorMessage`
|
||
|
||
### 4.2 Main behavior (`DocusignCompositeEnvelopeBuilder.sendCompositeEnvelope`)
|
||
|
||
1. Validate inputs; throw friendly errors if invalid.
|
||
2. Expand multi-copy templates:
|
||
- Find template IDs whose `Name` contains the constant `MULTI_COPY_TEMPLATE_NAME`.
|
||
- If `authReleaseFormCopies` > 1, append (copies - 1) additional entries for each matched template ID.
|
||
- Cap copies to 5 (Math.min(..., 5)).
|
||
3. Build document list (documents = fromTemplate(templateId, label)) and label duplicates as ` (Copy N)` to preserve uniqueness.
|
||
4. Build deduplicated display names for subject/body (merge repeated templates into count markers like `X (3)`).
|
||
5. Compose envelope subject & body (see section 5 for rules).
|
||
6. Resolve recipients via `resolveRecipients(recordId, recipientSmsPhone)`:
|
||
- Query Client_Case__c for lookup fields
|
||
- For Docusign Recipient #1: if linked Contact has no Email and `recipientSmsPhone` is provided, set recipientEmail to `SMS_PLACEHOLDER_EMAIL` and call `recipient.withSmsDelivery(smsPhone)`.
|
||
7. Use dfsle toolkit to build envelope with documents and recipients and call send.
|
||
8. Return `envelopeId` and `success`.
|
||
|
||
### 4.3 Important constants
|
||
|
||
- `SMS_PLACEHOLDER_EMAIL` (defined in `DocusignCompositeEnvelopeBuilder.cls`): placeholder email used when recipient has no email; required by DocuSign API even for SMS deliveries.
|
||
- `MULTI_COPY_TEMPLATE_NAME` (defined in same class): base name used to identify the Authorization to Release Information template (covers English + Spanish variations via LIKE).
|
||
|
||
### 4.4 i18n detection
|
||
|
||
- The code normalizes `req.language` to lowercase and treats as Spanish if any of the following are true:
|
||
- `lang.startsWith('es')` (e.g. `es`, `es-CO`)
|
||
- `lang.contains('spanish')`
|
||
- `lang.contains('espa')` (to capture `español` / `espanol`)
|
||
- On Spanish detection, Apex uses Spanish greeting/signoff; otherwise English is used.
|
||
|
||
---
|
||
|
||
## 5. Email Subject & Body Composition Rules
|
||
|
||
- Subject:
|
||
- Prefix: `Docusign: ` is prepended to the subject to make the source explicit.
|
||
- Truncation: After prefixing, subject is truncated to a maximum of 100 characters (Docusign requirement). The code uses `left(97) + '...'` if longer.
|
||
- If user supplies `emailSubject`, prefix and truncation still apply.
|
||
|
||
- Body:
|
||
- Built as: GREETING + (template bodies joined by DIVIDER) + SIGNOFF
|
||
- DIVIDER: `"\n\n" + '─'.repeat(40) + "\n\n"` (visual separator)
|
||
- Greeting/Sign-off: English default; Spanish strings used when language detection matches Spanish variants. Examples:
|
||
- English greeting: `Hello,\n\nPlease complete the DocuSign signature request from Early Intervention Colorado.\n\n`
|
||
- Spanish greeting: `Hola,\n\nPor favor, firme la solicitud de DocuSign de parte de Intervención Temprana Colorado.\n\n`
|
||
|
||
---
|
||
|
||
## 6. Multi-copy Behavior
|
||
|
||
- Single constant drives detection: `MULTI_COPY_TEMPLATE_NAME = 'Authorization to Release Information'`.
|
||
- Flow shows a copies screen when the template is present; operator selects 1–5 copies.
|
||
- Apex expands the templateId list before building documents to include multiple entries; duplicates are intentionally kept so each copy becomes a separate document in the envelope.
|
||
- Document labels: duplicates are labeled with ` (Copy N)` so they appear distinct in DocuSign Status.
|
||
|
||
---
|
||
|
||
## 7. SMS Delivery Details
|
||
|
||
- Trigger: Flow V4 routes to `SMS_Phone_Screen` if the Contact linked by `Docusign_Recipient_1__c` has empty `Email`.
|
||
- The screen collects `smsPhoneInput` which is assigned to `recipientSmsPhone` variable and passed to Apex.
|
||
- In Apex, when `recipientSmsPhone` is non-blank for Docusign Recipient #1:
|
||
- If recipient record has no email, set `recipientEmail = SMS_PLACEHOLDER_EMAIL`.
|
||
- Call `recipient = recipient.withSmsDelivery(smsPhone)` to enable SMS delivery via dfsle toolkit.
|
||
- Service Coordinator recipient always uses email delivery (unchanged).
|
||
- Important setup requirement (documented): `Docusign_Recipient_1__c` on the Client Case must be populated with a Contact. The Contact must have `Name` and (for SMS flow) may have blank `Email`. If the Contact is null, the recipient will be omitted and envelope will be missing that signer.
|
||
|
||
---
|
||
|
||
## 8. Flows & Metadata Notes
|
||
|
||
- Flow element naming conventions are important (screen fields bind by their `name`). For the SMS flow, the screen field is `smsPhoneInput` and the assignment must use `<elementReference>smsPhoneInput</elementReference>` (not `ScreenName.smsPhoneInput`).
|
||
- Flow metadata must keep element blocks contiguous (screens, assignments, recordLookups, decisions, loops, choices) to avoid Salesforce Flow XML validation failures. The repo's V4 flow file was normalized accordingly.
|
||
|
||
---
|
||
|
||
## 9. Tests, Validation & CI
|
||
|
||
- Unit tests: ensure `DocusignCompositeEnvelopeBuilderTest` covers:
|
||
- English and Spanish subject/body composition
|
||
- Multi-copy expansion with 1–5 copies
|
||
- SMS flow path: when Contact.Email blank + recipientSmsPhone provided, mailbox placeholder used and `withSmsDelivery` applied
|
||
- Error branches and API failures
|
||
- CI: add a PR validation job that does:
|
||
- sfdx auth to a validation org
|
||
- For changed flow or Apex files, run `sfdx force:source:deploy --checkonly` for those components
|
||
- Fail PR if check-only returns errors
|
||
- Pre-deploy: run check-only deploy to target org before actual deploy. Example local command:
|
||
|
||
```bash
|
||
sfdx force:source:deploy -p force-app/main/default/flows/Docusign_Envelope_Templates_V4.flow-meta.xml,force-app/main/default/classes/DocusignCompositeEnvelopeBuilder.cls -u dev-org --checkonly --testlevel NoTestRun
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Edge Cases and Known Gotchas
|
||
|
||
- If operator edits a flow in the org and does not retrieve+commit the changes, repo and org diverge. Use mdapi `retrieve` or `sf project retrieve` to pull the authoritative version and commit immediately.
|
||
- Flow Builder sometimes reorders or normalizes XML: prefer re-checking contiguity of element blocks after Flow Builder saves.
|
||
- Ensure the Flow variable `recipientSmsPhone` is passed to Apex action and that the assignment uses `smsPhoneInput` as elementReference.
|
||
- The DocuSign API requires an email field on every recipient even when SMS is used; `SMS_PLACEHOLDER_EMAIL` is central and must be kept updated in Apex if changed.
|
||
|
||
---
|
||
|
||
## 11. Deployment Checklist
|
||
|
||
1. Confirm `force-app/main/default/flows/Docusign_Envelope_Templates_V4.flow-meta.xml` matches the active version in org (if you intend to deploy active draft)
|
||
2. Confirm `force-app/main/default/classes/DocusignCompositeEnvelopeBuilder.cls` and related classes/tests are committed
|
||
3. Run `sfdx force:source:deploy --checkonly` for affected components against a validation org
|
||
4. Run Apex tests (or allow CI to run tests during deploy)
|
||
5. Deploy to sandbox, perform a manual Flow Builder inspection of V4
|
||
6. Activate the desired Flow version if runtime activation is needed
|
||
|
||
---
|
||
|
||
## 12. Change Log (high level)
|
||
|
||
- 2.0 (2026-03-25): Updated design to reflect:
|
||
- Flow V4 (SMS path) retrieval & Active flow committed
|
||
- Spanish greeting/signoff and broadened language detection
|
||
- Envelope subject prefix `Docusign: ` and truncation to 100 chars
|
||
- Increased Authorization multi-copy support to 5 copies
|
||
- Flow element and metadata normalization
|
||
|
||
---
|
||
|
||
## 13. Contact & Ownership
|
||
|
||
- Primary developer: Paul Huliganga (update as appropriate)
|
||
- Repo: `composite-envelope-builder`
|
||
- For deployment questions: refer to `docs/DEPLOYMENT_AND_TESTING.md`
|
||
|
||
---
|
||
|
||
*This document was generated to represent the repository state as of March 25, 2026. Update the change log and ownership fields when you make future changes.*
|