Salesforce 向け Adobe Acrobat Sign：デベロッパーガイド

概要

Salesforce 向け Adobe Acrobat Sign：デベロッパーガイドは、Salesforce パッケージと Adobe Acrobat Sign を統合するために必要なオブジェクトとパラメーターについて Salesforce 開発者が学習できるように作成されています。

この文書のトピックを参照して、詳細を確認してください。

• 開発者ガイドライン
• 更新の順序
• Apex サービス
• API サービス
• Apex バッチサービス
• 契約テンプレート一括作成
• 契約テンプレートサービスバッチ
• REST サービス
• バックグラウンドサービス
• 後方互換性の変更

開発者ガイドライン

• 契約書がいつ完全に署名されたかを知る必要がある場合、更新前または後（使用事例および要件に応じて）に、echosign_dev1__SIGN_Agreement__c オブジェクト上に Apex トリガーを実装します。 echosign_dev1__Status__c フィールドが 署名済み、承認済みまたは他の最終ステータスに変更されると、契約書は完成します。 
• 個別の署名済み PDF がいつ挿入されたかを知る必要がある場合、例えば途中の各署名済み PDF を入手する必要がある場合、Attachment または ContentVersion オブジェクトに Apex トリガーを実装し、挿入後に、親契約書および「- signed.pdf」または「- approved.pdf」または他の最終ステータスで終わる名前を監視します。
• 各受信者がいつ署名または承認したかを知る必要がある場合、更新前または後（使用事例および要件に応じて）に、echosign_dev1__SIGN_Recipients__c オブジェクト上に Apex トリガーを実装します。 echosign_dev1__Status__c フィールドが 署名済み、承認済みまたは他の最終ステータスに変更されると、受信者の作業は完了します。  
• 署名プロセスの一環の特定のイベントがいつ発生したかを知る必要がある場合（契約書が署名用に送信される、リマインダーが送信される、など）、署名イベントオブジェクト（echosign_dev1__SIGN_AgreementEvent__c）にトリガーを作成して、イベントのタイプを確認します。
• 完成した契約書の契約書の最終ステータス名は、「署名済み」、「承認済み」、「同意済み」、「フォーム入力済み」および「配信済み」です。
  
• 終了した契約書の契約書の最終ステータス名は、「取り消し済み / 拒否済み」、「キャンセル / 拒否済み」、「期限切れ」です。

更新順序

v21 では、更新の順序が変更されました。 以下に、契約書およびその関連するオブジェクトが更新される順序を示します。

1. 添付ファイル 
2. 受信者 
3. 契約書（ステータスおよび他の属性）
4. 契約イベント 
5. Chatter フィード 

Apex サービス

Apex メソッドを使用

Acrobat Sign for Salesforce V 21.0 以降、すべての非同期処理（自動更新とデータ マッピングを含む）は、Salesforce で推奨されているとおり、Future メソッドではなく Queueable メソッドを使用します。
この変更により、自動更新またはデータ マッピング処理のために Salesforce キューに追加されるすべてのカスタマイズジョブは、次のエラーで失敗します：「System.LimitException: Too many queueable jobs added to queue:2.」

このエラーは、queueable プロセスで追加できる子 queueable ジョブが 1 つだけで、Acrobat Sign によって既に開始されているために発生します。 詳細については、Queueable Apex の制限を参照してください。 

契約状況が変更されない場合、またはデータマッピングが正しく実行されない場合は、エラー「ジョブをチェーンする場合、System.enqueueJob を使用して実行中のジョブから 1 つのジョブのみを追加できます。つまり、各親の queueable ジョブに存在できる子ジョブは 1 つのみです。 同じ queueable ジョブからの複数の子ジョブ開始はサポートされていません」が表示されることがあります。

このエラーを解決するには、原因となっているトリガー、プロセスビルダー、またはワークフローを探して非アクティブ化するか、同期コールを使用するように切り替えるか、後から行うようにスケジュールします。

契約テンプレートサービス

契約テンプレートサービスは、マネージドパッケージによってグローバル Apex サービスとして公開されます。 そのため、マネージドパッケージ以外の Apex コードでも、既存の契約テンプレートに基づいて契約を読み込むことができます。 クラスおよび公開されているすべてのメソッドは、このようなアクセスを可能にするために global としてマークされています。

Apex サービスは、次の呼び出しクラスを介して公開されます。echosign_dev1.AgreementTemplateService

メソッド

 コンストラクター

グローバルクラスプロパティ

実行時変数

echosign_dev1.AgreementTemplateVariable グローバルクラスには、次の 2 つのグローバルフィールドがあります。

• name：変数名。契約テンプレート内で設定されている実行時変数の名前と一致する必要があります。
• value：テンプレートの読み込み時に使用する変数値。 値は、変数が使用される場所によって異なります。 例えば、受信者の場合は、取引先責任者、リード、ユーザーのレコード ID または電子メールである必要があります。 文書変数の場合は、添付ファイルのレコード ID である必要があります。

結果

すべてのメソッドは、新たに作成された契約レコードの ID を返すか、読み込み操作中に問題が発生した場合は詳細なエラーメッセージと共に例外をスローします。

API サービス

Adobe 電子サイン API テンプレートサービスは、マネージドパッケージによってグローバル Apex サービスとして公開されます。 そのため、マネージドパッケージ以外の Apex コードでも、ラッパーを通じて一連の Adobe 電子サイン API を呼び出すことができます。 ラッパーを使用すると、リクエストとレスポンスによるデータモデルをコンシューマーが作成する必要がないため、API 呼び出しが大幅に簡素化されます。 また、Salesforce データから電子サインデータモデルへの変換をコンシューマーが処理する必要もありません。 複雑な処理のほとんどは、コンシューマーにとっては抽象化されます。 例えば、契約をコンシューマーに送信するには、契約レコード ID を渡すだけで済みます。ID のクエリ、すべての関連データの抽出、API への引き渡し、結果の解析は、サービスによって処理されます。

クラスおよび公開されているすべてのメソッドは、このようなアクセスを可能にするために global としてマークされています。

• v17 以前では、SOAP API が呼び出されます。
• v18 以降では、REST API が呼び出されます。

Apex サービスは、次の呼び出しクラスを通じて公開されます。echosign_dev1.EchoSignApiService

代替受信者用の Apex API の機能強化

バージョン 24.14 以降では、更新された Apex API を使用して、代替受信者の置き換えや追加を行うことができ、グローバルクラス「EchoSignApiService」内でアクセスできます。2 つの新しい要素が導入されました。

• グローバル関数：
  

  /**

  * Input params:

  * toBeChangedRecipientId: SIGN_Recipient__c Id

  * newRecipientStr: JSON string of SIGN_Recipient__c of a new recipient for recipient replacement or alternate

  * changeType: REPLACE or ALTERNATE

  */

  global static void changeRecipient(Id toBeChangedRecipientId, String newRecipientStr, RECIPIENT_CHANGE_TYPE changeType )

• A global enumeration: RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

受信者用にこの API を呼び出すサンプルコード（受信者タイプは電子メール）

// first query all the recipients associated with the agreement

List<SIGN_Recipients__c> recipients = [SELECT Id, echosign_dev1__Agreement__c, echosign_dev1__Email_Address__c, echosign_dev1__ParticipantSet__c, echosign_dev1__Recipient_Type__c, echosign_dev1__Order_Number__c FROM echosign_dev1__SIGN_Recipients__c where echosign_dev1__Agreement__c = 'a0P7X000008Cc1GUAS'];

SIGN_Recipients__c newRecipient = null;

SIGN_Recipients__c replacedRecipient = null;

// find the recipient that needs to be replaced or an alternate

// in this case, find the recipient by its email.

// More conditions can be added to find the recipient that is to be replaced or needs an alternate.

for(SIGN_Recipients__c recipient: recipients) {

    if (rep.echosign_dev1__Email_Address__c == 'someUser@example.com') {

         newRecipient = recipient.clone(false, true, false, false);

         replacedRecipient = recipient;

    }

}

// update emal address for new recipient

newRecipient.echosign_dev1__Email_Address__c = ''someNewUser@abc.com';

// serialize it to json string

String newRecipientStr = JSON.serialize(newRecipient);

Try {

    echosign_dev1.EchoSignApiService.changeRecipient(replacedRecipient.Id, newRecipientStr, EchoSignApiService.RECIPIENT_CHANGE_TYPE.REPLACE);

} catch (Exception ex) {

    // handle the exception and rethrow if needed

}

メソッド

内部クラス

• グローバルクラス：DocumentHistoryEvent

• グローバルクラス：DocumentInfo
  

• グローバルクラス：ParticipantInfo

• グローバルクラス：SendDocumentResult

• グローバルクラス：SigningUrl
  

Apex バッチサービス

電子サインの主な契約アクションを一括レベルで公開して、一連の契約に対して操作を実行できるようにします。 このクラスは、Salesforce Database.Batchable インターフェイスを実装します。 処理できるレコードの数に制限はありません。レコードは 5 件ごとのセットに分割され、各セットが個別のトランザクションとして処理されるので、管理上の制限に従うことができます。

Apex バッチサービスは、次の呼び出しクラスを通じて公開されます。echosign_dev1.EchoSignActionBatch

パラメーター

バッチ操作を初期化するには、次のパラメーターを指定する必要があります。

• 指定したアクションを実行する契約書レコード ID のリスト：アクションは、サポートされている値（通知、送信、キャンセル、削除、更新）のいずれかにすることができます。
• 現在のユーザーセッション ID：更新アクションタイプの場合のみ必要です。
• 送信者のユーザーレコード：一括処理が完了したときに、電子メールでユーザーに通知するために使用されます。

使用例

User submitterUser = UserInfo.getUserId();

EchoSignActionBatch batch = new EchoSignActionBatch( agreementIds, 'Remind', UserInfo.getSessionId(), submitterUser); Id syncProcessId = Database.executeBatch(batch, 5);

契約テンプレート一括作成

SOQL クエリおよび契約テンプレートレコード ID を受け取ります。 クエリの実行によってマスターオブジェクトレコードのセットが取得され、その後、指定された契約テンプレートに対して各レコードが処理されて、契約レコードが生成されます。 このクラスは、Salesforce Database.Batchable インターフェイスを実装します。 処理できるレコードの数に制限はありません。レコードは 5 件ごとのセットに分割され、各セットが個別のトランザクションとして処理されるので、管理上の制限に従うことができます。

SOQL クエリから返されるレコードタイプは、指定された契約テンプレートのマスターオブジェクトタイプと一致する必要があります。 レコードごとに契約テンプレートサービスが呼び出されます。

Apex バッチサービスは、次の呼び出しクラスを通じて公開されます。

echosign_dev1.AgreementTemplateBatch

パラメーター

バッチ操作を初期化するには、次のパラメーターを指定する必要があります。

• 実行する SOQL クエリ：選択したフィールドとしてレコード ID が含まれている必要があります。 その他のフィールドはオプションです。
• 契約テンプレートレコード ID：マスターレコード ID と併用して契約を読み込みます。

使用例

String agreementTemplateId = [SELECT Id from echosign_dev1__Agreement_Template__c where Name = 'Default Template']; String soqlQuery = 'SELECT Id from Contact where Account.IsActive = true';

AgreementTemplateBatch batch = new AgreementTemplateBatch(soqlQuery, agreementTemplateId); Id syncProcessId = Database.executeBatch(batch, 5);

契約テンプレートサービスバッチ

マスターオブジェクトレコード ID の一覧とマスターオブジェクトタイプを受け取ります。その後、クエリが実行され、指定された契約テンプレートに対してそれぞれが処理されて、契約レコードが生成されます。 このクラスは、Salesforce Database.Batchable インターフェイスを実装します。 処理できるレコードの数に制限はありません。レコードは 5 件ごとのセットに分割され、各セットが個別のトランザクションとして処理されるので、管理上の制限に従うことができます。

指定されたマスターオブジェクトタイプは、指定された契約テンプレートのマスターオブジェクトタイプと一致する必要があります。 レコードごとに契約テンプレートサービスが呼び出されます。

Apex バッチサービスは、次の呼び出しクラスを通じて公開されます。

echosign_dev1.AgreementTemplateServiceBatch

パラメーター

バッチ操作を初期化するには、次のパラメーターを指定する必要があります。

• マスターレコード ID の一覧。
• 契約テンプレートレコード ID：マスターレコードと併用して契約を読み込みます。
• マスターレコードのクエリに使用するマスターオブジェクト名。

使用例

String agreementTemplateId = [SELECT Id from echosign_dev1__Agreement_Template__c where Name = 'Default Template'];

AgreementTemplateBatch batch = new AgreementTemplateServiceBatch(new List<Id>{'01p50000000HoMB'}, agreementTemplateId, 'Contact');
Id syncProcessId = Database.executeBatch(batch, 5);

REST サービス

契約テンプレートサービス

契約テンプレートサービスは、マネージドパッケージによって Salesforce REST Web サービスとして公開されます。 そのため、Salesforce 組織外の外部システムでも、既存の契約テンプレートに基づいて契約を読み込むことができます。 Salesforce 内からカスタム REST Apex サービスに対してアクセスおよび呼び出しをおこなう方法について詳しくは、Apex REST を使用した REST API の作成を参照してください。 呼び出しの際は、認証と承認のために有効なセッション ID を指定する必要があります。

Web サービスは、次の URL で公開されます。

https://<インスタンス名>.salesforce.com/services/apexrest/echosign_dev1/template/load/<テンプレート ID>?masterId=<マスター ID>&varName1=varValue1&varName2=varValue2

テンプレート ID

URL の最後の部分は、現在の Salesforce 組織で契約の読み込みに使用される契約テンプレートレコードの ID です。 URL のこの部分は省略可能です。 省略すると、デフォルトとマークされている契約テンプレートが読み込まれます。 テンプレート ID を省略し、デフォルトの契約テンプレート ID が存在しない場合は、エラーが返されます。

テンプレート ID には、15 文字または 18 文字の形式を使用できます。

マスター ID

masterId パラメーターには、特定の契約テンプレートから契約を読み込むために使用するマスターレコードを指定します。 このパラメーターは省略可能ですが、契約テンプレートでマスターオブジェクトタイプを指定し、テンプレート内でそのマスターオブジェクトを参照している場合は、指定する必要があります。

マスター ID には、15 文字または 18 文字の形式を使用できます。

実行時変数

実行時変数として任意の追加パラメーターを名前と値のペアで指定すると、契約テンプレートで指定されている実行時変数への入力に使用されます。

結果

REST Web サービスから、以下のフィールドを含む LoadResult オブジェクトが返されます。

• agreementId：契約の読み込み操作が成功した場合、新しく作成された契約レコードの ID が含まれます。
• error：契約の読み込み中にエラーが発生した場合は、詳細なエラーメッセージが含まれます。

バックグラウンドサービス

バックグラウンドサービス機能を使用すると、パッケージのコンシューマーは「バックグラウンドアクション」（echosign_dev1 Background_Actions c）フィールドを対応する値に更新することによって、契約オブジェクトに対して様々なアクションを呼び出すことができます。 フィールドが空白値または何らかの値から以下の値のいずれかに変更されると、電子サインマネージドパッケージの一部であるトリガーからアクションが実行されます。

• Remind
• Send
• Cancel
• Delete
• Update

すべてのアクションは非同期機能モードで実行されるため、ステータスは契約の「エラー」フィールドに格納されます。

後方互換性の変更

その他の関連ヘルプ

• Salesforce 用 Adobe Acrobat Sign - インストールガイド
• Salesforce 用 Adobe Acrobat Sign - 高度なカスタマイズに関するガイド
• Salesforce 用 Adobe Acrobat Sign - フィールドマッピングおよびテンプレート
• Salesforce 用 Adobe Acrobat Sign - アップグレードガイド
• Salesforce 用 Adobe Acrobat Sign - ユーザーガイド