如何取消使用锚标记放置的复选框

Question

我们在文档中使用 AnchorTags 将签名元素放入 PDF 文档中。到目前为止，像“SignHere”这样的签名元素按预期工作，每个签名单击一次，并正确放入文档中。我们现在正尝试使用 AnchorTags 向这些文档添加复选框，但我们遇到了一些问题，即复选框 1. 标记和 2. 分组的方式。

根据 DocuSign 文档：

对于每组放置的字段，该组中所有字段的数据标签都相同。这对于收件人填写的字段类型很重要，例如文本字段。如果您保持数据标签不变，则当收件人填写组中的任何一个字段时，所有其他类似字段都会自动填充相同的数据。

查看使用 API 创建复选框，我们可以使用这样的 JSON 对象在文档中为复选框标签分配字符串值。这将找到字符串 BOR_2_CHK 并在每个实例上放置一个复选框。

PUT /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs

{
"checkboxTabs": [
    {
        "name": "",
        "tabLabel": "Checkbox1",
        "selected": "false",
        "shared": "false",
        "required": "false",
        "locked": "false",
        "documentId": "46688109",
        "recipientId": "50556292",
        "anchorString": "BOR_2_CHK",
        "anchorXOffset": "0",
        "anchorYOffset": "0",
        "anchorUnits": "pixels",
        "anchorCaseSensitive": "false",
        "anchorMatchWholeWord": "true",
        "anchorHorizontalAlignment": "left",
        "tabId": ""
    }]}

此调用对具有多个匹配 AnchorString 的文档的影响是，将在每个匹配位置放置一个复选框，当任何一个复选框被选中时，它们都被选中。通过将“AutoPlace”规则分配给复选框的文档，这很容易在 DocuSign 网站中重现。

这就是事情变得奇怪的地方，当一个使用 AnchorTags 放置复选框的文档，并且文档中有不止一次的 AnchorString 实例时，签名仪式将显示多个复选框，但 API 只报告有文档上的单个复选框选项卡。

在以下 JSON 示例中，文档中有 2 个锚字符串的 3 个实例，因此文档中总共有 6 个复选框。

{
"checkboxTabs": [
    {
        "name": "",
        "tabLabel": "Checkbox 0daa7d08-db75-43da-bcee-01a6451a34a5",
        "selected": "false",
        "shared": "false",
        "required": "false",
        "locked": "false",
        "documentId": "46688109",
        "recipientId": "50556292",
        "pageNumber": "1",
        "xPosition": "74",
        "yPosition": "253",
        "anchorString": "BOR_2_CHK",
        "anchorXOffset": "0",
        "anchorYOffset": "0",
        "anchorUnits": "pixels",
        "anchorCaseSensitive": "false",
        "anchorMatchWholeWord": "true",
        "anchorHorizontalAlignment": "left",
        "tabId": "d87fb774-2b4b-4c86-95b3-e5a730066874"
    },
    {
        "name": "",
        "tabLabel": "BOR_1_CHK",
        "selected": "false",
        "shared": "false",
        "required": "false",
        "locked": "false",
        "documentId": "46688109",
        "recipientId": "50556292",
        "pageNumber": "1",
        "xPosition": "74",
        "yPosition": "73",
        "anchorString": "BOR_1_CHK",
        "anchorXOffset": "0",
        "anchorYOffset": "0",
        "anchorUnits": "pixels",
        "anchorCaseSensitive": "false",
        "anchorMatchWholeWord": "true",
        "anchorHorizontalAlignment": "left",
        "tabId": "966c4273-d4a4-4acd-8ff5-08b27ba69c13"
    }
  ]
}

我的问题是，如何使用 DocuSign REST API 取消组合并让文档上的所有 6 个复选框独立工作？

DocuSign 网站有一个可用作 AutoPlace 一部分的按钮，称为“Ungroup”，当在 UI 中单击此按钮时，API 会显示分配给 AnchorString 的每个复选框的复选框选项卡，但是“ancorString”属性具有全部从未分组的对象中剥离。我已经搜索了 DocuSign API 文档以及 StackOverflow，但没有找到任何可用于完成此操作的“Ungroup”方法或属性。

我发现取消组合复选框的唯一方法是使用 EnvelopeTabs:Update 方法将对象的 anchorTag 属性设置为 null。这种方法是有限的，因为当我查询信封上的选项卡列表时，每个组复选框选项卡仅显示为单个对象，因此要取消组合 3 个复选框，我必须执行 3 次更新，并且 2 作为第 2 和第 3 的 tabID cheboxes 仅在其前身已更改后才可用。

通常我们的文档最多可以有 6 个签名者，每个签名者在文档中有 40 个或更多复选框元素，即单个信封有 240 个 GET/PUT 请求，并且在 4 个信封后会达到 DocuSign 速率限制。

提前感谢您的帮助，

Answer 1

根据 Larry K 提供的信息，我能够推导出一种方法来“取消分组”使用 AnchorString 分配的选项卡。

第 1 步 - 使用“includeAnchorTabLocations”选项集获取信封信息。

            //Get envelope information
        EnvelopesApi envelopesApi = new EnvelopesApi();
        EnvelopesApi.ListTabsOptions options = new EnvelopesApi.ListTabsOptions();
        options.includeAnchorTabLocations = "True";
        Envelope envInfo = envelopesApi.GetEnvelope(accountId, envelopeID);

            //Get recipients on envelope
        Recipients recips = envelopesApi.ListRecipients(accountId, envelopeID);
        RecipientsUpdateSummary updateSummary = new RecipientsUpdateSummary();
            //List documents in envelope
        EnvelopeDocumentsResult docsList = envelopesApi.ListDocuments(accountId, envelopeID);

Step2 - 对于信封中的每个收件人，更新选项卡并删除 AnchorString。在我们的例子中，我们还希望每个选项卡都有独立的数据，因此 TabLabel 也被更新为唯一值。

            //Remove AnchorString from tabs in documents
        foreach (Signer recip in recips.Signers)
        {
            Tabs tabs = envelopesApi.ListTabs(accountId, envInfo.EnvelopeId, recip.RecipientId, options);

            if (tabs.CheckboxTabs != null)
            {
                foreach ( Checkbox tab in recip.Tabs.CheckboxTabs)
                {
                    // Ungroup checkbox tabs by removing the AnchorString                      
                    tab.AnchorString = "";
                    tab.TabLabel = Guid.NewGuid().ToString();
                }
            }

            envelopesApi.UpdateTabs(accountId, envInfo.EnvelopeId, recip.RecipientId, tabs);
        }

最后说明

由于使用了锚标签，因此信封最初应以“草稿”状态提交给 DocuSign，这允许 DocuSign 处理文档中的 AnchorStrings。处理后，每个 Tab 将具有 X、Y 坐标，从而允许删除 AnchorString，同时仍保持文档中每个 TAB 的原始位置。完成更新选项卡后，将信封信息更新为“已发送”状态并触发信封API 更新方法以提交更改。

        envInfo.PurgeState = null;
        envInfo.Status = "sent";
        envelopesApi.Update(accountId, envelopeID, envInfo, null);

Answer 2

您可以使用EnvelopeRecipientTabs: list 方法获取收件人的所有字段（标签）的列表，并将查询参数include_anchor_tab_locations 设置为true：

当设置为 true 时，所有具有锚标签属性的标签都包含在响应中。

很遗憾，我不知道您关于如何复制网络工具的“取消组合”命令效果的具体问题的答案。

更新

查看此answer 以了解类似于Docusign web tool's“取消组合”命令的取消分组选项卡。