適用於 Salesforce 的 Adobe Acrobat Sign：開發人員指南

概述

適用於 Salesforce 的 Adobe Acrobat Sign：開發人員指南旨在協助 Salesforce 開發人員瞭解整合 Salesforce 套件與 Adobe Acrobat Sign 所需的物件和參數。

請參閱此文件中的主題以瞭解：

• 開發人員指南
• 更新順序
• 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 開始，所有非同步程序 (包括自動更新和資料對應) 都使用 Queueable 方法，而不是 Future 方法，如 Salesforce 所推薦。
透過此變更，所有新增至 Salesforce 佇列中進行自動更新或資料對應程序的自訂作業都會失敗，並出現此錯誤：「System.LimitException: Too many queueable jobs added to queue:2.」

失敗是因為可排入佇列的程序只能新增一個可排入佇列的子工作，但此配額已由 Acrobat Sign 所使用。 如需詳細資訊，請參閱可排入佇列的 Apex 限制。 

如果合約狀態沒有變更，或資料對應無法正確執行，則可能會顯示此錯誤：「將工作鏈結時，您只能透過 System.enqueueJob 從執行中的工作新增一個工作，換句話說，每個可排入佇列的父工作都只能有一個子工作。 系統不支援從同一個可排入佇列的工作啟動多個子工作。」

若要解決此錯誤，請尋找違規的觸發器、程序產生器或工作流程並加以停用，或將其切換為使用同步呼叫，或排程於稍後執行。

合約範本服務

合約範本服務會以管理套件的全域 Apex 服務之形式顯示。 這可讓管理套件之外的 Apex 程式碼根據現有合約範本載入合約。 類別和所有顯示方法都會標示為全域以允許此類存取。

Apex 服務會透過此叫用類別顯示：echosign_dev1.AgreementTemplateService

方法

 建構函式

全域類別屬性

執行階段變數

echosign_dev1.AgreementTemplateVariable 全域類別有下列兩個全域欄位：

• 名稱：變數名稱，這必須符合合約範本中設定的執行階段變數名稱。
• 數值：載入範本期間使用的變數值。 此值取決於要使用變數之處。 例如，若是收件者，這必須是連絡人、商機或使用者記錄 ID 或電子郵件。 若是文件變數，這必須是附件記錄 ID。

結果

每種方法都會傳回新建立合約記錄的 ID 或擲出例外狀況，而如果在載入作業期間發生錯誤，將會顯示詳細錯誤訊息。

API 服務

Adobe 電子簽署 API 範本服務會顯示為管理套件的全域 Apex 服務。 這可讓管理套件之外的 Apex 程式碼透過這些包裝函式，叫用一組 Adobe 電子簽署 API。 包裝函式大幅簡化了 API 的叫用，因為消費者不需要建立要求及回應資料模型。 此外，消費者也不需要負責將 Salesforce 資料轉換為電子簽署資料模型。 消費者不需要處理大多數的複雜情況。 例如，若要傳送合約，消費者只需傳入合約記錄 ID，服務就會負責查詢，擷取所有相關資料，將資料傳遞到 API，然後剖析結果。

類別和所有顯示方法都會標示為全域以允許此類存取。

• 第 17 版和較舊版本會叫用 SOAP API
• 第 18 版和更新版本會叫用 REST API

Apex 服務會透過下列叫用類別顯示: echosign_dev1.EchoSignApiService

替代收件者的 Apex API 增強功能

從 24.14 版或更新版本開始，更新的 Apex API 可讓您取代或新增替代收件者，且可在全域類別「EchoSignApiService」中存取，我們引進了兩項新元素：

• 全域函數：
  

  /**

  * 輸入參數：

  * toBeChangedRecipientId: SIGN_Recipient__c Id

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

  * changeType：REPLACE 或 ALTERNATE

  */

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

• 全域列舉： RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

為收件者呼叫此 API 的範例代碼 (收件者類型為電子郵件)

// 首先查詢與合約相關聯的所有收件者

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;

// 尋找需要被取代或需要替代收件者的收件者

// 在此情況下，請透過電子郵件尋找收件者。

// 可新增更多條件以尋找要取代的收件者或需要替代收件者的收件者。

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;

    }

}

// 為新的收件者更新電子郵件地址

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

// 將其序列化為 json 字串

String newRecipientStr = JSON.serialize(newRecipient);

Try {

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

} catch (Exception ex) {

    // 處理例外狀況，並視需要重新擲回

}

方法

內部類別

• 全域類別：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 組織之外的外部系統根據現有合約範本載入合約。 請參閱使用 Apex REST 建立 REST API 一文，瞭解有關如何從 Salesforce 中存取和叫用自訂 REST Apex 服務的詳細資訊。 叫用必須提供有效的工作階段 ID，以供驗證和授權使用。

Web 服務會從下列 URL 公開:

https://<instance_name>.salesforce.com/services/apexrest/echosign_dev1/template/load/<template_id>?masterId=<master_id>&varName1=var Value1&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) 欄位更新為對應的值，以在合約物件上叫用各種動作。 一旦欄位值從空白值或其他值變更為下列其中一個值，便會從屬於電子簽署管理套件一部分的觸發器開始執行動作。

• 提醒
• 傳送
• 取消
• 刪除
• 更新

所有動作都是以非同步的未來模式執行，因此狀態將會儲存在合約的「錯誤」欄位中。

回溯相容性變更

更多相關資訊

• 適用於 Salesforce 的 Adobe Acrobat Sign - 安裝指南
• 適用於 Salesforce 的 Adobe Acrobat Sign - 進階自訂指南
• 適用於 Salesforce 的 Adobe Acrobat Sign - 欄位對應和範本
• 適用於 Salesforce 的 Adobe Acrobat Sign - 升級指南
• 適用於 Salesforce 的 Adobe Acrobat Sign - 使用手冊