# Deployment & Testing Guide

Quick reference for deploying the Salesforce Composite Envelope Builder to your org and running tests.

> **Shell Note:** Commands below show both **Bash/WSL** and **PowerShell** variants for Windows Terminal. Choose the one that matches your environment. The `sf` CLI commands are identical across both shells.

---

## Quick Start (Recommended)

### Deploy + Test in One Script

**Bash/WSL:**
```bash
cd /home/paulh/.openclaw/workspace/projects/salesforce-composite-envelope-builder/composite-envelope-builder
bash deploy-to-dev-org.sh
```

**PowerShell (Windows Terminal):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"
bash deploy-to-dev-org.sh
# Or if you prefer native PowerShell (not WSL):
# .\deploy-to-dev-org.sh  (requires WSL bash available)
```

This script handles:
- ✅ Org authorization (opens browser login)
- ✅ Code deployment
- ✅ Unit test execution with code coverage
- ✅ Human-readable results

---

## Manual Commands

### 1. Authorize Your Org (First Time Only)

**Bash/WSL:**
```bash
# For Developer Edition
sf org login web --alias dev-org --instance-url https://login.salesforce.com

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

**PowerShell (Windows Terminal):**
```powershell
# For Developer Edition
sf org login web --alias dev-org --instance-url https://login.salesforce.com

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

You'll be redirected to Salesforce login. Once authorized, the org alias is saved for future deploys.

---

### 2. Deploy Code

**Bash/WSL:**
```bash
cd /home/paulh/.openclaw/workspace/projects/salesforce-composite-envelope-builder/composite-envelope-builder
sf project deploy start --target-org dev-org
```

**PowerShell (Windows Terminal):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"
sf project deploy start --target-org dev-org
```

**Options:**
- `--target-org dev-org` — Use the authorized org alias (replace with your alias if different)
- `--wait 10` — Wait up to 10 minutes for deployment to complete

---

### 3. Run Tests

**Run ALL unit tests with code coverage:**

Bash/WSL:
```bash
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

PowerShell:
```powershell
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

---

**Run ONLY the new handler tests:**

Bash/WSL:
```bash
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --wait 10 --result-format human --target-org dev-org
```

PowerShell:
```powershell
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --wait 10 --result-format human --target-org dev-org
```

---

**Run specific test methods:**

Bash/WSL:
```bash
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --method-names testValidateRequest_Success --wait 10 --result-format human --target-org dev-org
```

PowerShell:
```powershell
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --method-names testValidateRequest_Success --wait 10 --result-format human --target-org dev-org
```

---

**Run tests for a specific class only:**

Bash/WSL:
```bash
# Test the main invocable class
sf apex run test --class-names DocusignCompositeEnvelopeBuilderTest --wait 10 --result-format human --code-coverage --target-org dev-org

# Test the request handler
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --wait 10 --result-format human --code-coverage --target-org dev-org

# Test the API service
sf apex run test --class-names DocusignAPIServiceTest --wait 10 --result-format human --code-coverage --target-org dev-org

# Test the credentials helper
sf apex run test --class-names DocusignCredentialsTest --wait 10 --result-format human --code-coverage --target-org dev-org
```

PowerShell:
```powershell
# Test the main invocable class
sf apex run test --class-names DocusignCompositeEnvelopeBuilderTest --wait 10 --result-format human --code-coverage --target-org dev-org

# Test the request handler
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --wait 10 --result-format human --code-coverage --target-org dev-org

# Test the API service
sf apex run test --class-names DocusignAPIServiceTest --wait 10 --result-format human --code-coverage --target-org dev-org

# Test the credentials helper
sf apex run test --class-names DocusignCredentialsTest --wait 10 --result-format human --code-coverage --target-org dev-org
```

---

**Run ALL tests with JSON output (for parsing):**

Bash/WSL:
```bash
sf apex run test --wait 10 --result-format json --code-coverage --target-org dev-org > test-results.json
```

PowerShell:
```powershell
sf apex run test --wait 10 --result-format json --code-coverage --target-org dev-org | Out-File -FilePath test-results.json
```

---

## Complete Deploy + Test in One Command

**Bash/WSL:**
```bash
cd /home/paulh/.openclaw/workspace/projects/salesforce-composite-envelope-builder/composite-envelope-builder && \
sf project deploy start --target-org dev-org && \
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

**PowerShell (Windows Terminal):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"; `
sf project deploy start --target-org dev-org; `
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

**Alternative PowerShell (using semicolons):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"; sf project deploy start --target-org dev-org; sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

---

## Understanding Test Results

Sample output:
```
Apex Tests
═════════════════════════════════════════════════════════════════

Test Results Summary  [Included Code Coverage]
═════════════════════════════════════════════════════════════════
Outcome: Passed
Tests Ran: 39
Passes: 39
Failures: 0
Skipped: 0
Pass Rate: 100%
Apex Code Coverage: 92%
```

**Key metrics:**
- **Pass Rate** — Percentage of tests that passed (should be 100%)
- **Apex Code Coverage** — Percentage of code executed by tests (should be >80%)
- **Failures** — If > 0, review the failed test names and error messages below

---

## Updating the Multi-Copy Template Name

The "Authorization to Release Information" template name is stored in **two places**. If this template is ever renamed, update both:

### 1. Apex constant — `DocusignCompositeEnvelopeBuilder.cls`

```apex
// Line ~30 in DocusignCompositeEnvelopeBuilder.cls
private static final String MULTI_COPY_TEMPLATE_NAME = 'Authorization to Release Information';
```

Change the string value to match the new template name (partial match is fine — the query uses `LIKE '%<name>%'`).

### 2. Flow decision — `Docusign_Envelope_Templates_V3.flow-meta.xml`

In the `Does_Row_Contain_Auth_Release` decision node, update the `Contains` condition value:

```xml
<conditions>
    <leftValueReference>Scan_For_Auth_Release_Template.Name</leftValueReference>
    <operator>Contains</operator>
    <rightValue>
        <stringValue>Authorization to Release Information</stringValue>  <!-- update here -->
    </rightValue>
</conditions>
```

After editing the XML, redeploy the flow to your org.

---

## Updating Template IDs After Sandbox Refresh

After a sandbox refresh, Docusign template IDs may become stale and need updating with the correct demo/sandbox template IDs.

### Find Your Demo Template IDs

1. Log into your Docusign demo account: **https://demo.docusign.net**
2. Go to **Templates**
3. Click each template — the GUID is in the URL or under **Template ID**
4. Copy the template IDs you need

### Option 1: Developer Console (Quickest)

1. Open **Developer Console** (gear icon → Developer Console)
2. Click **Debug** → **Open Execute Anonymous Window**

**Step 1: View current template IDs:**
```apex
List<dfsle__EnvelopeConfiguration__c> configs = [
    SELECT Id, Name, dfsle__DocuSignId__c 
    FROM dfsle__EnvelopeConfiguration__c
    ORDER BY Name
];
for (dfsle__EnvelopeConfiguration__c c : configs) {
    System.debug(c.Name + ' → ' + c.dfsle__DocuSignId__c);
}
```

Check the **Logs** tab at the bottom for the output.

**Step 2: Update with new template IDs:**
```apex
// Replace template names and IDs with YOUR values
Map<String, String> updates = new Map<String, String>{
    'Template Name 1' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    'Template Name 2' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
};

List<dfsle__EnvelopeConfiguration__c> configs = [
    SELECT Id, Name, dfsle__DocuSignId__c 
    FROM dfsle__EnvelopeConfiguration__c
    WHERE Name IN :updates.keySet()
];

for (dfsle__EnvelopeConfiguration__c c : configs) {
    c.dfsle__DocuSignId__c = updates.get(c.Name);
}
update configs;
System.debug('Updated ' + configs.size() + ' templates');
```

### Option 2: Query Editor (View Only)

In Developer Console → **Query Editor** tab:
```sql
SELECT Id, Name, dfsle__DocuSignId__c, Envelope_Template_Language__c 
FROM dfsle__EnvelopeConfiguration__c 
ORDER BY Name
```

### Option 3: Salesforce UI (Point and Click)

1. Use **App Launcher** → search for **Docusign Envelope Templates**
2. Open each record → **Edit**
3. Update the **DocuSign template ID** field
4. **Save**

---

## Post-Deployment Setup

After successful deployment, configure your Salesforce org:

### 1. Create Docusign Configuration Custom Setting

1. Log into your Salesforce org
2. Go to **Setup** → **Custom Settings**
3. Click **Manage** next to **Docusign Configuration**
4. Click **New**
5. Fill in:
   - **Account Id:** `{your Docusign sandbox account ID}`
   - **Base URL:** `callout:DocusignAPI`
6. Click **Save**

### 2. Create Named Credential for Docusign API

1. Go to **Setup** → **Named Credentials**
2. Click **New Named Credential**
3. Fill in:
   - **Name:** `DocusignAPI`
   - **Label:** `Docusign API`
   - **URL:** `https://demo.docusign.net/restapi/v2.1`
   - **Identity Type:** Named Principal
   - **Authentication Protocol:** OAuth 2.0
   - **Authentication Provider:** DocusignOAuthProvider (if available)
4. Click **Save**

### 3. Update Your Screen Flow

1. Go to **Flow Builder**
2. Create or edit your Screen Flow
3. Add an **Action** to the flow:
   - Action: **Send Composite Docusign Envelope**
   - Input Variables:
     - **Template IDs** — Comma-separated Docusign template IDs
     - **Salesforce Record ID** — {!Record.Id}
     - **Language** — en or es
     - **Email Subject** — Optional custom subject
     - **Authorization to Release Form Copies** — Number of copies (1–3) for the Authorization to Release Information template; populated by the `authReleaseFormCopies` flow variable (defaults to 1)
4. Output Variables:
   - **Envelope ID** — Unique Docusign envelope ID
   - **Success** — Boolean (true/false)
   - **Error Message** — Error details if creation failed
5. Save and test the flow

> **Multi-copy dialog**: If you are using `Docusign_Envelope_Templates_V3`, the flow automatically detects when "Authorization to Release Information" is selected and displays a radio-button screen asking for 1–5 copies before sending. No additional Flow configuration is required for this feature.

---

## Troubleshooting

### Authorization Issues

**Bash/WSL:**
```bash
# If auth fails, try manual URL method:
sf org login web --alias dev-org --instance-url https://login.salesforce.com --json

# Copy the 'url' value and paste into your browser
```

**PowerShell:**
```powershell
# If auth fails, try manual URL method:
sf org login web --alias dev-org --instance-url https://login.salesforce.com --json

# Copy the 'url' value from the output and paste into your browser
```

---

### Deployment Errors

**Bash/WSL:**
```bash
# Check what's in your org
sf project list metadata --target-org dev-org

# Validate without deploying
sf project validate deploy --target-org dev-org
```

**PowerShell:**
```powershell
# Check what's in your org
sf project list metadata --target-org dev-org

# Validate without deploying
sf project validate deploy --target-org dev-org
```

---

### Test Failures

**Bash/WSL:**
```bash
# Run tests with verbose output
sf apex run test --target-org dev-org --result-format human --code-coverage -v
```

**PowerShell:**
```powershell
# Run tests with verbose output
sf apex run test --target-org dev-org --result-format human --code-coverage -v
```

---

## Reference: Classes Deployed

**Apex Classes:**
- `DocusignCompositeEnvelopeBuilder` — Main invocable class (Flows); includes multi-copy template expansion logic
- `DocusignEnvelopeRequest` — Invocable input DTO; includes `authReleaseFormCopies` field (v1.1)
- `DocusignEnvelopeRequestHandler` — Request validation & envelope building (reusable)
- `DocusignAPIService` — Docusign REST API wrapper
- `DocusignCredentials` — Custom settings singleton

**Test Classes:**
- `DocusignCompositeEnvelopeBuilderTest` — Tests for main invocable
- `DocusignEnvelopeRequestHandlerTest` — Tests for request handler (10 test methods)
- `DocusignAPIServiceTest` — Tests for API service
- `DocusignCredentialsTest` — Tests for credentials

**Flows:**
- `Docusign_Envelope_Templates_V3` — Main template selection flow; includes multi-copy dialog for Authorization to Release Information (v1.1)

**Custom Settings:**
- `Docusign_Configuration__c` — Stores Account ID and Base URL

---

## Next Steps After Successful Deploy

1. ✅ Verify all tests pass
2. ✅ Create Docusign Configuration in Salesforce
3. ✅ Set up Named Credential
4. ✅ Create a test Screen Flow
5. ✅ Test with real Docusign templates
6. ✅ Deploy to Production (when ready)

---

For more details, see:
- `docs/deployment-guide.md` — Detailed deployment instructions
- `docs/api-reference.md` — API reference
- `docs/design.md` — Architecture & design decisions

---

## Change Log

| Version | Date | Author | Summary |
|---------|------|--------|---------|
| 1.0 | 2026-02-23 | Paul Huliganga | Initial release |
| 1.1 | 2026-03-11 | Paul Huliganga | Added multi-copy Authorization to Release Information feature; added "Updating the Multi-Copy Template Name" section; updated Screen Flow setup instructions and class reference |