salesforce-composite-envelope-builder/composite-envelope-builder/docs/design_previous_2026-03-25.md

Design Document (previous)

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

---

1. Architecture Overview

1.1 System Context

┌──────────────────┐
│  Salesforce User │
└────────┬─────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│     Salesforce Platform                  │
│  ┌──────────────┐    ┌───────────────┐  │
│  │ Screen Flow  │───▶│  Apex Class   │  │
│  │ (Template    │    │  (Composite   │  │
│  │  Selection)  │    │   Builder)    │  │
│  └──────────────┘    └───────┬───────┘  │
│                              │           │
└──────────────────────────────┼───────────┘
                               │
                               ▼ HTTPS/REST API
                    ┌──────────────────────┐
                    │  Docusign REST API   │
                    │  (Composite          │
                    │   Templates)         │
                    └──────────────────────┘

1.2 Component Architecture

┌────────────────────────────────────────────────────────┐
│                  Salesforce Org                         │
│                                                          │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Presentation Layer (Screen Flow)               │   │
│  │  - Language selection                            │   │
│  │  - Template display (checkbox collection)        │   │
│  │  - Success/error messaging                       │   │
│  └──────────────────┬──────────────────────────────┘   │
│                     │                                    │
│  ┌─────────────────▼──────────────────────────────┐   │
│  │  Business Logic Layer (Apex)                    │   │
│  │                                                  │   │
│  │  ┌─────────────────────────────────────────┐   │   │
  │  │  │ DocusignCompositeEnvelopeBuilder       │   │   │
│  │  │ - @InvocableMethod entry point          │   │   │
│  │  │ - Input validation                       │   │   │
│  │  │ - Multi-copy template expansion          │   │   │
│  │  │ - SMS delivery (withSmsDelivery)         │   │   │
│  │  │ - Composite JSON construction            │   │   │
│  │  │ - Envelope ID return                     │   │   │
│  │  └──────────────────┬──────────────────────┘   │   │
│  │                     │                            │   │
│  │  ┌─────────────────▼──────────────────────┐   │   │
│  │  │ DocusignAPIService                     │   │   │
│  │  │ - API authentication                    │   │   │
│  │  │ - HTTP callout construction             │   │   │
│  │  │ - Response parsing                      │   │   │
│  │  │ - Error handling                        │   │   │
│  │  └──────────────────┬──────────────────────┘   │   │
│  │                     │                            │   │
│  │  ┌─────────────────▼──────────────────────┐   │   │
│  │  │ DocusignCredentials                    │   │   │
│  │  │ - Credential retrieval                  │   │   │
│  │  │ - Token management                      │   │   │
│  │  └─────────────────────────────────────────┘   │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Data Layer                                   │   │
│  │  - Named Credential (Docusign API creds)     │   │
│  │  - Custom Settings (configuration)            │   │
│  └──────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────┘
                     │
                     ▼ HTTPS REST API
          ┌──────────────────────┐
          │  Docusign Platform   │
          └──────────────────────┘

---

2. Detailed Component Design

2.1 DocusignCompositeEnvelopeBuilder (Main Class)

Purpose: Invocable Apex class that combines multiple Docusign templates into a single envelope

Responsibilities:

• Receive template IDs from Screen Flow
• Validate inputs
• Expand multi-copy templates (e.g. Authorization to Release Information)
• Construct composite template JSON
• Delegate API call to service class
• Return envelope ID to Flow

Methods:

// Flow-invocable entry point
@InvocableMethod(
    label='Send Composite Docusign Envelope' 
    description='Combines multiple templates into one envelope'
)
public static List<Result> sendCompositeEnvelope(List<Request> requests)

// Private helper methods
private static String buildCompositeEnvelopeJSON(
    List<String> templateIds, 
    String recordId,
    String language,
    Map<String, String> customFields
)

private static void validateInputs(Request req)

private static List<String> sortTemplatesAlphabetically(List<String> templateIds)

Inner Classes:

public class Request {
    @InvocableVariable(required=true label='Template IDs')
    public List<String> templateIds;
    
    @InvocableVariable(required=true label='Salesforce Record ID')
    public String recordId;
    
    @InvocableVariable(required=false label='Language')
    public String language; // 'en' or 'es'
    
    @InvocableVariable(required=false label='Email Subject')
    public String emailSubject;
    
    @InvocableVariable(required=false label='Authorization to Release Form Copies')
    public Integer authReleaseFormCopies; // 1–5; only used when that template is selected
    
    @InvocableVariable(required=false label='Recipient SMS Phone')
    public String recipientSmsPhone; // E.164 preferred (+15551234567); triggers SMS delivery for Docusign Recipient #1
    
    @InvocableVariable(required=false label='Custom Fields')
    public Map<String, String> customFields; // For merge fields
}

public class Result {
    @InvocableVariable(label='Envelope ID')
    public String envelopeId;
    
    @InvocableVariable(label='Success')
    public Boolean success;
    
    @InvocableVariable(label='Error Message')
    public String errorMessage;
}

---

2.2 DocusignAPIService (Service Class)

Purpose: Handles all Docusign REST API interactions

Responsibilities:

• Construct HTTP requests
• Make callouts to Docusign API
• Parse responses
• Handle errors and retries
• Log API interactions

Methods:

public static String createCompositeEnvelope(
    String envelopeJSON, 
    DocusignCredentials creds
)

public static HttpResponse callDocusignAPI(
    String endpoint,
    String method,
    String body,
    Map<String, String> headers
)

public static String parseEnvelopeId(HttpResponse response)

private static void logAPICall(
    HttpRequest req,