Use AutoPlace to dynamically place signing fields

Enable your app’s signing, data, and other types of fields to dynamically adjust their position on the page as the source documents change.

Getting ready

To use the example code you will need:

  • A DocuSign developer account email and password.
  • An integration key. See Generate Your Integrator Key.
  • The DocuSign client library for your software language.

Try it out!

The recipe source files include a full example that enables you to send an envelope that includes multiple AutoPlace fields which are positioned via anchor text. You can run the example, for free, on Heroku.

This recipe uses the same source files as the Sending Multiple documents recipe.

Run on Heroku

Run the recipe on Heroku

Deploy the recipe to Heroku. Enter your DocuSign Developer Sandbox credentials on the form in the Heroku dashboard. Then press the View button at the bottom of the dashboard screen when it is enabled by the dashboard.

For more information, see the Heroku section of the PAAS recipe.

How to do it

Step 1: use the login_information API end point to obtain the base url for use in subsequent API calls, and the user’s account ID. See the recipe Requesting a Signature via Email for an example of this step.

Step 2: Use the Envelopes:create method to create a new envelope. When you create the envelope, use AutoPlace by specifying field locations via the anchorString, anchorXOffset, anchorYOffset, and anchorUnits fields.

Source files

The recipe source files are available on Github: Python

Additional language versions of the recipe are in development and will be posted here in the future.

How it works

DocuSign’s AutoPlace feature enables a field to be positioned relative to other text within the envelope’s documents. AutoPlace solves the problem of variable-length documents, enabling your app to correctly place document fields, even when a document becomes longer or shorter.

Using AutoPlace enables your application to be less brittle. With AutoPlace, your application handles document changes automatically, resulting in less work for you.

AutoPlace can be used with a document’s existing text, or by adding specialized text anchors:

Existing text A benefit of using a document’s existing text as anchor is that no changes to the existing document are required. However, you will probably need to specifiy the X and Y offsets from the anchor text. As shown in the example, offsets can be positive or negative, depending on the layout of your document.

Adding new text If you have access to the source of the document, it is often best to explicitly add anchor text to the document. Your anchor text can be positioned in the document, minimizing the need to use offsets. You can also choose text to ensure that there will be no “false positives” when the DocuSign platform searches the document(s) for matching anchor text. To avoid unsightly anchor strings such as signer1sig, simply set the string’s color the same as the page’s background (white) and it won’t be shown.

Automatic Data Population

If the tabLabel for multiple document fields (of the same type) are set to the same value, then data entered in one of the fields will be replicated to the others. In this example, the tabLabel "Company" was used for a text field in the first document and two more in the last document. When the user enters a value in one of the text fields, it will be duplicated in the other two.

By default, the scope for automatic data population is per document. You can change the scope to the envelope level via the account’s preferences screen. See the “Data Population Scope” setting.

There’s more

If an AutoPlace field’s anchor settings cause it to match more than one location in the envelope’s documents, a field will be placed at each matching location. This enables you to define a field once, and it will be placed as needed, wherever you add the matching text.

To examine the multiple fields that a single AutoPlace field definition creates, set the optional query parameter include_anchor_tab_locations to true. It’s available for API methods that retrieve document field information. If the parameter is not included, only information on the first instance of the AutoPlace field will be provided.