15 KiB

Raw Blame History

Deployment Guide

Project: Salesforce Composite Envelope Builder
Version: 1.0
Date: February 23, 2026

1. Prerequisites

1.1 Salesforce Requirements

Edition: Enterprise Edition or higher (required for API access)
User Permissions:
- API Enabled
- Modify All Data (for deployment)
- Manage Flows (for Flow updates)
Features Enabled:
- Screen Flows
- Apex Classes

1.2 Docusign Requirements

Account: Docusign eSignature (Production or Sandbox)
API Access: Enabled
Templates: 28 single-form templates created (14 English + 14 Spanish)
User Role: Sender or higher

1.3 Development Tools

VS Code with Salesforce Extension Pack
Salesforce CLI (sf CLI version 2.0+)
Git for version control

2. Docusign Configuration

2.1 Create Integration Key

Step 1: Navigate to Apps & Keys

Log in to Docusign
Go to Settings → Apps and Keys
Click Add App and Integration Key

Step 2: Configure Integration

App Name: Salesforce Composite Envelope Builder
Integration Type: JWT (JSON Web Token)
Redirect URI: Not required for JWT
Secret Key: Save securely (will be shown once)

Step 3: Generate RSA Key Pair

Click Generate RSA
Download private key (PEM file)
Copy public key (will be added to Salesforce)

Step 4: Grant Consent

Click Grant Consent button
Authenticate as Docusign admin user
Accept permissions

Step 5: Note Important Values

Integration Key (GUID): e.g., a1b2c3d4-...
User ID (GUID of API user): e.g., f9876543-...
Account ID (GUID): e.g., 12345678-...
Base URL: e.g., https://na3.docusign.net/restapi/v2.1

2.2 Create Templates

For each of 14 forms, create 2 templates (English + Spanish):

Go to Templates → New → Use a Template
Upload PDF document
Add fields (signature tabs, text fields, etc.)
Define recipients:
- Role 1: Signer 1 (routing order 1)
- Role 2: Signer 2 (routing order 2)
Name template clearly:
- Format: [Form Name] - [Language]
- Example: Form A - English, Form A - Spanish
Save template
Note template ID (GUID)

Template Naming Convention (for alphabetical sorting):

Form A - Credit Application - English
Form A - Credit Application - Spanish
Form B - Income Verification - English
Form B - Income Verification - Spanish
... (continue alphabetically)

3. Salesforce Configuration

3.1 Create Named Credential

Option 1: External Credential (Recommended for JWT)

Step 1: Create External Credential

Setup → Named Credentials → External Credentials → New
Label: Docusign JWT Auth
Name: DocusignJWTAuth
Authentication Protocol: Custom
Identity Type: Named Principal
Click Create

Step 2: Add Custom Headers

Open External Credential → Custom Headers → New
Add header:
- Header Field Name: Authorization
- Header Field Value: Bearer {!$Credential.DocusignJWTAuth.AccessToken}

Step 3: Create Named Credential

Setup → Named Credentials → New Named Credential
Label: Docusign API
Name: DocusignAPI
URL: https://na3.docusign.net/restapi/v2.1 (or your data center)
External Credential: DocusignJWTAuth
Enabled for Callouts: Checked
Click Save

Option 2: Legacy Named Credential (Simpler but less flexible)

Setup → Named Credentials → New Legacy
Label: Docusign API
Name: DocusignAPI
URL: https://na3.docusign.net/restapi/v2.1
Identity Type: Named Principal
Authentication Protocol: OAuth 2.0
Authentication Provider: (Create new - see below)
Scope: signature impersonation
Save

Create Authentication Provider:

Setup → Auth. Providers → New
Provider Type: Open ID Connect
Name: Docusign OAuth
Consumer Key: {Integration Key from Docusign}
Consumer Secret: {Secret from Docusign}
Authorize Endpoint URL: https://account-d.docusign.com/oauth/auth
Token Endpoint URL: https://account-d.docusign.com/oauth/token
Default Scopes: signature impersonation
Save

3.2 Create Custom Settings (for Account ID)

Step 1: Create Custom Setting

Setup → Custom Settings → New
Label: Docusign Configuration
Object Name: Docusign_Configuration
Setting Type: Hierarchy
Add custom fields:
- Account_Id__c (Text, 255)
- Base_URL__c (Text, 255)
Save

Step 2: Manage Custom Setting

Setup → Custom Settings → Docusign Configuration → Manage
Click New (organization-wide default)
Account Id: {Docusign Account GUID}
Base URL: https://na3.docusign.net/restapi/v2.1
Save

3.3 Create Remote Site Settings

Setup → Remote Site Settings → New Remote Site
Remote Site Name: Docusign_API
Remote Site URL: https://na3.docusign.net
Active: Checked
Save

Add additional sites (if using sandbox or different data center):

https://demo.docusign.net (Docusign Sandbox)
https://account-d.docusign.com (OAuth endpoints)

4. Code Deployment

4.1 Clone Repository (if using Git)

git clone https://github.com/your-org/salesforce-composite-envelope-builder.git
cd salesforce-composite-envelope-builder/composite-envelope-builder

4.2 Authorize Salesforce Org

Sandbox:

sf org login web --alias my-sandbox --instance-url https://test.salesforce.com

Production:

sf org login web --alias my-production --instance-url https://login.salesforce.com

4.3 Deploy to Sandbox

sf project deploy start --target-org my-sandbox

Expected output:

Deploying v60.0 metadata to my-sandbox using the v60.0 SOAP API
Status: Succeeded
Component Deployed:
   ApexClass DocusignCompositeEnvelopeBuilder
   ApexClass DocusignEnvelopeRequest
   ApexClass DocusignEnvelopeRequestHandler
   ApexClass DocusignEnvelopeResult
   ApexClass DocusignCompositeEnvelopeBuilderTest
   ApexClass DocusignEnvelopeRequestHandlerTest

Note: The older `DocusignAPIService` / `DocusignCredentials` classes and their tests are part of a legacy REST-based implementation. The active implementation uses the `dfsle` toolkit and does not require those classes; include them only if you intentionally retain the legacy REST helpers.

4.4 Run Unit Tests

sf apex run test --class-names DocusignCompositeEnvelopeBuilderTest --target-org my-sandbox --wait 5 --result-format human

Expected output:

Test Success  1 tests ran, 1 passed, 0 failed, 0 skipped
Code Coverage  85% (target: 75%)

4.5 Validate Production (without deploying)

sf project deploy validate --target-org my-production --test-level RunLocalTests

4.6 Deploy to Production

sf project deploy start --target-org my-production --test-level RunLocalTests

5. Flow Configuration

5.1 Update Existing Screen Flow

Step 1: Open Flow in Flow Builder

Setup → Flows → [Your Form Selection Flow]
Click Edit

Step 2: Modify Template Loop Logic

Old Logic (sends one envelope per template):

Loop through selected templates
  └─ Create envelope for template

New Logic (sends one envelope with all templates):

Get selected templates (checkbox collection)
  └─ Apex Action: Send Composite Envelope
       Input: templateIds (checkbox collection)
       Output: envelopeId

Step 3: Add Apex Action Element

Drag Action element onto canvas (after template selection screen)
Action: Send Composite Docusign Envelope
Label: Send Composite Envelope
API Name: Send_Composite_Envelope
Set Input Values:
- templateIds = {!SelectedTemplateIds} (collection from checkboxes)
- recordId = {!recordId} (from flow start)
- language = {!SelectedLanguage} (from language selection)
- emailSubject = "Please review and sign these forms"
Store Output Values:
- envelopeId → {!EnvelopeId} (text variable)
- success → {!Success} (boolean variable)
- errorMessage → {!ErrorMessage} (text variable)

Step 4: Add Decision Element (Success/Error)

Drag Decision element after Apex Action
Outcome 1: Success
- Condition: {!Success} Equals true
- Next: Show success screen
Outcome 2: Error
- Default outcome
- Next: Show error screen (with {!ErrorMessage})

Step 5: Remove Old Loop

Delete old loop element that sent individual envelopes
Delete old Apex actions (if any) for single-template sending

Step 6: Save and Activate

Click Save As → New version
Click Activate

6. Testing

6.1 Unit Test Verification

Run all tests:

sf apex run test --wait 10 --result-format human --code-coverage --target-org my-sandbox

Expected code coverage: >75% on all classes

6.2 Integration Test (Manual)

Test Case 1: Send 3 Templates (Happy Path)

Navigate to Salesforce record
Launch Screen Flow
Select language: English
Check 3 templates: Form A, Form B, Form C
Click Send
Expected:
- Success message shown
- Envelope ID displayed
- One envelope created in Docusign
- Three documents in envelope
- Recipients receive one email

Test Case 2: Send 1 Template (Minimum)

Select 1 template only
Expected: Envelope created with 1 document

Test Case 3: Send 14 Templates (Maximum)

Select all 14 templates
Expected: Envelope created with 14 documents

Test Case 4: Spanish Language

Select language: Spanish
Select 2 Spanish templates
Expected: Envelope created with Spanish documents

Test Case 5: Error Handling (Invalid Template)

Manually modify Apex to use invalid template ID
Expected: Error message displayed, no envelope created

6.3 Performance Test

Measure Apex execution time:

Enable Debug Logs (Setup → Debug Logs)
Send envelope with 14 templates
Review log file
Expected: Execution time < 10 seconds

7. Monitoring

7.1 Debug Logs

Enable for API User:

Setup → Debug Logs → New
Traced Entity Type: User
Traced Entity Name: [API User]
Log Level: FINEST (for troubleshooting) or INFO (for production)
Expiration: 1 day (or desired duration)

Review Logs:

Setup → Debug Logs
Click View on recent log
Search for:
- REQUEST_BODY (Docusign API request JSON)
- RESPONSE_BODY (Docusign API response)
- CalloutException (errors)

7.2 Custom Logging (Optional)

Create Custom Object for API Logs:

Setup → Object Manager → Create → Custom Object
Object Name: Docusign API Log
API Name: Docusign_API_Log__c
Add fields:
- Envelope_Id__c (Text, 255)
- Template_Count__c (Number, 0 decimals)
- Status__c (Picklist: Success, Error)
- Error_Message__c (Long Text Area, 32,000)
- Request_Time__c (Date/Time)
- Duration_Ms__c (Number, 0 decimals)

Log API calls in Apex:

Docusign_API_Log__c log = new Docusign_API_Log__c(
    Envelope_Id__c = envelopeId,
    Template_Count__c = templateIds.size(),
    Status__c = 'Success',
    Request_Time__c = System.now(),
    Duration_Ms__c = durationMs
);
insert log;

8. Rollback Plan

8.1 Quick Rollback (Deactivate Flow)

If issues arise in production:

Setup → Flows → [Your Flow]
Deactivate current version
Activate previous version (before composite envelope changes)

8.2 Full Rollback (Remove Apex)

sf project deploy start --manifest manifest/destructiveChanges.xml --target-org production

destructiveChanges.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>DocusignCompositeEnvelopeBuilder</members>
        <members>DocusignAPIService</members>
        <members>DocusignCredentials</members>
        <members>DocusignCompositeEnvelopeBuilderTest</members>
        <members>DocusignAPIServiceTest</members>
        <members>DocusignCredentialsTest</members>
        <name>ApexClass</name>
    </types>
    <version>60.0</version>
</Package>

9. Post-Deployment Checklist

Named Credential configured and tested
Custom Settings populated with Account ID
Remote Site Settings added
Apex classes deployed (100% coverage)
Unit tests pass
Screen Flow updated and activated
Integration test completed successfully
Debug logs reviewed (no errors)
User training completed
Documentation updated
Rollback plan tested

10. Troubleshooting

10.1 Common Issues

Issue: USER_AUTHENTICATION_FAILED error
Cause: Access token expired or invalid
Solution:

Verify Named Credential configuration
Check Integration Key and User ID in Docusign
Re-grant consent if needed

Issue: INVALID_REQUEST_PARAMETER - Template ID not found
Cause: Template doesn't exist or is in different account
Solution:

Verify template IDs in Docusign
Ensure using correct Docusign account (sandbox vs. production)

Issue: Governor limit exceeded (Heap size)
Cause: Too many templates or large JSON payload
Solution:

Reduce number of templates per envelope
Optimize JSON construction (avoid unnecessary string concatenation)

Issue: Flow shows no templates
Cause: Flow query not finding templates
Solution:

Check Flow SOQL query (if using custom object for template list)
Verify Docusign template naming convention matches Flow filter

11. Maintenance

11.1 Regular Tasks

Weekly:

Review debug logs for errors
Check Docusign API usage (approaching rate limits?)

Monthly:

Review custom object logs (if implemented)
Update templates as needed

Quarterly:

Review access token expiry settings
Update Apex classes if Docusign API changes

11.2 Template Updates

When adding a new form template:

Create template in Docusign (English + Spanish versions)
Update Flow template list (if hardcoded)
Test envelope creation with new template
Update user documentation

12. Support

12.1 Internal Support

Salesforce Admin: [Contact info]
Docusign Admin: [Contact info]
Developer: Paul Huliganga

12.2 External Resources

Salesforce Support: https://help.salesforce.com
Docusign Support: https://support.docusign.com
Docusign Developer Center: https://developers.docusign.com

Document Version: 1.0
Last Updated: February 23, 2026
Next Review: After first production deployment

15 KiB Raw Blame History