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

# Requirements Document

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

### 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

### 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 |

---

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