From the Trenches: PDF form field transformation
A powerful feature of the DocuSign Agreement Platform is our ability to transform PDF form fields into DocuSign eSignature tabs on an envelope automatically. PDF form field transformation enables you to transform PDF form fields automatically into DocuSign tabs, carrying over all of their existing values. The locations of the created tabs will match the locations of the fields from which they were generated.
There are three common ways to use this feature:
- In the eSignature web application, when you upload a PDF document that contains form fields, you will be asked if you want to transform these fields, and then asked to which recipient they should be assigned. All fields are assigned to one recipient.
- Similarly, using the eSignature REST API, you can add two attributes to your
documentobject that will transform the PDF fields and assign them to a recipient. - For more control, you can use the DocuSign composite template model, which allows you to assign transformed fields to specific recipients, write values in the fields, and set additional properties on the fields.
Transforming PDF fields in the web application is detailed in our Support article Send a PDF with Form Fields. In this post, we will describe how to use PDF form field transformation in the API.
For simple use cases where you want to assign all the transformed PDF fields to a single recipient, you can set two properties on your document object in your REST API call:
"transformPdfFields": true,
"assignTabsToRecipientId": "1"
When you set these two properties, the PDF fields are converted to DocuSign tabs on the envelope and assigned to the recipient with the ID specified. If you have fields defined as checkboxes or signatures or other types recognized by DocuSign, they will automatically convert into checkboxes or signature tabs in DocuSign. This type of transformation happens regardless of the names of the fields. DocuSign will also transform simple text fields into DocuSign tabs of specific types through a naming convention. If you name your text field eSignSignHere or DocuSignSignHere, the text field will transform to a DocuSign SignHere tab. DocuSign will not transform PDF form fields that have the text DocuSignIgnoreTransform or eSignIgnoreTransform as part of the name of the PDF form field. You can see all the supported tab types and sample code on the Developer Center at PDF form field transformation.
When developing applications with more complex use cases, you may need to transform PDF fields and then assign them to different recipients. This allows for setting values or adding additional properties on the resulting tabs such as scale, required, or locked. These more complex use cases require a composite template. Keep in mind the following rules:
- Use one document per composite template. If you have multiple documents, add more composite templates to the array.
- Use the exact name of the fields in the source PDF as the
tabLabelin the API call. - Using this model, fields that you do not explicitly specify are not transformed. They are rendered in a fixed state unless you use the
defaultRecipientparameter. - When defining most transformed tabs, only the
tabLabelis required. Radio buttons present a special case: you must define the values of each button.
In the following example, we want to assign the PDF fields Customer_Name, Customer_eSignSignHere and the radio group Customer_eSignRadio to the Customer, recipient 1. The fields are transformed to a Text tab, a SignHere tab and a RadioGroup. They retain all the original properties we do not explicitly set. We will assign a Seller_Name text tab to the Seller, recipient 2. We want to allow the recipient to edit the name we provide, so we're setting the locked property to false. Setting this true would prevent the signer from changing the value. For the radio button defined, we match the groupName to the name of the Group Name of the Radio Button properties. We also have to add values for the individual radio buttons.
Making the API call
Here’s the JSON body for the createEnvelope call using a composite template:
{
"compositeTemplates": [
{
"compositeTemplateId": "1",
"document": {
"documentBase64": "JVBERi0...VPRgo=",
"transformPdfFields": "true",
"documentId": "1",
"fileExtension": "pdf",
"name": "Example Agreement"
},
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"email": "customer@gmail.com",
"name": "Zack Customer",
"recipientId": "1",
"routingOrder": "1",
"defaultRecipient": "true",
"tabs": {
"textTabs": [
{
"tabLabel": "Customer_Name",
"value": "Zack Customer",
"locked": "false"
}
],
"signHereTabs": [
{
"optional": "false",
"scaleValue": "1",
"tabLabel": "Customer_eSignSignHere"
}
],
"radioGroupTabs": [
{
"groupName": "Customer_eSignRadio",
"recipientId": "1",
"radios": [
{
"value": "Yes"
},
{
"value": "No"
}
]
}
]
}
},
{
"email": "seller@gmail.com",
"name": "Zack Seller",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"textTabs": [
{
"tabLabel": "Seller_Name",
"value": "Zack Seller",
"locked": "false"
}
]
}
}
]
},
"sequence": "1"
}
]
}
],
"emailSubject": "Testing Transform PDF Fields",
"status": "sent"
}
In the above example we explicitly assigned every tab. Another approach you could use is to use the defaultRecipient parameter to assign any tabs which are not specified in your call to a default recipient. None will be rendered into the document in a fixed state. You would assign tabs to other recipients just as we did above.
PDF Form field transformation can save time by defining tabs in DocuSign, leveraging the data in your PDF. When needed, using composite templates gives you control over assigning tabs to different recipients and setting values at runtime.
