Converting PDF Form checkboxes: why you need tab groups
Many DocuSign customers use the PDF transform feature for PDF Forms, because it transforms Form fields automatically while maintaining their values. When a form field is transformed to a DocuSign Tab object, however, not all of its functionality is preserved. For example, required checkboxes are converted to checkbox tabs that are not required.
To fully transform a PDF Form’s required checkbox to a required checkbox in your document, you need to use a compositeTemplates object with tab groups.
DocuSign uses tab groups to specify whether a checkbox is required or not. Tab groups also enable you to apply validation rules to multiple checkboxes, such as "Select at least," "Select at most," and so on. You can read more about the feature in the Checkbox Fields guide.
To take a typical use case, suppose you want to require at least one of the PDF Form’s checkboxes to be checked in the DocuSign envelope. The DocuSign PDF Transform feature creates Tab objects for the checkboxes, but the checkboxes are not grouped in tab groups.
To create the at least one checkbox rule, use a compositeTemplates object. It will add the tabGroups object to the envelope object and will also set the tabGroupLabels attribute of the checkboxTabs objects to the new tabGroups object. The tabGroups object is set to require at least one of the checkboxes to be checked.
You need to know the names of the form fields so that you can refer to them in the compositeTemplates object. The names are set in the checkbox properties in the PDF Form.
The PDF form in our example has three checkboxes with field names signer_room, signer_apartment, and signer_house.
This JSON fragment shows the end goal for the checkboxTabs and tabGroups objects. To achieve this goal, use the compositeTemplates object to update the checkbox objects and add a new tabGroups object to the envelope object.
"tabs": {
"checkboxTabs": [
{
"name":"Room",
"tabLabel": "signer_room",
"tabGroupLabels": [
"signer_chk_grp"
]
},
{
"name":"Apartment",
"tabLabel": "signer_apartment",
"tabGroupLabels": [
"signer_chk_grp"
]
},
{
"name":"House",
"tabLabel": "signer_house",
"tabGroupLabels": [
"signer_chk_grp"
]
}
],
"tabGroups": [
{
"groupLabel": "signer_chk_grp",
"minimumRequired": "1",
"groupRule": "SelectAtLeast",
"tabScope": "Document",
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"xPosition": "0",
"yPosition": "0",
"tabType": "tabgroup"
}
]
}
In the JSON above, tabLabel attributes are set to the checkbox name, and each checkbox tabGroupLabels attribute is set to the name of the newly added tab group, signer_chk_grp.
The tab group attributes are set: minimumRequired: "1" combined with groupRule: "SelectAtLeast" ensures that at least one of the three checkboxes is checked.
Note: If only one checkbox is set to a tabGroups property, it will translate to a single required checkbox.
The composite template shown below accomplishes your goals.
{
"status": "sent",
"enforceSignerVisibility": "true",
"emailSubject": "Simple checkbox",
"compositeTemplates": [
{
"compositeTemplateId": "1",
"document": {
"documentBase64": "converted to base64 pdf",
"documentId": "1",
"fileExtension": "pdf",
"name": "Simple checkbox form.pdf",
"order": "1",
"transformPdfFields": "true"
},
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"name": "{signer name}",
"email": "{user email}",
"recipientId": 1,
"tabs": {
"checkboxTabs": [
{
"name": "Room",
"tabLabel": "signer_room",
"tabGroupLabels": [
"signer_chk_grp"
]
},
{
"name": "Apartment",
"tabLabel": "signer_apartment",
"tabGroupLabels": [
"signer_chk_grp"
]
},
{
"name": "House",
"tabLabel": "signer_house",
"tabGroupLabels": [
"signer_chk_grp"
]
}
],
"tabGroups": [
{
"groupLabel": "signer_chk_grp",
"minimumRequired": "1",
"groupRule": "SelectAtLeast",
"tabScope": "Document",
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"xPosition": "0",
"yPosition": "0",
"tabType": "tabgroup"
}
],
"signHereTabs": [
{
"tabLabel": "signer\\*"
}
]
}
}
]
}
}
]
}
]
}
Summary
Together, the DocuSign PDF Transform and composite template features enable you to convert a PDF Form to a DocuSign envelope and choose any of many different requirement options for the checkboxes. Composite templates can add many other DocuSign features to PDF Form files, too.
