Summer ‘21のApex Toolkitにおける新機能について
今年の夏にリリースされたDocuSign Apps Launcherのバージョン 3.3では、Apex Toolkitにいくつかの新機能が追加されました。Salesforceレコードへの書き戻しオプションの設定やテンプレート文書の差し替え、さらにはSMSでの受信者へのエンベロープ送信など、すべてApex Toolkitを使って行うことができます。
Apex Toolkitとは？
Apex Toolkitは、エンベロープの設定や送信など、DocuSign関連の機能を利用するために、Apexコード内で呼び出すことができるApexクラス群やオブジェクトのセットです。このツールキットは、Salesforce AppExchangeで提供されているマネージド・パッケージであるDocuSign Apps Launcherをインストールすることで利用可能です。詳しくは、DocuSign Developer CenterのHow to install the Apex Toolkitをご覧ください。
文書ファイルとデータの書き戻し
DocuSign Apps Launcher 3.3以前では、ライトバック・オプションを制御する唯一の方法は、DocuSignエンベロープテンプレートを使用することでした。このバージョン3.3からは、Apex Toolkitでこれらのオプションを直接制御することができます。dfsle.Envelope.withOptionsメソッドを公開しました。このメソッドは、様々なエンベロープや受信者レベルのイベントで、デフォルトの自動配置タグの配置、ドキュメントの書き戻し、データの書き戻しを制御します。
例えば、全員の署名・押印が完了した書類を書き戻すと同時に、商談のステージを更新するには、次のようなApexコードを記述します。
myEnvelope.withOptions(new dfsle.Envelope.Options(
// Whether to populate auto-place tags for default roles
false,
new dfsle.Document.WriteBack(
// Where to link the completed document(s)
opportunityId,
// The completed document(s) file name format
dfsle.Document.WRITE_BACK_ENVELOPE_STATUS_PDF,
// Whether to combine all the documents into a single PDF
true,
// Whether to include the Certificate of Completion (CoC)
true),
// Envelope status event updates
new Map<String, Map<String, Object>> {
// Set Opportunity.StageName to "Closed Won" upon completion
dfsle.Envelope.STATUS_COMPLETED => new Map<String, Object> {
'Opportunity.StageName' => 'Closed Won'
}
},
// Recipient status event updates
new Map<String, Map<String, Object>>()));
更新できるフィールドの数に制限はありませんが、この方法では最小限のフィールドを更新し、新規レコードの作成などの複雑なロジックはプロセスビルダーなどのSalesforceの標準機能を活用することをお勧めします。
SMS配信
SMS配信機能は、SMSによるテキストメッセージを通じて受信者にエンベロープを送信することができ、文書の送信やアクセスの方法を向上させ、ビジネス取引を迅速に行うことができます。この機能がApex toolkitで使用できるようになりました。(訳者注: 現在は、SMSだけの送信はできず、メールアドレスも同時に指定が必要になります)
SMS配信機能をご利用の際は、その機能制限にご注意ください。問題が発生した場合のトラブルシューティングに役立ちます。
Apex ToolkitでSMS配信を利用するには、DocuSign Apps Launcherのインストール時に、SMS配信機能を有効にしたDocuSign開発者アカウントとSalesforceを接続する必要があります。お客様のアカウントでこの機能を有効にする方法については、DocuSign Developer CenterでSMS配信を確認してください。
SMS対応のDocuSignアカウントとDocuSign Apps Launcherを連携させれば、すぐに始められます。
dfsle.Recipient.withSmsDeliveryメソッドを適用するだけで、以下のようにSMS配信を設定することができます。
myRecipient.withSmsDelivery(myRecipient.phone);
この関数は、SMSでエンベロープを受け取る受信者の電話番号を表す文字列を引数として受け取ります。受信者に正しくSMS配信を設定するためには、この値は空ではない文字列で、フォーマットに沿っていなければなりません。
+countryCode phoneNumber
文字列countryCodeの先頭には「+」が付き、残りの値phoneNumberとはスペースで区切られています。以下は、有効と考えられる電話番号の例です。
- 9255550123 (注: デフォルトのカントリーコードは +1 です)
- +1 9255550123
- +1 925-555-0123
- +1 (925)-555-0123
dfsle.Recipient.withSmsDeliveryを適用すると、あとはその受信者を Envelope オブジェクトのインスタンスにアタッチして、署名用の封筒を送信するだけです。例えば、以下のようになります。
for (dfsle.Recipient r : myRecipients) {
r.withSmsDelivery(r.phone); // Set SMS delivery
}
envelope.withRecipients(myRecipients);
EnvelopeService.sendEnvelope(envelope, true);
Apexコードを実行してエンベロープを送信すると、SMS配信を設定した受信者はテキストメッセージでエンベロープを受け取ります。受信者は自分の携帯電話でエンベロープにアクセスし、署名することができます。
以上です。これで、Apex Toolkitを使ってSMSで封筒を送信することができます。
EUAdvancedなど、別の署名方式のサポート
エンベロープの署名時に、電子証明書を使った署名方式(Express/Signature Appliance)や、EUや日本の取締役会議事録の電子署名で認められているようなより本人確認性の高いEUAdvanced方式もサポートされました。
例えば、EUAdvanced方式で署名してもらう場合、dfsle.Recipient.withSignatureProvidersメソッドを利用します。
List<dfsle.SignatureProvider> providers = new List <dfsle.SignatureProvider>{
new dfsle.EUAdvancedAccessCodeProvider('1234')
};
myRecipient = dfsle.Recipient.withSignatureProviders(providers);
文書ファイルの置き換え(テンプレート使用時)
DocuSignテンプレートを使用してエンベロープを送信する際、Apex Toolkitを使用してそのドキュメントを置き換えることができるようになりました。これは、ドキュメントのバージョンが動的に変化する場合に、DocuSignテンプレートに設定されたフィールドや受信者を保持したい場合に便利です。現在は、テンプレートごとに1つの文書の置き換えに制限されています。テンプレートのドキュメントを置き換えるには、 dfsle.Document.withReplacementメソッドを使用します。
例えば、テンプレートドキュメントをファイルレコードにある文書のContentVersionに置き換えるには、次のようなコードを指定します。
myTemplate.withReplacement(dfsle.Document.fromFile(myGeneratedFile));
補足文書
Apexコードの中で補足文書を指定できるようになりました。補足文書は、法的な開示情報や利用規約など、署名を必要としない追加の文書情報を受信者に表示するために使用されます。補足文書を指定するには、dfsle.Document.withSupplementalOptionsメソッドを使用します。例えば、以下のようになります。
myDocument.withSupplementalOptions(new
dfsle.Document.SupplementalOptions(
// Signer must view and accept this document
dfsle.Document.SIGNER_ACKNOWLEDGEMENT_VIEW_ACCEPT,
// Include this document in the combined document download.
true));
PDFフォームのフィールドへの変換
PDFのフォームフィールドを自動的にDocuSignフィールドに変換したい場合、Apex Toolkitで対応できます。dfsle.Document.withPdfOptionsメソッドを使って、PDFフォームフィールドの変換が可能になりました。
myDocument.withPdfOptions(new dfsle.Document.PdfOptions(
// Whether to transform PDF form fields.
true,
// The recipient for which to apply the tags
1));
まとめ
Apex Toolkitは、開発者がSalesforceのApexを使ったカスタム実装にDocuSignのeSignature APIを使用できるようにするものです。最新のアップデートでは、書き戻し、ドキュメント、SMS配信など、エンベロープの設定方法に関するオプションが増えました。Apex Toolkitについてもっと知りたいですか？「Apex Toolkitを使ったDocuSignテンプレートの送信(英語)」や「Apex Toolkitでのタブの新しいサポート(英語)」など、コード例を掲載した他のApex Toolkitブログ記事をご覧ください。
※本ブログはドキュサイン本社のブログ「What’s new in Summer ‘21 with Apex Toolkit」の抄訳に一部加筆した内容になります。