Dynamic MS Word eSigning Templates

Overview

Circularo supports dynamic MS Word eSigning templates using the JSON notation embedded in standard MS Word shapes tools.

The advantage of this approach is that there are many options for how your Circularo signature and other fields should look like and behave as you can change the style, size, color, shape, alignment, and many other standard shape object properties in MS Word.

Most importantly - by using MS Word shape alignment options you can define signature placeholders that will be positioned relative to the content of the document and will be automatically adjusted as you edit the paragraphs and content itself.

All such templates once ready can be uploaded to Circularo Template Library and reused when needed. Every time you use such a template all the fields definitions and even signatories will be automatically recognized and used as part of your Circularo signing process.

Circularo users with valid MS Office 365 online subscriptions can also easily edit newly created documents based on such templates online.

Basics

MS Word Shapes

For the best results, we do recommend using the standard “Rectangular“ shape for defining the placeholders and to set the alignment properties correctly.

It’s a good practice to have the proper size of your shapes ready (depending on the type of signature field, the size of fonts in your documents, etc.)

Always try to add or delete the text in the template you are working on to see if your alignment options are set properly. Once ready simply copy & paste the same shape again.

Basic JSON guidelines

All the rectangles defined in the word document must have the following text signature_field_start:{json}:signature_field_end to be recognized by our signing component in CIRCULARO.

By embedding the text signature_field_start:{json}:signature_field_end in the rectangles, you would be able to transform a simple word document to a document that can be sent for signatures with the sign fields and information fields.

You are able to define how many users need to sign the document and assign roles to the users.

The prepared word documents can be reused and can be sent to any number of internal and external users.

• JSON data is written as name/value pairs.

• A name/value pair consists of a field name (in double quotes), followed by a colon, followed by a value.

• You would be able to define different attributes such as type, style, size, color, alignment using JSON for both the signature fields and for the other information fields.

Let us see a basic JSON example:

signature_field_start:{"type":"signature","id":"signer-1","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

All the content included between the curly braces is JSON. The attributes which we have defined below are the “type“, ”id”, “userRoleId“ & “userRoleName“.

"type":"signature","id":"signer-1","userRoleId":1,"userRoleName":"signer-1"

Let’s see the different attributes used in the example above:

• type - (string) Type of sign field. It can be any of the options [signature, initials, stamp, wacom, annotation, image]

• id - (string) Identifier of sign field (doesn’t have to be unique). If ID is provided, then it’s used, otherwise random unique ID is generated. It can be used only using workflow.

• userRoleId - (integer) Identifier of the signer, used only in sign templates and signature extraction for the first assignment to "real" users or shares.

• userRoleName - (string) Only serves as the display name for userRoleId

How to prepare the document?

1. Place rectangles on the desired positions in the document.

2. Add text to the rectangles. Depending on the field the text inside the rectangles will change.

3. To make the text invisible for the end-user, the text can be small and even in the same color as the rectangle.

4. The prepared word document

5. When the word document is uploaded in CIRCULARO, it will automatically detect the number of signers and redirect to the user selection screen.

6. After the users are selected, you will be able to preview the sign fields and the information fields which have been placed on the document for the respective users.

7. The document is ready to be sent for signatures.

If the user's email address is specified in the JSON, the user will be automatically detected. For the users to be detected they need to be internal system users[needs to be verified].

signature_field_start:{"type":"signature","user":"adam.smith@circularo.com","id":"signer-1","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

In the above example, we are predefining the signer-1 of the document as adam.smith@circularo.com by setting the “user“ attribute.

Required attributes

Certain attributes need to be specified when defining the JSON for sign and information fields. If the required attributes are not defined all such rectangles will be ignored and will not be detected by CIRCULARO as a signature field.

For the Sign fields (signature, initials, stamp, Wacom) the below attributes are required:

• position (automatically filled)

• type

• page (automatically filled)

• userRoleId or user or both

• userRoleName (recommended otherwise will be automatically generated)

For the Information fields the below attributes are required:

• position (automatically filled)

• type

• page (automatically filled)

• userRoleId or user or both

• userRoleName (recommended otherwise will be automatically generated)

Sign fields JSON

Signature

• To define the signature field, the “type” attribute needs to be set to “signature“.

  signature_field_start:{"type":"signature","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

• To predefine the signature for a certain user, set the “user“ attribute to the email address of the user.

  signature_field_start:{"type":"signature","user":"adam.smith@circularo.com","id":"signer-1","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

• To define signature with a timestamp, set the “timestamp“ attribute to true. By default, the value is set to false.

  signature_field_start:{ "type": "signature","userRoleId": 1,"userRoleName": "signer-1","timestamp": "true"}:signature_field_end

• To define the signature field as required, set the “required“ attribute to true.

  signature_field_start:{"type": "signature","userRoleId": 1,"userRoleName": "signer-1","timestamp": "true","required": "true"}:signature_field_end

Initials

• To define the initials field, the “type” attribute needs to be set to “initials“.

  signature_field_start:{"type":"initials","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

• To predefine initials for a certain user, set the “user“ attribute to the email address of the user.

  signature_field_start:{"type":"initials","user":"adam.smith@circularo.com","id":"signer-1","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

Stamp

• To define the Stamp field, the “type” attribute needs to be set to “stamp“.

  signature_field_start:{"type":"stamp","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

• To predefine the Stamp for a certain user, set the “user“ attribute to the email address of the user.

  signature_field_start:{"type":"stamp","user":"adam.smith@circularo.com","id":"signer-1","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

WACOM

• To define the WACOM sign field, the “type” attribute needs to be set to “wacom“.

  signature_field_start:{"type":"wacom","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

• To predefine the WACOM sign for a certain user, set the “user“ attribute to the email address of the user.

  signature_field_start:{"type":"wacom","user":"adam.smith@circularo.com","id":"signer-1","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

Information fields JSON

For all the information fields it is necessary to define the attribute "type": "annotation" and the attribute "subtype" will vary depending on the field. For defining company field attribute subtype should be defined as "subtype": "annotation_company"

Text

signature_field_start:{"type":"annotation","subtype":"annotation_generic","userRoleId":1,"userRoleName":"signer-1","align":"left","fontSize":12}:signature_field_end

signature_field_start:{"type":"annotation","subtype":"annotation_generic","userRoleId":1,"userRoleName":"signer-1","align":"left","fontSize":14,"text":"Pre filled text for user.\nNew line\nAnother pre filled text"}:signature_field_end

Number

signature_field_start:{"type":"annotation","subtype":"annotation_generic","userRoleId":1,"userRoleName":"signer-1","config":"{\"maskSubtype\":\"mask_number\",\"placeholder\":\"Number\",\"mask\":{\"decimal\":false,\"groupSeparated\":false,\"groupSeparator\":\" \",\"groupLength\":3,\"radixPoint\":\",\"},\"unwrappedText\":\"\",\"group\":false}","align":"left","fontSize":12}:signature_field_end

Decimal Number

signature_field_start:{"type":"annotation","subtype":"annotation_generic","userRoleId":1,"userRoleName":"signer-1","config":"{\"maskSubtype\":\"mask_number\",\"placeholder\":\"Number\",\"mask\":{\"decimal\":true,\"groupSeparated\":false,\"groupSeparator\":\" \",\"groupLength\":3,\"radixPoint\":\",\"},\"unwrappedText\":\"\",\"group\":false}","align":"left","fontSize":12}:signature_field_end

Currency

signature_field_start:{"type":"annotation","subtype":"annotation_generic","userRoleId":1,"userRoleName":"signer-1","config":"{\"maskSubtype\":\"mask_currency\",\"placeholder\":\"Currency\",\"mask\":{\"decimal\":true,\"groupSeparated\":false,\"groupSeparator\":\" \",\"groupLength\":3,\"radixPoint\":\".\",\"currencyChar\":\"$\",\"currencyCharPosition\":\"before\"},\"unwrappedText\":\"\",\"group\":false}","align":"left","fontSize":12}:signature_field_end

Percentage

signature_field_start:{"type":"annotation","subtype":"annotation_generic","userRoleId":1,"userRoleName":"signer-1","config":"{\"maskSubtype\":\"mask_percentage\",\"placeholder\":\"Percentage\",\"mask\":{\"alias\":\"percentage\"},\"unwrappedText\":\"\",\"group\":false}","align":"left","fontSize":12}:signature_field_end

Company

signature_field_start:{"type": "annotation","subtype": "annotation_company","userRoleId": 1, "userRoleName": "signer-1","align": "left","fontSize": 10,"tooltip": "Company"}:signature_field_end

signature_field_start:{ "type": "annotation","subtype": "annotation_company","userRoleId": 1, "userRoleName": "signer-1","user":"adam.smith@circularo.com","id":"signer-1","align": "left","fontSize": 10,"tooltip": "Company"}:signature_field_end

Date

signature_field_start:{"type":"annotation","subtype":"annotation_date","tooltip":"Select date…","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

signature_field_start:{"type":"annotation","subtype":"annotation_date","tooltip":"Select date…","user":"adam.smith@circularo.com","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

Name

signature_field_start:{ "type": "annotation","subtype": "annotation_full_name","userRoleId": 1, "userRoleName": "signer-1","align": "left","fontSize": 10,"tooltip": "Full name","bold": "true","color": "#e80c12"}:signature_field_end

Full name aligned right side

signature_field_start:{ "type": "annotation","subtype":"annotation_full_name","userRoleId": 2,   "userRoleName":"signer-2","align": "right","fontSize":10,  "tooltip":"Please enter your full name","bold":"true","color": "#e80c12"}:signature_field_end

signature_field_start:{"type":"annotation","subtype":"annotation_full_name","user":"adam.smith@circularo.com","id":"signer-1","userRoleId":1,"userRoleName":"signer-1","align":"center", "fontSize":10,"tooltip":"Please enter your full name","bold": "true","color": "#E80C12"}:signature_field_end

Mail

signature_field_start:{ "type": "annotation","subtype": "annotation_mail","userRoleId": 1, "userRoleName": "signer-1","align": "left","fontSize": 10,"tooltip": "Enter email address"}:signature_field_end

signature_field_start:{ "type": "annotation","subtype": "annotation_mail","user":"adam.smith@circularo.com", "userRoleId": 1,"userRoleName": "signer-1","align": "left","fontSize": 10,"tooltip": "Enter email address"}:signature_field_end

Phone

signature_field_start:{ "type": "annotation","subtype": "annotation_phone", "userRoleId": 1, "userRoleName": "signer-1","align": "left","fontSize": 10, "tooltip": "Enter your mobile number"}:signature_field_end

Job Title

signature_field_start:{ "type": "annotation", "subtype": "annotation_role", "userRoleId": 1, "userRoleName": "signer-1", "align": "left", "fontSize": 10, "tooltip": "Designation" }:signature_field_end

signature_field_start:{ "type": "annotation", "subtype": "annotation_role", "userRoleId": 1, "userRoleName": "signer-1", "align": "left", "fontSize": 10, "tooltip": "Designation", "user":"adam.smith@circularo.com","id":"signer-1"}:signature_field_end

List

signature_field_start:{"type":"annotation","subtype":"annotation_dropdown","userRoleId":1,"userRoleName":"signer-1","user":"adam.smith@circularo.com","id":"signer-1","align":"left","fontSize":10,"values":["option1","option2","option3"],"text":"option2"}:signature_field_end

Check

signature_field_start:{"type": "annotation", "subtype": "annotation_check", "userRoleId": 1, "userRoleName":"signer-1", "user":"adam.smith@circularo.com","id":"signer-1"}:signature_field_end

Radio button

signature_field_start:{"type": "annotation", "subtype": "annotation_radio", "userRoleId": 1,"userRoleName":"signer-1","groupId":0}:signature_field_end

signature_field_start:{"type": "annotation", "subtype": "annotation_radio", "userRoleId": 1,"userRoleName":"signer-1","user":"adam.smith@circularo.com","id":"signer-1""groupId":0}:signature_field_end

Link

signature_field_start:{"type": "annotation", "subtype": "annotation_link", "userRoleId": 1, "userRoleName":"signer-1","link":"https://circularo.com","text":"Circularo", "align":"left","fontSize":10,"id":"signer-1"}:signature_field_end

Comb field

signature_field_start:{"type": "annotation", "subtype": "annotation_generic", "userRoleId": 1, "userRoleName":"signer-1","maxCharacters":5,"align":"left","fontSize":10,"id":"signer-1"}:signature_field_end

Image

signature_field_start:{"type":"image","userRoleId":1,"userRoleName":"signer-1"}:signature_field_end

signature_field_start:{"type":"image","userRoleId":1,"userRoleName":"signer-1","user":"adam.smith@circularo.com","id":"signer-1"}:signature_field_end

JSON text options

The different types of attributes that can be defined in the JSON text are listed below.

• id - (string) Identifier of sign field (doesn’t have to be unique). If ID is provided, then it’s used, otherwise random unique ID is generated. It can be used only using workflow.

• user - (string) User which has this sign field assigned to

• position - (Object) Position is containing position itself (top left corner) and dimensions, both are expressed as a ratio within document page ⇒ all numbers are between 0 and 1

  • percentX - (float) X coord of top left corner <0, 1)

  • percentY - (float) Y coord of top left corner <0, 1)

  • percentWidth - (float) Width of field (0, 1>

  • percentHeight - (float) Height of field (0, 1>

The position will be filled automatically based on the rectangle position. Will be ignored if present in JSON.

• type - (string) Type of sign field [signature, initials, stamp, wacom, annotation, image]

• timestamp - (boolean) Should timestamp be embedded into a final signature? (not supported for annotation and image, default false)

• text - (string) Text of annotation (annotation only), for annotation_dropdown it sets the default value selected in the dropdown list. The value must match one of the value of values.

If you want to make new line use the following character sequence \n.

• align - (string) Text alignment of annotation [left, center, right] (annotation only, default left)

• fontSize - (float) Font size of annotation (annotation only, default 11)

• bold - (boolean) Use bold font (annotation only, default false)

• color - (string) Color that text should use in hex format e.g. #7E544B (annotation only, default #000000)

• page - (integer or Array<integer>) Page(s) on which this sign field should be located (first page is 1)

The page will be filled automatically based on the rectangle position. Will be ignored if present in JSON.

• order - (integer) Order in which this sign field should be signed (always signing from the lowest non-signed field) It can be used only using workflow.

• subtype - (string) Further specification of sign field type (used only for docId for now) [ annotation_generic, annotation_date, annotation_full_name, annotation_company, annotation_phone, annotation_mail, annotation_role, annotation_check, annotation_dropdown, annotation_link ]

• required - (boolean) Sign field must be filled for the sign to complete (default false).

• tooltip - (string) Tooltip displayed to the user.

• usage - (string) How this field should be filled [manual, automatic] (default manual) Only relevant for workflow (autosign feature).

• values - (Array<string>) Array of possible values for annotation (annotation > annotation-dropdown only)

• shareId - (string) Share ID which this sign field is bounded to.

ShareId will be filled by the backend while sharing. Sign fields used during workflow have this value empty. Will be ignored if present in JSON.

• numberOfLines - (integer) How many lines annotation has. (annotation only, default auto)

• userRoleId - (integer) Identifier of the signer, used only in sign templates and signature extraction for the first assignment to "real" users or shares.

• userRoleName - (string) Only serves as the display name for userRoleId

Tips and Tricks

Always use the same combination of userRoleName/userRoleId/user. If they are specifying the same person → Must be the same in all fields.

Disclaimers

• When adding the text in the rectangles make sure the entire text is within the rectangle else when the document is parsed by CIRCULARO the rectangle will not be detected as a signing component.

  As can be seen below the recipient signature field was not detected.

• Make sure there are no whitespaces in the JSON text, else the field will be recognized but it will also display the JSON text (it will not get replaced).

MS word document examples

• MS Word eSigning Template - sample 1.docx

• MS Word eSigning Template - sample 2.docx

• MS Word eSigning Template - sample 3.docx

• MS Word eSigning Template - sample 4.docx

• MS Word eSigning Template - sample 5.docx