Tagging Dynamic Documents

Tagging Dynamic Documents

Some types of documents may not be suitable for working with in a graphical "template builder", particularly:

  • Dynamic documents that are generated programmatically in back-end systems, where the fields needed, and their locations, may change based on business logic, or
  • One-off documents that are generated and used only for a single signing operation, where a manual process for placing and defining fields is not wanted.

In these cases, developers may embed "tags" in both Word (DOCX) and PDF files to identify where signing fields should be placed and managed by Verdocs. Tags are defined using a Handlebars-style format as follows:

{{fieldtype:"RoleName";option1;option2...}}

For a complete example of a range of field types and options, click here to download a sample DOCX file with a variety of options in use.

Field Types

The following field types are supported:

  • attachment - A file attachment, to be uploaded by the user
  • checkbox - A single check-box that may be selected or deselected. Check boxes may be "grouped", and will appear in output metadata as an array of the values that were selected.
  • date - A date. When clicked, a date picker will be presented to the user
  • dropdown - A drop-down box
  • initial - An initial-here field
  • radio - A radio button. Radio buttons act like check boxes, but only one option in a group may be selected at a time.
  • signature - A sign-here field
  • textarea - A multi-line text box
  • textbox - A single-line text box
  • timestamp - A date/time stamp that will be automatically filled in when the user submits the document

Roles

All fields must be assigned to a "role". Roles are defined by you (the user or developer) and are usually generic names such as "Buyer," "Leasing Agent," or even as simple as "Recipient 1".

Role names can be anything you want, but keep the following rules in mind:

  • Role names must be between 3 and 30 characters long.
  • Simpler names are better. Role names become the IDs used later in metadata to identify the values used fill in for a document's fields. It may be easier to write code to look for "submittedData['OfficeMgr'][...]" than "submittedData['Assistant to the President\'s Office'][...]".
  • Role names are case-sensitive and must be unique. Be sure to be consistent and avoid confusion with terms such as using "officemgr" in one field and "OfficeMgr" in another.

Field Options

All fields share a common set of options. Options are separated by semicolons. Where options require parameters, they are delimited with colons. For example:

opt;w:150

indicates a field that is required (r) and has a width of 150.

Most options may be specified inline, with no additional delimiters. However, where special characters such as spaces or punctuation are included, they may be enclosed in double-quotes.

NOTE: When producing templates in Word/DOCX format, be sure to disable "Smart Quotes" for these markers!

p:"Enter your full name";w:150

The following options are available for most fields:

  • opt - By default, fields are required. If this flag is included, the field will be optional.
  • w - Set the width of the field (note: PDFs are typically 72dpi so a field with a width of 150 is typically ~2" in effective print width)
  • h - Set the height of the field.
  • n - Set the name of the field. If a name is not supplied, a system-generated name will be created and user-submitted data will still be available in the submittedData collection once signing is complete. For signature, initial, and timestamp fields, most apps rarely access the submitted data anyway and a name is not generally useful. However, it is generally recommended to include names for user input fields such as dates, textboxes and textareas.
  • p - Set the "placeholder" for the field. This text will be displayed until the user enters a value in the field as a hint for what they are expected to enter (e.g. "Enter your full name").
  • d - Set the "default" value for the field.

Note that some fields have exceptions, specifically:

  • Signature and initial fields have fixed widths and heights, and w/h options will be ignored.
  • group  applies only to checkboxes and radio buttons, and will be ignored for other fields.
  • options  applies only to dropdowns.
  • value applies only to radio buttons.
  • p  applies only to textbox and textarea fields.
  • d applies only to textbox, textarea, checkbox, dropdown, and radio fields.

Placing fields

Tags should generally be written in-line, in the places where signature fields belong in the final document. Most fields are small, and generally line up well with "typical" document formats and styles. When tags are detected, a signature field will be placed in each tag's location, and the tags will be redacted from the source document.

‍

Be sure to leave enough space for large fields, such as textareas.

A common confusion when working with source documents is that most editors (e.g. Microsoft Word) work from the top down (0,0 is the top-left corner of a page). Final page layouts are not determined until a document is printed, or converted to a print-compatible format such as PDF. In contrast, for historical reasons, PDF documents are laid out from the bottom up (0,0 is the bottom-left corner of a page). Therefore, when adding white-space around tags to leave room for them in a final document, be sure to place the tag in the bottom of the empty space, as shown with this textarea field for the Buyer's Address:

Alternative Definition Method

Defining fields inline using the above tags is the fastest and most streamlined option, but fields with many options may interfere with creating an elegant template in Word or other editors. In this case, you may use a simplified tag definition, referring to the tag by its unique ID, e.g.

{{Buyer-Address}}

or even:

{{F1}}

When using this syntax, you must follow a few additional rules:

  • Field names must be unique
  • Field names must be between 2-30 characters, begin with a letter, and consist only of alphanumeric characters, dashes, and spaces. NOTE: While spaces are supported, they are not recommended. Some API calls that include role names as a parameter will require URL-encoding these, e.g. a field named "Buyer Address" would need to be referred to as "Buyer%20Address").

When fields are specified in this way, you must include an additional fields definition array in API calls to create templates and envelopes using these documents, to provide the types and other options to assign to these fields.