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/requirements.md

15 KiB
Raw Blame History

Requirements Document

Project: Salesforce Composite Envelope Builder
Version: 1.2
Date: February 23, 2026 (updated March 15, 2026)
Author: Paul Huliganga

1. Executive Summary

1.1 Purpose

Enable Salesforce users to dynamically select and send multiple Docusign form templates in a single envelope, eliminating the need for pre-built combination templates.

1.2 Business Problem

  • Current system has 42 pre-built templates for various combinations of 14 forms
  • Maintenance burden: every new combination requires a new template
  • Cannot handle all possible combinations (14 forms = 16,384 possible combinations)
  • User confusion: difficult to find the right pre-built combination template

1.3 Solution Overview

Replace combination templates with 28 single-form templates (14 forms × 2 languages). Build custom Apex code to dynamically combine selected templates into one envelope at runtime using Docusign's Composite Templates API.

2. Business Requirements

2.1 Functional Requirements

FR-001: Multi-Language Support

Priority: High
Description: System must support English and Spanish forms
Acceptance Criteria:

  • User selects language before form selection
  • Only templates in selected language are displayed
  • All forms in envelope are in same language

FR-002: Dynamic Form Selection

Priority: High
Description: Users can select any combination of forms to include in envelope
Acceptance Criteria:

  • Forms displayed in alphabetical order by title
  • Checkbox interface for selection (existing Screen Flow UI)
  • Minimum 1 form, maximum 14 forms per envelope
  • User can select all, none, or any combination

FR-006: Multiple Copies of Authorization to Release Information

Priority: Medium
Description: When the "Authorization to Release Information" template (English or Spanish) is selected, users may include 1, 2, or 3 copies of that form in the same envelope
Acceptance Criteria:

  • After template selection, if "Authorization to Release Information" is among the selected templates, an additional dialog screen is displayed before sending
  • The dialog presents a radio-button selection: 1 copy (default), 2 copies, 3 copies
  • If the user selects 2 or 3 copies, the template is added to the envelope that many times, each appearing as a distinct document
  • Additional copies are labelled with a (Copy N) suffix in the envelope document list so they are distinguishable
  • If "Authorization to Release Information" is not selected, the dialog is skipped entirely and default behaviour is unchanged
  • The template name used for matching is stored in a single constant (MULTI_COPY_TEMPLATE_NAME) in the Apex class and a single string value in the Flow decision, making it straightforward to update if the template is renamed

FR-007: SMS Delivery for Recipients Without Email

Priority: Medium
Description: When the primary recipient (Docusign Recipient #1) has no email address, the operator must be able to send the envelope via SMS to the recipient's mobile phone
Acceptance Criteria:

  • The flow (V4) checks whether the recipient contact has an email address after template selection
  • If the email is present, the send proceeds normally (identical behaviour to V3)
  • If the email is blank, a screen is displayed prompting the operator to enter the recipient's mobile phone number (E.164 format, e.g. +15551234567); this field is required
  • Upon entering a phone number, the envelope is sent and the recipient receives a Docusign signing invitation via SMS instead of email
  • The Service Coordinator recipient is unaffected and always receives delivery by email
  • A placeholder email address is substituted automatically in the Apex layer so the Docusign API requirement for an email field is satisfied without routing any real email to the recipient
  • The placeholder email is defined as the constant SMS_PLACEHOLDER_EMAIL in DocusignCompositeEnvelopeBuilder.cls — this is the single location to update if the placeholder address ever needs to change
  • Setup requirement: The Docusign_Recipient_1__c field on the Client Case must be populated with a Contact record. The Contact must have a Name but no Email — a null lookup (no Contact at all) will cause the recipient to be omitted from the envelope entirely
  • This functionality is delivered via Flow V4 (Docusign_Envelope_Templates_V4); Flow V3 is unchanged

FR-003: Single Envelope Generation

Priority: High
Description: All selected forms must be combined into ONE envelope
Acceptance Criteria:

  • One envelope ID returned
  • One email sent to recipients
  • One signing ceremony
  • Documents appear in selected order

FR-004: Consistent Recipients

Priority: High
Description: All forms go to the same 2 recipients for review and signature
Acceptance Criteria:

  • Recipient 1: Review and sign
  • Recipient 2: Review and sign
  • Same roles across all templates
  • Recipients automatically merged by Docusign

FR-005: Salesforce Document Storage

Priority: High
Description: Completed envelope documents written back to initiating Salesforce record
Acceptance Criteria:

  • Documents attached to correct record
  • All forms from envelope stored
  • Metadata preserved (envelope ID, completion date, signers)

2.2 Non-Functional Requirements

NFR-001: Performance

Priority: Medium
Description: Envelope creation must complete within acceptable timeframe
Acceptance Criteria:

  • Apex execution time < 10 seconds
  • No Salesforce governor limit violations
  • REST API call timeout handled gracefully

NFR-002: Maintainability

Priority: High
Description: Code must be easy to maintain and extend
Acceptance Criteria:

  • Clear variable naming
  • Inline comments for complex logic
  • Modular design (separation of concerns)
  • Unit tests with >75% code coverage

NFR-003: Error Handling

Priority: High
Description: System must handle errors gracefully
Acceptance Criteria:

  • API failures logged and reported to user
  • Partial failures do not corrupt data
  • Clear error messages for troubleshooting
  • Retry logic for transient failures (optional Phase 2)

NFR-004: Security

Priority: High
Description: Docusign credentials and API calls must be secure
Acceptance Criteria:

  • Credentials stored in Named Credential or Protected Custom Settings
  • No hardcoded API keys
  • OAuth2 or JWT authentication
  • HTTPS for all API calls

3. Technical Requirements

3.1 Salesforce Platform Requirements

TR-001: Apex Version

  • API version: 60.0 or higher
  • Language: Apex

TR-002: Salesforce Edition

  • Enterprise Edition or higher (required for API access)
  • Screen Flows enabled

TR-003: Permissions

  • Users must have permission to:
    • Execute Flows
    • Send Docusign envelopes
    • Attach files to Salesforce records

3.2 Docusign Requirements

TR-004: Docusign Account

  • Docusign eSignature account (Production or Sandbox)
  • REST API enabled
  • Composite Templates feature available

TR-005: Templates

  • 28 single-form templates created:
    • 14 English templates
    • 14 Spanish templates
  • Each template contains:
    • Document with Docusign tabs
    • 2 recipient roles defined
    • Merge fields for Salesforce data

TR-006: API Credentials

  • Integration Key (Integrator Key)
  • User ID with API access
  • RSA key pair (for JWT) OR OAuth2 client credentials
  • Account ID (GUID)

3.3 Integration Requirements

TR-007: REST API Endpoint

  • Endpoint: /accounts/{accountId}/envelopes
  • Method: POST
  • Request format: JSON (Composite Templates structure)

TR-008: Authentication

  • Preferred: JWT (JSON Web Token)
  • Alternative: OAuth2 Authorization Code Grant
  • Access token refresh handling

4. User Stories

US-001: Select Forms in English

As a Salesforce user
I want to select multiple English forms to send
So that I can send all required documents in one envelope

Acceptance Criteria:

  • Given I am on the form selection screen
  • When I select "English" as the language
  • Then I see all 14 English form templates in alphabetical order
  • And I can check any combination of forms
  • And I can send them in one envelope

US-002: Select Forms in Spanish

As a Salesforce user
I want to select multiple Spanish forms to send
So that I can send all required documents in one envelope in Spanish

Acceptance Criteria:

  • Given I am on the form selection screen
  • When I select "Spanish" as the language
  • Then I see all 14 Spanish form templates in alphabetical order
  • And I can check any combination of forms
  • And I can send them in one envelope

US-003: Send Selected Forms

As a Salesforce user
I want to send my selected forms in one envelope
So that recipients receive all documents together

Acceptance Criteria:

  • Given I have selected 3 forms
  • When I click "Send"
  • Then one envelope is created
  • And one email is sent to recipients
  • And envelope ID is returned to Salesforce
  • And I see a success confirmation

US-005: Request Multiple Copies of Authorization to Release Information

As a Salesforce user
I want to include more than one copy of the Authorization to Release Information form in a single envelope
So that I can obtain multiple authorisations in one signing ceremony

Acceptance Criteria:

  • Given I have selected the "Authorization to Release Information" template (English or Spanish) along with any other forms
  • When I click "Send" on the template selection screen
  • Then a new dialog appears asking "How many copies of this form should be included in the envelope?"
  • And the dialog offers radio-button options: 1 copy (pre-selected), 2 copies, 3 copies
  • When I select 2 copies and click "Next"
  • Then the resulting envelope contains 2 copies of the Authorization form plus all other selected forms
  • And I see the standard success confirmation after sending

US-006: Send Envelope via SMS When Recipient Has No Email

As a Salesforce user
I want to send a Docusign envelope to a recipient who has no email address
So that I can complete the signing ceremony without requiring the recipient to have an email account

Acceptance Criteria:

  • Given I am using Flow V4 and the selected Docusign Recipient #1 contact has no email address on file
  • When I proceed past template selection
  • Then a screen is displayed informing me that the recipient has no email and that the envelope will be delivered via SMS
  • And I am prompted to enter the recipient's mobile phone number (required, E.164 format)
  • When I enter a valid phone number and click "Next"
  • Then the envelope is sent and the recipient receives a signing invitation by SMS
  • And the Service Coordinator recipient still receives their invitation by email
  • And I see the standard success confirmation after sending
  • Given the recipient contact does have an email address
  • Then the SMS phone screen is skipped and sending proceeds as normal

US-004: View Completed Documents

As a Salesforce user
I want to see completed documents attached to the Salesforce record
So that I have a record of what was signed

Acceptance Criteria:

  • Given an envelope was sent and completed
  • When I view the Salesforce record
  • Then I see all signed documents attached
  • And I see envelope metadata (completion date, signers)

5. Constraints

5.1 Technical Constraints

  • Salesforce Governor Limits: Must stay within Apex heap size (6 MB synchronous, 12 MB asynchronous), callout limits (100 per transaction), CPU time
  • Docusign API Rate Limits: Respect Docusign API rate limits (varies by plan)
  • Template Limit: Maximum 14 forms per envelope (business rule)
  • SMS Delivery: Requires the dfsle Apex Toolkit (Docusign for Salesforce managed package) version that supports dfsle.Recipient.withSmsDelivery(); an email field must always be populated on each recipient (placeholder used automatically)

5.2 Business Constraints

  • Single Language Per Envelope: Cannot mix English and Spanish in one envelope
  • Same Recipients: All forms must go to the same 2 recipients

5.3 Timeline Constraints

  • Delivery: Solution needed soon (target: 2-4 weeks)

6. Assumptions

  1. Salesforce Screen Flow already exists and displays templates
  2. Docusign templates are already created with correct tabs and roles
  3. Docusign API credentials are available (or can be configured)
  4. Existing document write-back logic can be reused
  5. Users have appropriate Salesforce and Docusign permissions

7. Dependencies

7.1 Internal Dependencies

  • Salesforce Screen Flow (existing)
  • Docusign templates (must be created)
  • Salesforce record structure (for document attachment)

7.2 External Dependencies

  • Docusign REST API availability
  • Network connectivity for API callouts

8. Success Criteria

8.1 Functional Success

  • ✅ Users can select any combination of forms
  • ✅ All selected forms sent in ONE envelope
  • ✅ Documents written back to Salesforce
  • ✅ No pre-built combination templates needed
  • ✅ Recipients without email can receive envelopes via SMS (Flow V4)

8.2 Technical Success

  • ✅ Code coverage >75%
  • ✅ No Salesforce governor limit violations
  • ✅ Error handling tested
  • ✅ API integration validated

8.3 User Success

  • ✅ Easier form selection (alphabetical list vs. searching for combination)
  • ✅ Faster envelope creation
  • ✅ Reduced maintenance burden

9. Out of Scope (Phase 1)

The following are explicitly out of scope for the initial release:

  1. Custom recipient selection - recipients are fixed per template
  2. Dynamic tab positioning - tabs defined in templates, not runtime
  3. Form preview - no preview before sending
  4. Bulk sending - one envelope at a time
  5. Template versioning - template updates handled manually
  6. Analytics dashboard - no reporting on form selection patterns

10. Future Enhancements (Potential Phase 2)

  1. Dynamic recipient selection: Allow users to override default recipients
  2. Conditional logic: Show/hide forms based on Salesforce data
  3. Form preview: Preview selected forms before sending
  4. Bulk operations: Send envelopes to multiple records
  5. Template management UI: Admin UI for template configuration
  6. Analytics: Track which form combinations are most common
  7. Configurable multi-copy forms: Extend the multi-copy pattern to other templates without code changes (admin-configurable list)

11. Change Log

Version Date Author Summary
1.0 2026-02-23 Paul Huliganga Initial release
1.1 2026-03-11 Paul Huliganga Added FR-006 (multi-copy Authorization to Release Information), US-005, updated constraints
1.2 2026-03-13 Paul Huliganga Added FR-007 (SMS delivery for recipients without email), US-006; updated constraints and success criteria

Document Status: Draft
Next Review: After design document completion
Approvers: [Customer stakeholders]