docs: update to v1.2 with SMS delivery feature documentation
- design.md v1.2: add section 2.5 (SMS delivery via dfsle.Recipient.withSmsDelivery()); document SMS_PLACEHOLDER_EMAIL constant, resolveRecipients/buildRecipient signatures, Flow V4 structure and decision paths; update component diagram and Request class docs - requirements.md v1.2: add FR-007 (SMS delivery for recipients without email), US-006 user story; update constraints and success criteria - api-reference.md v1.2: add section 11 (SMS delivery via dfsle toolkit); document recipientSmsPhone parameter, withSmsDelivery() usage pattern, Flow V4 integration steps; renumber Reference Links to section 12
This commit is contained in:
Paul Huliganga
parent
e41e43cabd
commit
71a156df78
|
|
@ -1,8 +1,8 @@
|
|||
# API Reference
|
||||
|
||||
**Project**: Salesforce Composite Envelope Builder
|
||||
**Version**: 1.1
|
||||
**Date**: February 23, 2026 (updated March 11, 2026)
|
||||
**Version**: 1.2
|
||||
**Date**: February 23, 2026 (updated March 13, 2026)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -515,7 +515,79 @@ Body:
|
|||
|
||||
---
|
||||
|
||||
## 11. Reference Links
|
||||
## 11. SMS Delivery via dfsle Apex Toolkit (v1.2)
|
||||
|
||||
### 11.1 Overview
|
||||
|
||||
Rather than calling the Docusign REST API directly for SMS delivery, this project uses the native **dfsle Apex Toolkit** method `dfsle.Recipient.withSmsDelivery()`, which is part of the Docusign for Salesforce managed package already installed in the org.
|
||||
|
||||
This approach requires no additional REST endpoints, no extra authentication, and no HTTP callouts beyond what the toolkit already handles.
|
||||
|
||||
### 11.2 `dfsle.Recipient.withSmsDelivery(phone)`
|
||||
|
||||
**Method signature**:
|
||||
```apex
|
||||
dfsle.Recipient withSmsDelivery(String phone)
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `phone` | `String` | Mobile phone number in E.164 format (e.g. `+15551234567`). International numbers must include the country code. |
|
||||
|
||||
**Returns**: A new `dfsle.Recipient` instance with SMS delivery configured (`deliverBySms = true`).
|
||||
|
||||
**Important notes**:
|
||||
- This method sets the delivery method for the signing invitation; it is **not** a 2FA/authentication method.
|
||||
- The Docusign API still requires an `email` field on every recipient even when SMS delivery is configured. When the recipient contact has no email address, a placeholder (`placeholder_email@docusign.com`) is substituted automatically by the Apex layer. No actual email is sent to this address.
|
||||
- Only applied to **Docusign Recipient #1**. The Service Coordinator always uses email delivery.
|
||||
|
||||
### 11.3 Invocable Action Parameter
|
||||
|
||||
The `recipientSmsPhone` input parameter on the `Send_Composite_Envelope` Apex action activates SMS delivery:
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `recipientSmsPhone` | `String` | No | Mobile phone number for SMS delivery. When blank (or not provided), the envelope is sent normally by email. E.164 format preferred: `+15551234567`. |
|
||||
|
||||
### 11.4 Apex Usage Pattern
|
||||
|
||||
```apex
|
||||
// Resolve email from Contact record
|
||||
String recipientEmail = contact.Email;
|
||||
|
||||
// Substitute placeholder when email is blank and SMS phone is provided
|
||||
if (String.isBlank(recipientEmail) && String.isNotBlank(smsPhone)) {
|
||||
recipientEmail = 'placeholder_email@docusign.com';
|
||||
}
|
||||
|
||||
// Build recipient using dfsle toolkit
|
||||
dfsle.Recipient recipient = dfsle.Recipient.fromSource(
|
||||
contact.Name,
|
||||
recipientEmail,
|
||||
null, // phone param (not used here)
|
||||
'Docusign Recipient #1', // role name — must match template exactly
|
||||
new dfsle.Entity(caseRecordId) // source record for merge fields
|
||||
);
|
||||
|
||||
// Enable SMS delivery when phone is provided
|
||||
if (String.isNotBlank(smsPhone)) {
|
||||
recipient = recipient.withSmsDelivery(smsPhone);
|
||||
}
|
||||
```
|
||||
|
||||
### 11.5 Flow V4 Integration
|
||||
|
||||
In `Docusign_Envelope_Templates_V4`, the flow checks the recipient contact's email before presenting the send screen:
|
||||
|
||||
1. **`Get_Recipient_Contact`** — queries the Contact linked to `Docusign_Recipient_1__c`
|
||||
2. **`Is_Recipient_Email_Blank`** — if email is null or empty, routes to the phone collection screen; otherwise proceeds normally
|
||||
3. **`SMS_Phone_Screen`** — collects the mobile number (required text field); stores result in the `recipientSmsPhone` flow variable
|
||||
4. **`Send_Composite_Envelope`** action — receives `recipientSmsPhone` as an input; when non-blank the Apex layer applies `withSmsDelivery()`
|
||||
|
||||
---
|
||||
|
||||
## 12. Reference Links
|
||||
|
||||
- [Docusign REST API Reference](https://developers.docusign.com/docs/esign-rest-api/reference/)
|
||||
- [Composite Templates Guide](https://developers.docusign.com/docs/esign-rest-api/how-to/request-signature-composite-template/)
|
||||
|
|
@ -525,5 +597,13 @@ Body:
|
|||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Last Updated**: February 23, 2026
|
||||
**Document Version**: 1.2
|
||||
**Last Updated**: March 13, 2026
|
||||
**Change Log**:
|
||||
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0 | 2026-02-23 | Initial release |
|
||||
| 1.1 | 2026-03-11 | No changes (version aligned with design/requirements) |
|
||||
| 1.2 | 2026-03-13 | Added section 11 — SMS delivery via `dfsle.Recipient.withSmsDelivery()`; documented `recipientSmsPhone` parameter; renumbered Reference Links to section 12 |
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Design Document
|
||||
|
||||
**Project**: Salesforce Composite Envelope Builder
|
||||
**Version**: 1.1
|
||||
**Date**: February 23, 2026 (updated March 11, 2026)
|
||||
**Version**: 1.2
|
||||
**Date**: February 23, 2026 (updated March 13, 2026)
|
||||
**Author**: Paul Huliganga
|
||||
|
||||
---
|
||||
|
|
@ -56,6 +56,7 @@
|
|||
│ │ │ - @InvocableMethod entry point │ │ │
|
||||
│ │ │ - Input validation │ │ │
|
||||
│ │ │ - Multi-copy template expansion │ │ │
|
||||
│ │ │ - SMS delivery (withSmsDelivery) │ │ │
|
||||
│ │ │ - Composite JSON construction │ │ │
|
||||
│ │ │ - Envelope ID return │ │ │
|
||||
│ │ └──────────────────┬──────────────────────┘ │ │
|
||||
|
|
@ -146,6 +147,9 @@ public class Request {
|
|||
@InvocableVariable(required=false label='Authorization to Release Form Copies')
|
||||
public Integer authReleaseFormCopies; // 1–3; 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
|
||||
}
|
||||
|
|
@ -328,6 +332,118 @@ Duplicate template IDs are intentionally **not deduplicated** when multi-copy is
|
|||
|
||||
---
|
||||
|
||||
## 2.5 SMS Delivery Feature (v1.2)
|
||||
|
||||
### Overview
|
||||
|
||||
When the primary recipient — **Docusign Recipient #1** — has no email address on file, the envelope cannot be delivered via the normal email path. Rather than blocking the send, the system supports SMS delivery using the dfsle Apex Toolkit's native `dfsle.Recipient.withSmsDelivery()` method.
|
||||
|
||||
This feature is surfaced through **Flow V4** (`Docusign_Envelope_Templates_V4`), a copy of V3 with an added pre-send phone-collection step. **Flow V3 is unchanged** and continues to be used for cases where the recipient has an email address.
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
| Decision | Choice | Rationale |
|
||||
|----------|--------|-----------|
|
||||
| Toolkit method | `dfsle.Recipient.withSmsDelivery(phone)` | Native dfsle support; no direct REST API needed |
|
||||
| Email field | `SMS_PLACEHOLDER_EMAIL` constant | Docusign API requires an email on every recipient even for SMS-only delivery; placeholder satisfies this without routing any real email |
|
||||
| Flow version | New V4; V3 unchanged | Preserves the working deployed flow; allows rollout at the operator's pace |
|
||||
| Phone collection | Screen in flow (not Apex) | Keeps Apex free of UI logic; phone can also be supplied programmatically by bypassing the screen |
|
||||
| Recipient scope | Docusign Recipient #1 only | Service Coordinator always has an email; only the primary recipient may lack one |
|
||||
|
||||
### Configuration
|
||||
|
||||
A single constant in `DocusignCompositeEnvelopeBuilder.cls` holds the placeholder email address:
|
||||
|
||||
```apex
|
||||
// ============================================================
|
||||
// SMS DELIVERY: Placeholder email used when the primary recipient
|
||||
// (Docusign Recipient #1) has no email address and SMS delivery is
|
||||
// requested via recipientSmsPhone. Docusign requires an email on
|
||||
// every recipient even when dfsle.Recipient.withSmsDelivery() is used.
|
||||
// ============================================================
|
||||
@TestVisible
|
||||
private static final String SMS_PLACEHOLDER_EMAIL = 'placeholder_email@docusign.com';
|
||||
```
|
||||
|
||||
### Flow V4 Changes
|
||||
|
||||
The following elements were added to `Docusign_Envelope_Templates_V4` (relative to V3):
|
||||
|
||||
| Element | Type | Purpose |
|
||||
|---------|------|---------|
|
||||
| `Get_Recipient_Contact` | Record Lookup | Queries the Contact record linked to `Docusign_Recipient_1__c`; fetches `Id`, `Email`, `Name` |
|
||||
| `Is_Recipient_Email_Blank` | Decision | Checks whether `Get_Recipient_Contact.Email` is null or empty |
|
||||
| `SMS_Phone_Screen` | Screen | Collects the recipient's mobile phone number (E.164, required field); shown only when email is blank |
|
||||
| `recipientSmsPhone` | Variable (String) | Stores the phone number entered on `SMS_Phone_Screen`; passed to the Apex action |
|
||||
|
||||
#### Updated Flow Path (after `Get_Records`)
|
||||
|
||||
```
|
||||
Get_Records → Get_Recipient_Contact → Is_Recipient_Email_Blank
|
||||
│
|
||||
├─ Has Email ──────────────────────────────▶ Is_Language_Selected
|
||||
│
|
||||
└─ No Email → SMS_Phone_Screen (collect phone) ▶ Is_Language_Selected
|
||||
```
|
||||
|
||||
The `recipientSmsPhone` variable is passed to `Send_Composite_Envelope` as a new input parameter. When the recipient has an email the variable is blank and the Apex action behaves identically to V3.
|
||||
|
||||
### Apex Changes
|
||||
|
||||
**`DocusignEnvelopeRequest.cls`** — new `@InvocableVariable`:
|
||||
```apex
|
||||
@InvocableVariable(
|
||||
label='Recipient SMS Phone'
|
||||
description='Mobile phone number for SMS delivery when Docusign Recipient #1 has no email.
|
||||
A placeholder email is substituted automatically. Format: +15551234567 (E.164 preferred).'
|
||||
required=false
|
||||
)
|
||||
global String recipientSmsPhone;
|
||||
```
|
||||
|
||||
**`DocusignCompositeEnvelopeBuilder.cls`** — `resolveRecipients` now accepts `smsPhone` and passes it only to the Docusign Recipient #1 builder:
|
||||
|
||||
```apex
|
||||
private static List<dfsle.Recipient> resolveRecipients(String recordId, String smsPhone) {
|
||||
// ... query Client_Case__c ...
|
||||
// Service Coordinator — always email delivery (null smsPhone)
|
||||
recipients.add(buildRecipient(serviceCoordinatorId, ROLE_SERVICE_COORDINATOR, routingOrder++, recordId, null));
|
||||
// Docusign Recipient #1 — SMS delivery when smsPhone is provided
|
||||
recipients.add(buildRecipient(docusignRecipientId, ROLE_DOCUSIGN_RECIPIENT, routingOrder++, recordId, smsPhone));
|
||||
}
|
||||
```
|
||||
|
||||
`buildRecipient` applies the SMS toolkit method and placeholder email when a phone is supplied:
|
||||
|
||||
```apex
|
||||
private static dfsle.Recipient buildRecipient(
|
||||
Id recipientId, String roleName, Integer routingOrder,
|
||||
String sourceRecordId, String smsPhone) {
|
||||
|
||||
// ... resolve name/email from Contact or User ...
|
||||
|
||||
if (String.isBlank(recipientEmail)) {
|
||||
if (String.isNotBlank(smsPhone)) {
|
||||
recipientEmail = SMS_PLACEHOLDER_EMAIL; // satisfy API requirement
|
||||
} else {
|
||||
throw new IllegalArgumentException('No email found for ' + roleName + ' ...');
|
||||
}
|
||||
}
|
||||
|
||||
dfsle.Recipient recipient = dfsle.Recipient.fromSource(
|
||||
recipientName, recipientEmail, null, roleName, new dfsle.Entity(sourceRecordId)
|
||||
);
|
||||
|
||||
if (String.isNotBlank(smsPhone)) {
|
||||
recipient = recipient.withSmsDelivery(smsPhone); // dfsle native SMS delivery
|
||||
}
|
||||
|
||||
return recipient;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Data Flow
|
||||
|
||||
### 3.1 Sequence Diagram: Send Composite Envelope
|
||||
|
|
@ -748,3 +864,4 @@ Accept: application/json
|
|||
|---------|------|--------|---------|
|
||||
| 1.0 | 2026-02-23 | Paul Huliganga | Initial release |
|
||||
| 1.1 | 2026-03-11 | Paul Huliganga | Added section 2.4 — multi-copy Authorization to Release Information feature; updated component diagram, Request inner class, and sequence diagram |
|
||||
| 1.2 | 2026-03-13 | Paul Huliganga | Added section 2.5 — SMS delivery via `dfsle.Recipient.withSmsDelivery()` for recipients without email; added Flow V4 description, `SMS_PLACEHOLDER_EMAIL` constant, `recipientSmsPhone` parameter; updated component diagram and Request class docs |
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Requirements Document
|
||||
|
||||
**Project**: Salesforce Composite Envelope Builder
|
||||
**Version**: 1.1
|
||||
**Date**: February 23, 2026 (updated March 11, 2026)
|
||||
**Version**: 1.2
|
||||
**Date**: February 23, 2026 (updated March 13, 2026)
|
||||
**Author**: Paul Huliganga
|
||||
|
||||
---
|
||||
|
|
@ -55,6 +55,18 @@ Replace combination templates with **28 single-form templates** (14 forms × 2 l
|
|||
- If "Authorization to Release Information" is not selected, the dialog is skipped entirely and default behaviour is unchanged
|
||||
- The template name used for matching is stored in a single constant (`MULTI_COPY_TEMPLATE_NAME`) in the Apex class and a single string value in the Flow decision, making it straightforward to update if the template is renamed
|
||||
|
||||
#### FR-007: SMS Delivery for Recipients Without Email
|
||||
**Priority**: Medium
|
||||
**Description**: When the primary recipient (Docusign Recipient #1) has no email address, the operator must be able to send the envelope via SMS to the recipient's mobile phone
|
||||
**Acceptance Criteria**:
|
||||
- The flow (V4) checks whether the recipient contact has an email address after template selection
|
||||
- If the email is present, the send proceeds normally (identical behaviour to V3)
|
||||
- If the email is blank, a screen is displayed prompting the operator to enter the recipient's mobile phone number (E.164 format, e.g. `+15551234567`); this field is required
|
||||
- Upon entering a phone number, the envelope is sent and the recipient receives a Docusign signing invitation via SMS instead of email
|
||||
- The Service Coordinator recipient is unaffected and always receives delivery by email
|
||||
- A placeholder email address is substituted automatically in the Apex layer so the Docusign API requirement for an email field is satisfied without routing any real email to the recipient
|
||||
- This functionality is delivered via **Flow V4** (`Docusign_Envelope_Templates_V4`); Flow V3 is unchanged
|
||||
|
||||
#### FR-003: Single Envelope Generation
|
||||
**Priority**: High
|
||||
**Description**: All selected forms must be combined into ONE envelope
|
||||
|
|
@ -227,6 +239,23 @@ Replace combination templates with **28 single-form templates** (14 forms × 2 l
|
|||
- Then the resulting envelope contains 2 copies of the Authorization form plus all other selected forms
|
||||
- And I see the standard success confirmation after sending
|
||||
|
||||
### US-006: Send Envelope via SMS When Recipient Has No Email
|
||||
**As a** Salesforce user
|
||||
**I want to** send a Docusign envelope to a recipient who has no email address
|
||||
**So that** I can complete the signing ceremony without requiring the recipient to have an email account
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Given I am using Flow V4 and the selected Docusign Recipient #1 contact has no email address on file
|
||||
- When I proceed past template selection
|
||||
- Then a screen is displayed informing me that the recipient has no email and that the envelope will be delivered via SMS
|
||||
- And I am prompted to enter the recipient's mobile phone number (required, E.164 format)
|
||||
- When I enter a valid phone number and click "Next"
|
||||
- Then the envelope is sent and the recipient receives a signing invitation by SMS
|
||||
- And the Service Coordinator recipient still receives their invitation by email
|
||||
- And I see the standard success confirmation after sending
|
||||
- Given the recipient contact does have an email address
|
||||
- Then the SMS phone screen is skipped and sending proceeds as normal
|
||||
|
||||
### US-004: View Completed Documents
|
||||
**As a** Salesforce user
|
||||
**I want to** see completed documents attached to the Salesforce record
|
||||
|
|
@ -246,6 +275,7 @@ Replace combination templates with **28 single-form templates** (14 forms × 2 l
|
|||
- **Salesforce Governor Limits**: Must stay within Apex heap size (6 MB synchronous, 12 MB asynchronous), callout limits (100 per transaction), CPU time
|
||||
- **Docusign API Rate Limits**: Respect Docusign API rate limits (varies by plan)
|
||||
- **Template Limit**: Maximum 14 forms per envelope (business rule)
|
||||
- **SMS Delivery**: Requires the dfsle Apex Toolkit (Docusign for Salesforce managed package) version that supports `dfsle.Recipient.withSmsDelivery()`; an email field must always be populated on each recipient (placeholder used automatically)
|
||||
|
||||
### 5.2 Business Constraints
|
||||
- **Single Language Per Envelope**: Cannot mix English and Spanish in one envelope
|
||||
|
|
@ -286,6 +316,7 @@ Replace combination templates with **28 single-form templates** (14 forms × 2 l
|
|||
- ✅ All selected forms sent in ONE envelope
|
||||
- ✅ Documents written back to Salesforce
|
||||
- ✅ No pre-built combination templates needed
|
||||
- ✅ Recipients without email can receive envelopes via SMS (Flow V4)
|
||||
|
||||
### 8.2 Technical Success
|
||||
- ✅ Code coverage >75%
|
||||
|
|
@ -331,6 +362,7 @@ The following are explicitly out of scope for the initial release:
|
|||
|---------|------|--------|---------|
|
||||
| 1.0 | 2026-02-23 | Paul Huliganga | Initial release |
|
||||
| 1.1 | 2026-03-11 | Paul Huliganga | Added FR-006 (multi-copy Authorization to Release Information), US-005, updated constraints |
|
||||
| 1.2 | 2026-03-13 | Paul Huliganga | Added FR-007 (SMS delivery for recipients without email), US-006; updated constraints and success criteria |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue