salesforce-composite-envelope-builder/composite-envelope-builder/docs/requirements.md

# Requirements Document

**Project**: Salesforce Composite Envelope Builder  
**Version**: 1.2  
**Date**: February 23, 2026 (updated March 13, 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
- 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]