Skip to main content
Blog
Home/

Converting PDF Form checkboxes: why you need tab groups

Author Ivan Dinkov
Ivan DinkovSr. Developer Support Advisory Engineer
Summary3 min read

This feature of composite templates lets you use the eSignature REST API to set properties on checkboxes imported from PDF Forms.

    • Summary
    • Additional resources

    Table of contents

    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.

    Checkbox properties on the PDF Form

    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.

    Additional resources

    Author Ivan Dinkov
    Ivan DinkovSr. Developer Support Advisory Engineer
    More posts from this author

    Related posts

    • Event Notifications using JSON SIM and HMAC
      Developers

      Event Notifications using JSON SIM and HMAC

      Author Jonathan Sammons
      Jonathan Sammons
    • Fast-Track Your Extension Apps with Reference Implementations

      Fast-Track Your Extension Apps with Reference Implementations

      Author Karissa Jacobsen
      Karissa Jacobsen
    • Trending Topics: Latest from our forums (October 2024)
      Author Paige Rossi
      Paige Rossi
    Event Notifications using JSON SIM and HMAC

    Event Notifications using JSON SIM and HMAC

    Author Jonathan Sammons
    Jonathan Sammons
    Fast-Track Your Extension Apps with Reference Implementations

    Fast-Track Your Extension Apps with Reference Implementations

    Author Karissa Jacobsen
    Karissa Jacobsen
    Trending Topics: Latest from our forums (October 2024)
    Author Paige Rossi
    Paige Rossi

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting