478 lines
14 KiB
Markdown
478 lines
14 KiB
Markdown
# 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, 2, or 3 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 |
|