salesforce-composite-envelope-builder/composite-envelope-builder/QUICK_START.md

# Quick Start Guide

## ✅ Phase 2 Complete: Code Development

All Apex classes and tests have been created! Here's what you have:

### 📦 Code Files Included in This Package

**Main Classes:**
1. `DocusignCompositeEnvelopeBuilder.cls` - Invocable method for Flow integration (uses dfsle toolkit)
2. `DocusignEnvelopeRequest.cls` - Invocable request parameter object
3. `DocusignEnvelopeRequestHandler.cls` - Request validation helper
4. `DocusignEnvelopeResult.cls` - Invocable result object

**Test Classes:**
 - `DocusignCompositeEnvelopeBuilderTest.cls`
 - `DocusignEnvelopeRequestHandlerTest.cls`

**Notes on legacy artifacts:**
- The repository contains a legacy `Docusign_Configuration__c` custom object and older REST-helper classes in docs, but the active implementation uses the `dfsle` (DocuSign for Salesforce managed package) toolkit and `dfsle__EnvelopeConfiguration__c` records. The legacy custom setting/object is not required for the current Flow + Apex approach.

**All `.cls-meta.xml` files** use API version 60/61 as shown in each file.

---

## 🚀 Next Steps (Deployment)

### Step 1: Open Project in VS Code

```bash
cd ~/.openclaw/workspace/projects/salesforce-composite-envelope-builder/composite-envelope-builder
code .
```

### Step 2: Install Salesforce Extension Pack (if not already installed)

In VS Code:
1. Open Extensions (Ctrl+Shift+X)
2. Search for "Salesforce Extension Pack"
3. Click Install

### Step 3: Authorize Your Salesforce Org

**For Sandbox:**
```bash
sf org login web --alias my-sandbox --instance-url https://test.salesforce.com
```

**For Production:**
```bash
sf org login web --alias my-production --instance-url https://login.salesforce.com
```

This will open a browser window. Log in with your Salesforce credentials.

### Step 4: Set Default Org

```bash
sf config set target-org my-sandbox
```

### Step 5: Deploy to Sandbox

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

Expected output:
```
Deploying v61.0 metadata to my-sandbox
Status: Succeeded

Component Deployed:
  ApexClass DocusignCompositeEnvelopeBuilder
  ApexClass DocusignAPIService
  ApexClass DocusignCredentials
  ApexClass DocusignCompositeEnvelopeBuilderTest
  ApexClass DocusignAPIServiceTest
  ApexClass DocusignCredentialsTest
  CustomObject Docusign_Configuration__c
```

### Step 6: Run Unit Tests

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

Expected output:
```
=== Test Summary ===
Outcome: Passed
Tests Ran: 39
Passing: 39
Failing: 0
Skipped: 0
Pass Rate: 100%
Code Coverage: 85%+
```

### Step 7: DocuSign Integration / Credentials (note)

- The current implementation uses the `dfsle` Apex Toolkit from the DocuSign for Salesforce managed package to send composite envelopes. That toolkit stores and references its templates/configuration using managed-package objects such as `dfsle__EnvelopeConfiguration__c`.

- You do NOT need to create the legacy Named Credential / custom setting (`Docusign_Configuration__c`) for the dfsle-based flow. Ensure the `DocuSign for Salesforce (dfsle)` managed package is installed and its envelope configurations/templates exist in Production.

- If you intentionally plan to use the older REST-based helper classes (legacy), then follow the steps below **only**:
  1. Create a Named Credential (Setup → Named Credentials → New)
     - Example name: `DocusignAPI`
     - Example URL: `https://na3.docusign.net/restapi/v2.1`
  2. (Optional legacy) Configure `Docusign_Configuration__c` custom setting/object with `Account_Id__c` and `Base_URL__c` if your older REST helpers require it.
  3. Add Remote Site or appropriate callout permissions for external DocuSign endpoints.

### Step 8: Update Screen Flow

See `docs/deployment-guide.md` section 5 for detailed Flow configuration steps.

**Summary:**
1. Open your existing form selection Flow
2. Add Apex Action element (after template selection)
3. Select action: `Send Composite Docusign Envelope`
4. Map inputs:
   - `templateIds` → `{!SelectedTemplateIds}` (from checkboxes)
   - `recordId` → `{!recordId}`
   - `language` → `{!SelectedLanguage}`
      - `emailSubject` → "Please review and sign these forms"
      - Note: The Apex layer will prefix the subject with `Docusign: ` automatically and will truncate the final subject to 100 characters to satisfy Docusign limits.
5. Store outputs:
   - `envelopeId` → `{!EnvelopeId}`
   - `success` → `{!Success}`
   - `errorMessage` → `{!ErrorMessage}`
6. Add Decision element for success/error handling
7. Save & Activate

### Step 9: Test Integration

1. Navigate to Salesforce record
2. Launch Screen Flow
3. Select language: English
4. Check 2-3 templates
5. Click Send
6. Verify:
   - Success message shown
   - Envelope ID displayed
   - Check Docusign: envelope created with multiple documents
   - Recipients receive ONE email

---

## 📚 Documentation

All docs are in the `docs/` folder:

- **requirements.md** - What we're building and why
- **design.md** - Architecture, sequence diagrams, data flow
- **api-reference.md** - Docusign REST API details
- **deployment-guide.md** - Complete deployment instructions

---

## 🧪 Test Coverage Details

**DocusignCompositeEnvelopeBuilderTest** (12 methods):
- ✅ Success with 3 templates
- ✅ Single template (minimum)
- ✅ 14 templates (maximum)
- ✅ Duplicate template handling
- ✅ Custom fields support
- ✅ Validation: no templates
- ✅ Validation: too many templates (>14)
- ✅ Validation: missing record ID
- ✅ API error 400 (bad request)
- ✅ API error 401 (unauthorized)
- ✅ JSON builder test

**DocusignAPIServiceTest** (14 methods):
- ✅ Successful envelope creation
- ✅ Parse envelope ID
- ✅ Parse envelope ID missing
- ✅ Handle errors: 400, 401, 403, 404, 429, 500
- ✅ Retry logic (transient failures)
- ✅ Build HTTP request
- ✅ Execute with retry (non-retryable error)

**DocusignCredentialsTest** (13 methods):
- ✅ Singleton pattern
- ✅ Load from Custom Settings
- ✅ Get access token, account ID, base URL
- ✅ Validate success
- ✅ Validate failures: missing account ID, base URL, token
- ✅ Set test credentials
- ✅ Reset instance
- ✅ Missing Custom Settings error
- ✅ Named Credential format

**Total: 39 test methods across 6 classes**

---

## 🎯 Project Status

| Phase | Status |
|-------|--------|
| Requirements & Design | ✅ Complete |
| Apex Code Development | ✅ Complete |
| Unit Tests | ✅ Complete (39 tests) |
| Documentation | ✅ Complete (56+ KB) |
| Deployment | ⏳ Ready to deploy |
| Flow Integration | ⏳ Awaiting deployment |
| Production Testing | ⏳ Next |

---

## 💡 Tips

**Before Deploying:**
- Review `docs/deployment-guide.md` sections 2-3 for Docusign setup
- Have your Docusign Integration Key ready
- Know your Docusign Account ID

**After Deploying:**
- Run all tests to verify 100% pass rate
- Check debug logs for any issues
- Test with 1 template first, then multiple

**Flow Modification:**
- Keep your existing template selection UI
- Replace the loop that sends individual envelopes
- Add the Apex Action in place of the loop

**SMS Delivery Setup (Flow V4):**
- Use **Flow V4** (`Docusign_Envelope_Templates_V4`) when recipients may not have an email address
- The `Docusign_Recipient_1__c` field on the Client Case **must be populated** with a Contact — a null lookup causes the recipient to be omitted from the envelope entirely
- To trigger SMS delivery: link the Contact to the case but **leave the Contact's Email field blank** — the flow detects this and prompts the operator for a mobile number
- The placeholder email (`placeholder_email@docusign.com`) substituted by Apex is defined as the constant `SMS_PLACEHOLDER_EMAIL` in `DocusignCompositeEnvelopeBuilder.cls` — **update the constant there** if the address ever needs to change

---

## ❓ Need Help?

Check the troubleshooting section in `docs/deployment-guide.md` (section 10) for common issues and solutions.

---

**Project Created:** February 23, 2026  
**Developer:** Paul Huliganga  
**Ready to Deploy:** YES! 🚀