paulh
/
salesforce-composite-envelope-builder
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
salesforce-composite-envelo.../composite-envelope-builder/docs/design_updated.md

12 KiB
Raw Blame History

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:
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.