How to ungroup checkboxes placed with AnchorTag

问题:

We are using AnchorTags in our documents to place signature elements into PDF documents. So far, signature elements like "SignHere" are working as expected, one click per signature, and being placed correctly into to the documents. We are now attempting to add checkboxes to these documents with AnchorTags and we are running in to some issues with how the checkboxes are 1. labeled and 2. grouped.

According to the DocuSign documentation:

For each group of placed fields, the data label is the same for all fields in the group. This is important for field types which the recipient fills out, such as text fields. If you leave the data labels the same, when the recipient completes any one of the fields in the group, all the other like fields are automatically populated with the same data.

Looking at creating checkboxes with the API, we can use a JSON object like this to assign string values in the document the checkbox tag. This will find the string BOR_2_CHK and place a checkbox at every instance.

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": ""
    }]}

This effect of this call on a document that has more than one matching AnchorString is that a checkbox will be placed at every matching location, when any of the checkboxes are checked, they are all checked. This is easily reproducible in the DocuSign web site by assigning an "AutoPlace" rule to the document for checkboxes.

This is where things get wierd, when a document that uses AnchorTags to place checkboxes, and there is more than once instance of the AnchorString in the document, the signing ceremony will display multiple checkboxes, but the API only reports that there is a single checkbox tab on the document.

In the following JSON example, there were 3 instances of 2 anchor strings in the document, so that is 6 checkboxes total in the document.

{
"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"
    }
  ]
}

My question is, how using the DocuSign REST API can I ungroup and make work independently all 6 checkboxes on the document?

The DocuSign website has a button available as part of AutoPlace called "Ungroup", when this is clicked in the UI, the API then shows checkbox tabs for each checkbox that was assigned to the AnchorString, however the "ancorString" attributes have all been stripped from the objects that were ungrouped. I have searched the DocuSign API documentation as well as StackOverflow and have not found any "Ungroup" method or attribute that I can use to accomplish this.

The only way I have found to ungroup the checkboxes is to remove the anchorTag attributes to the object using the EnvelopeTabs:Update method to set them to null. This approach is limited since when I query a list of tabs on the envelope, each group checkbox tabs is only shown as a single object therefore to ungroup 3 checkboxes, I must execute 3 updates, and 2 gets as the tabID for the 2nd and 3rd cheboxes are only available after its predecessor has been altered.

Commonly our documents can have upward of 6 signers, each having 40 or more checkbox elements in a document, that is 240 GET/PUT requests for a single envelope, and would hit the DocuSign rate limit after 4 envelopes.

Thanks in advance for your help,

回答1:

Based on the information provided by Larry K, I was able to derive a method for "ungrouping" tabs that were assigned using an AnchorString.

Step 1 - Get the envelope information with the "includeAnchorTabLocations" option set.

            //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 - For each recipient in the envelope update the tabs and remove the AnchorString. In our case, we also wanted each tab to have independent data, so the TabLabel was updated to a unique value as well.

            //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);
        }

Final Note

Since anchor tags are being used, the envelope should be submitted to DocuSign in a "Draft" status initially, this allows DocuSign to process the AnchorStrings in the document. Once processed each Tab will have an X,Y coordinate, allowing the AnchorString to be removed while still maintaining the original location of each TAB in the document. Once done updating tabs, update the envelope info to a status of "sent" and fire the envelopeAPI update method to commit the change.

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

回答2:

You can get a list of all of the fields (tags) for a recipient by using the EnvelopeRecipientTabs: list method, with the query parameter include_anchor_tab_locations set to true:

When set to true, all tabs with anchor tab properties are included in the response.

Unfortunately I don't know an answer to your specific question of how to duplicate the effect of the web tool's "ungroup" command.

Update

See this answer for ungrouping tabs similar to the Docusign web tool's "ungroup" command.