From c4f519fdb9615be30ef35a3ebf2b1bebd71cf0c0 Mon Sep 17 00:00:00 2001 From: Paul Huliganga Date: Wed, 25 Mar 2026 10:21:12 -0400 Subject: [PATCH] docs(design): add updated design document reflecting V4, SMS, i18n, subject and 5-copy support --- .../docs/design_updated.md | 228 ++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 composite-envelope-builder/docs/design_updated.md diff --git a/composite-envelope-builder/docs/design_updated.md b/composite-envelope-builder/docs/design_updated.md new file mode 100644 index 0000000..b69eb38 --- /dev/null +++ b/composite-envelope-builder/docs/design_updated.md @@ -0,0 +1,228 @@ +# 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 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 `smsPhoneInput` (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.*