全局
上次更新日期：
2022年9月29日
|
也应用至 Adobe Acrobat Sign
- Adobe Acrobat Sign 集成
- 新增功能
- 产品版本和生命周期
- Acrobat Sign for Salesforce
- Acrobat Sign for Microsoft
- Acrobat Sign for Microsoft 365
- 适用于 Outlook 的 Acrobat Sign
- 适用于 Word/PowerPoint 的 Acrobat Sign
- 适用于 Teams 的 Acrobat Sign
- 适用于 Microsoft PowerApps 和 Power Automate 的 Acrobat Sign
- 适用于 Microsoft Search 的 Acrobat Sign 连接器
- 适用于 Microsoft Dynamics 的 Acrobat Sign
- 适用于 Microsoft SharePoint 的 Acrobat Sign
- Acrobat Sign for Microsoft 365
- Acrobat Sign for ServiceNow
- 适用于 HR ServiceNow 的 Acrobat Sign
- 适用于 SAP SuccessFactors 的 Acrobat Sign
- 适用于 Workday 的 Acrobat Sign
- 适用于 NetSuite 的 Acrobat Sign
- 适用于 SugarCRM 的 Acrobat Sign
- 适用于 VeevaVault 的 Acrobat Sign
- 适用于 Coupa BSM Suite 的 Acrobat Sign
- Acrobat Sign 开发人员文档
概述
适用于 Salesforce 的 Adobe Acrobat Sign:开发者指南旨在帮助 Salesforce 开发者了解将 Salesforce 包与 Adobe Acrobat Sign 集成所需的对象和参数。
注意：
在未来的版本中，适用于 Salesforce 的 Adobe Acrobat Sign 对象可能会更改。如果构建依赖于已更改对象的自定义解决方案，则可能需要更新自定义设置。
集成指南
- 如果需要了解协议何时完全签署，请在更新后或更新之前（取决于用例和要求），在对 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 中，更新顺序已更改。以下是更新协议及其相关对象的序列：
- 附件
- 收件人
- 协议（状态及其他属性）
- 协议事件
- Chatter 订阅源
Apex 服务
正在使用的 Apex 方法
从适用于 Salesforce 的 Acrobat Sign V21.0 开始，所有异步进程（包括自动更新和数据映射）都已从未来方法切换到可排队方法，这是 Salesforce 推荐的方法。
进行此更改后，订阅者组织中在自动更新或数据映射过程中将作业添加到 Salesforce 队列的所有自定义设置都将失败，并显示错误“系统。LimitException：太多可排队作业添加到队列：2”。
出现此失败的原因是一个可排队进程只能添加一个子可排队作业，而这个作业已经被 Acrobat Sign 占用了。有关详细信息，请参阅可排队 Apex 限制。
错误：“当链接作业时，您只能使用“系统”从执行作业中添加一个作业。enqueueJob，这意味着每个父可排队作业只能存在一个子作业。不支持从同一个可排队作业启动多个子作业”。
当协议状态不变或数据映射未正确运行时，会出现上述错误。要解决此错误，请查找错误触发器、进程构建器或工作流程，然后将其停用或切换为使用同步调用，或安排在以后进行。
协议模板服务
协议模板服务通过受管理包作为一项全局 Apex 服务公开。这允许受管理包之外的 Apex 代码根据现有协议模板加载协议。类和所有公开的方法标记为全局以允许此类访问。
Apex 服务通过以下调用类公开：echosign_dev1.AgreementTemplateService
注意:
目前不支持使用 e-Sign 库模板加载协议模板。我们建议您将文档模板移至 Salesforce 文档库。
方法
|
|
static Id load() |
使用标记为默认且没有主对象类型的协议模板加载协议。 |
|
全局 |
static Id load(String templateId) |
使用没有主对象类型的指定协议模板 ID 加载协议。
|
|
全局 |
static Id load(String templateId, String masterId) |
使用指定协议模板 ID 和指定主记录 ID 加载协议，并且其类型必须与指定协议模板中配置的主对象类型相匹配。 |
|
全局 |
static Id load(String templateId, String masterId, Map<String,AgreementTemplateVariable> agreementTemplateVariables) |
使用指定协议模板 ID 和指定主记录 ID 加载协议，并且其类型必须与指定协议模板中配置的主对象类型相匹配。此外，还以名称值对形式传入指定运行时变量。
|
|
全局 |
static List<AgreementTemplateService.AgreementTemplateBasicInfo> getAgreementTemplateList(AgreementTemplateListOptions options) |
根据过滤选项获取协议模板的列表。如果使用过滤选项没有找到协议模板，则返回空列表。 |
|
全局 |
static AgreementTemplateService.AgreementTemplateDetails getAgreementTemplateDetails(String templateId) |
获取指定协议模板 ID 的协议模板详细信息。 如果未找到协议模板，则返回空对象。 |
|
全局 |
static String getAgreementTemplateUrl(String templateId) |
根据协议模板 ID 获取编辑协议模板的 URL。 |
|
全局 |
static String getNewAgreementTemplateUrl() |
获取在 Adobe Sign 中创建新协议模板的 URL。 |
构造函数 (1 个)
|
访问权限 |
签名 |
|---|---|
|
全局 |
AgreementTemplateListOptions() |
|
全局 |
AgreementTemplateListOptions(String masterObjectType, Boolean isActive, Boolean hasAttachment, Boolean hasRecipient, Boolean autoSend) |
global class AgreementTemplateService.AgreementTemplateListOptions
属性 (5)
|
访问权限 |
名称 |
|---|---|
|
全局 |
masterObjectType |
|
全局 |
isActive |
|
全局 |
hasAttachment |
|
全局 |
hasRecipient |
|
全局 |
autoSend |
注意:
在查询协议模板时，如果上面列出的字段为空值，则不对其对应的字段应用过滤器。
global class AgreementTemplateService.AgreementTemplateBasicInfo
属性 (6)
|
访问权限 |
名称 |
|---|---|
|
全局 |
name |
|
全局 |
recordId |
|
全局 |
url |
|
全局 |
isDefault |
|
全局 |
daysUntilExpiration |
|
全局 |
language |
global class AgreementTemplateService.AgreementTemplateDetails
属性 (6)
|
访问权限 |
名称 |
|---|---|
|
全局 |
message |
|
全局 |
ccList |
|
全局 |
dataMappingName |
|
全局 |
mergeMappingName |
|
全局 |
url |
|
全局 |
收件人 |
global class AgreementTemplateService.RecipientInfo
属性 (4)
|
访问权限 |
名称 |
|---|---|
|
全局 |
recipientRole |
|
全局 |
recipientType |
|
全局 |
recipientName |
|
全局 |
signOrder |
运行时变量
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
方法
全局 |
static void cancelDocument(Id agreementId) |
取消具有指定协议 ID 的协议。 |
全局 |
static void delegateSigner(Id agreementId, String delegatedEmail) |
将签名委派给提供的电子邮件。 |
全局 |
static void delegateSigner(Id agreementId, String delegatedEmail, String message) |
将签名委派给具有指定消息的所提供电子邮件。 |
全局 |
static echosign_dev1.EchoSignApiService.DocumentInfo getDocumentInfo(Id agreementId) |
检索指定协议 ID 的详细信息。 |
全局 |
static List<EchoSignApiService.SigningUrl> getSigningUrls(Id agreementId) |
检索指定协议 ID 的所有签名 URL。 |
全局 |
static void removeDocument(Id agreementId) |
取消具有指定协议 ID 的协议，并在 Salesforce 中删除该协议（该协议不会从 Adobe e-Sign 帐户中删除）。 |
全局 |
static void replaceSigner(Id replacementRecipientId) |
替换指定的签名者。 |
全局 |
static void replaceSigner(Id replacementRecipientId, String message) |
替换具有指定消息的指定签名者。 |
全局 |
static echosign_dev1.EchoSignApiService. SendDocumentResult sendDocument(Id agreementId) |
发出具有指定协议 ID 的协议，并返回包含文档键和 URL 的结果。 |
全局 |
static void sendReminder(Id agreementId) |
向指定协议 ID 的当前签名者发送提醒。 |
| 全局 | static void updateAgreement(Id agreementId) | 更新具有指定协议 ID 的协议 |
| 全局 | static EchoSignApiService.AgreementViewUrl getViewAgreementUrl(Id agreementId) |
从 Sign 中检索具有 viewURL 属性的指定协议 ID 的查看/管理页面。 注意：出于安全原因，生成的协议 URL 只有一个临时的生命周期，因此它会生成 REST-HTTPS 调用，以便从 Adobe Sign 服务获取一个全新的 URL。 |
内部类
global class DocumentHistoryEvent
属性 (2 个)
|
访问权限 |
名称 |
|---|---|
|
全局 |
String eventType |
|
全局 |
String participantEmail |
构造函数 (1 个)
|
访问权限 |
签名 |
|---|---|
|
全局 |
DocumentHistoryEvent() |
global class DocumentInfo
属性 (5 个)
|
访问权限 |
名称 |
|---|---|
|
全局 |
Map<string,list> historyByEmail |
|
全局 |
Map participantsByEmail |
|
全局 |
Map participantsByName |
|
全局 |
String senderEmail |
|
全局 |
String status |
构造函数 (1 个)
|
访问权限 |
签名 |
|---|---|
|
全局 |
DocumentInfo() |
global class ParticipantInfo
属性 (5 个)
|
访问权限 |
名称 |
|---|---|
|
全局 |
String company |
|
全局 |
String email |
|
全局 |
String name |
|
全局 |
String status |
|
全局 |
String title |
构造函数 (1 个)
|
访问权限 |
签名 |
|---|---|
|
全局 |
ParticipantInfo() |
global class SendDocumentResult
属性 (3 个)
|
访问权限 |
名称 |
|---|---|
|
全局 |
String documentKey |
|
全局 |
Exception error |
|
全局 |
String url |
构造函数 (1 个)
|
访问权限 |
签名 |
|---|---|
|
全局 |
SendDocumentResult() |
global class SigningUrl
属性 (3 个)
|
访问权限 |
名称 |
|---|---|
|
全局 |
String email |
|
全局 |
String esignUrl |
|
全局 |
String simpleEsignUrl |
构造函数 (1 个)
|
访问权限 |
签名 |
|---|---|
|
全球 |
|
Apex 批处理服务
在批处理级别公开主要 e-Sign 协议操作，允许对一组协议执行一个操作。这个类实现 Salesforce Database.Batchable 接口。它能处理任意数量的记录，这些记录会以 5 条一组进行分组，每一组作为一个事务进行处理，从而满足监管者限制要求。
Apex 批处理服务通过以下调用类公开：echosign_dev1.EchoSignActionBatch
参数
必须指定以下参数来初始化批处理操作。
一个协议记录 ID 列表，将对列表中的记录执行提供的操作。要执行的操作，支持的值如下：
- 提醒
- 发送
- 取消
- 删除
- 更新
当前用户会话 ID。只有更新类型的操作需要此 ID。
提交者用户记录，用于在批处理完成时通过电子邮件通知该用户。
用法示例
User submitterUser = UserInfo.getUserId();
EchoSignActionBatch batch = new EchoSignActionBatch( agreementIds, 'Remind', UserInfo.getSessionId(), submitterUser); 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); 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');
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
注意:
- 实例名称会有所不同，具体视您的组织实例而定。
- https://_<instance_name>_.salesforce.com/services/apexrest/echosign_dev1/template/load/<template_id> 是程序包 20.0 或更高版本的 POST HTTP 方法。
- V20 之前的版本使用 GET 方法。
模板 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 模式执行，因此状态会存储在协议的“错误”字段中。
向后兼容性更改
- 现在，文档和收件人更新之后，协议状态也会更新
- 在版本 21 之前，状态是在先前设置的。
- 现在根本无法插入已签名协议对象（用于存储图像 URL）
- 在版本 21 之前，在完成所有其他更新后可以插入已签名协议对象
- 根据 Salesforce 调节器限制，异步 Apex 呼出请求或响应的最大大小限制为 12 MB：https://developer.salesforce.com/docs/atlas.en-us.210.0.apexcode.meta/apexcode/apex_gov_limits.htm
- 由于上述限制，无法从 Sign 中获取大于 12 MB 的文档。
- 协议事件描述已更改。现在，它与 Sign API 返回的描述和审核报告相匹配。
- 现在，更新进程在 Salesforce 中作为本机 Apex 批处理进程（异步进程）运行
- 之前，更新进程是在 Salesforce 外部使用 API 调用进行的更新
- 触发这些启动异步进程的状态更新不再起作用，因为 Salesforce 限制从已经运行的异步进程调用另一个异步进程
- 在版本 21 之前，协议属性更新被拆分为单独的更新调用，现在协议对象在一个事务中即可全部更新。
- 在版本 21 之前，失败的协议只能通过在 Salesforce 中进行手动更新来重试
- 现在，更新更加可靠，因为 Sign 后端会自动重试失败事件指定的次数。
- 现在，手动更新会更新协议的所有方面，包括相关对象。
- 与常规更新一样，现在推送协议会以异步模式运行，并且也会更新其他属性。
- 引入了新设置，以启用/禁用协议不同方面的更新。
- 当已签名 PDF 存储在 Salesforce 中时，PDF 文件名的末尾将不再附加描述符（-signed 或 -approved）。
