适用于 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 开始，所有异步流程（包括自动更新和数据映射）均按照 Salesforce 的建议使用 Queueable 方法，而非 Future 方法。
\n此更改后，所有添加到 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 全局类有以下两个全局字段：

• name：变量名称，必须与协议模板中配置的运行时变量名称相匹配。
• value：在模板加载过程中使用的变量值。 该值取决于使用变量的位置。 例如，对于收件人，它必须是联系人、潜在客户、用户记录 ID 或电子邮件。 对于文档变量，它必须是附件记录 ID。

结果

每种方法都会返回新创建的协议记录 ID，或者，如果加载操作期间出错，会抛出异常和详细错误信息。

API 服务

Adobe e-Sign API 模板服务通过受管理包作为一项全局 Apex 服务公开。 这允许受管理包之外的 Apex 代码通过这些包装器调用一组 Adobe e-Sign API。 包装器极大地简化了 API 调用，因为使用者不需要创建请求和响应数据模型。 此外，使用者不需要处理 Salesforce 数据到 e-Sign 数据模型的转换。 这为使用者减少了很多复杂操作。 例如，要发送使用者刚刚通过协议记录 ID 传入的协议，该服务将处理查询操作，抽取所有相关数据，传递给 API 并解析结果。

类和所有公开的方法都标记为全局以允许此类访问。

• v17 及以下版本调用 SOAP API
• v18 及以上版本调用 REST API

Apex 服务通过以下调用类公开：echosign_dev1.EchoSignApiService

针对替代收件人的 Apex API 增强功能

从版本 24.14 或更高版本开始，更新后的 Apex API 允许您替换或添加替代收件人，并且可以在全局类“EchoSignApiService”中访问，还引入了两个新元素：

• 全局函数：
  

  /**

  * 输入参数：

  * toBeChangedRecipientId：SIGN_Recipient__c Id

  * newRecipientStr：新收件人的 SIGN_Recipient__c 的 JSON 字符串，以供收件人替换或替代

  * 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 字符串

字符串 newRecipientStr = JSON.serialize(newRecipient);

尝试 {

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

} catch (Exception ex) {

    // 处理异常并根据需要重新引发

}

方法

内部类

• 全局类：DocumentHistoryEvent

• 全局类：DocumentInfo
  

• 全局类：ParticipantInfo

• 全局类：SendDocumentResult

• 全局类：SigningUrl
  

Apex 批处理服务

在批处理级别公开主要 e-Sign 协议操作，允许对一组协议执行一个操作。 这个类实现 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，将使用这个 ID 来加载协议。 URL 的这一部分是可选的。 如果省略，则加载标记为默认值的协议模板。 如果省略模板 ID，且不存在默认协议模板 ID，将会返回错误。

模板 ID 可以采用 15 或 18 个字符格式。

主 ID

masterId 参数指定应使用哪个主记录从特定协议模板加载协议。 该参数是可选的，但对于指定了主对象类型并在模板中引用该主对象的任何协议模板，都必须指定该参数。

主 ID 可以采用 15 或 18 字符格式。

运行时变量

任何其他参数均用作运行时变量，采用名称值对的形式，用于填充协议模板中指定的任何运行时变量。

结果

REST Web 服务返回 LoadResult 对象，该对象包含以下字段：

• agreementId：如果协议加载操作成功，该字段包含新创建的协议记录的 ID。
• error：如果协议加载期间出现任何错误，该字段将包含详细的错误消息。

后台服务

后台服务功能允许数据包使用者将后台操作 (echosign_dev1 Background_Actions c) 字段更新为相应的值，从而对协议对象调用各种操作。 该字段值从空白值或其他值更改为以下某个值时，将立即从属于 e-Sign 受管理包中的触发器触发操作。

• 提醒
• 发送
• 取消
• 删除
• 更新

所有操作都以异步 Future 模式执行，因此状态会存储在协议的“错误”字段中。

向后兼容性更改

更多此类内容

• 适用于 Salesforce 的 Adobe Acrobat Sign - 安装指南
• 适用于 Salesforce 的 Adobe Acrobat Sign - 高级自定义指南
• 适用于 Salesforce 的 Adobe Acrobat Sign - 字段映射和模板
• 适用于 Salesforce 的 Adobe Acrobat Sign - 升级指南
• 适用于 Salesforce 的 Adobe Acrobat Sign - 用户指南