Defining JotBlocks Through Embedded Text Tags

Standard Format for Embedding JotBlocks

The JotBlock beginning and end tags are defined by the delimiting strings

{{!##{ and }##!}}

Attributes of the JotBlock are specified through comma-separated name/value pairs like
PropertyName:"Value"

The final composition follows the specification:

{{!##{Name[1]:"Value[1]",Name[2]:"Value[2]",…, Name[n]:"Value[n]"}##!}}

When the document is uploaded, then the text tag will be stripped from the document body; the tag is only used as a placeholder to indicate the location and properties of a JotBlock for pre-processing.

It is not possible to add a text tag without some modification to the XML, however. When using the SubmitWithFile and AsyncSubmitWithFile methods, the FileDocument element of the XML – which contains the ContextIdentifier attribute – must be modified to contain a ParseDocument attribute with value "true"; else, if this value is false or missing the document will not be checked for the existing of text tags. When using the SubmitWithFileRetrieval and AsyncSubmitWithFileRetrieval methods, the ParseDocument attribute must be added to the FileRetrievalDocument element.

So, for example, to override the location of a JotBlock named CustomerSignature that is defined in the template, the following string could be embedded within the normal flow of the document (in this case Name refers to the property called Name):

{{!##{Name:"CustomerSignature"}##!}}

To create an entirely new JotBlock in which the customer should write their initials using a mouse signature, the following could be specified:

{{!##{Name:"CustomerInitials",InputType:"Signatory",FieldType:"Written",Border:"All",InkColor:"Blue",Instructions:"Please use the mouse to write your initials indicating you agree with this section.",Height:"0.05",Width:"0.15", SignatoryEmail:"john.doe@assuresign.com"}##!}}

A new written JotBlock named CustomerInitials will be created with a full border in blue ink. It will be filled in by the signatory with email address john.doe@assuresign.com. It will occur in the document flow where the tag has been placed, and will be 0.0454545% the height of the page and 0.1176471% the width of the page (on a page 850 px by 1100 px, that calculates to a width of 100 pixels and a height of 50 pixels). When presented, the customer will be prompted: "Please use the mouse to write your initials indicating you agree with this section."

Multiple Choice JotBlocks

Note that special configuration is needed when SignatoryInputType is specified as MultipleChoiceText, MultipleChoiceGraphic, MultipleChoiceRadio, or MultipleChoiceCheckbox.

For MultipleChoiceText and MultipleChoiceGraphic, the multiple choice options must be defined as an array of name/value pairs, such as in these examples:

{{!##{Name:"AgeCheck",InputType:"Signatory",FieldType:"Typed",Instructions:"Are you over 18 years of age?", SignatoryEmail:"john.doe@assuresign.com",SigningStep:"1", Required:"true",InputType:"Signatory", SignatoryInputType:"MultipleChoiceText", TypedFieldOptions:[{Text:"Yes I am", TextValue:"Yes"}, {Text:"I am not",TextValue:"No"}] }##!}}

{{!##{Name:"AgeCheckGraphic",InputType:"Signatory",FieldType:"Typed",Instructions:"Are you over 18 years of age?", SignatoryEmail:"john.doe@assuresign.com",SigningStep:"1", Required:"true",InputType:"Signatory", SignatoryInputType:"MultipleChoiceText", TypedFieldOptions:[{Text:"Yes I am", TextValue:"Yes",GraphicRenderType:"Check"}, {Text:"I am not",TextValue:"No",GraphicRenderType:"Empty"}] }##!}}

For MultipleChoiceRadio and MultipleChoiceCheckbox, the multiple choice options are each associated with an individual region of the document, so the options must be defined as separate tags (in addition to the primary tag for the JotBlock – which in and of itself will not correspond to any visual element on the completed document). For example, the main JotBlock may be defined like this:

{{!##{Name:"AgeCheck",InputType:"Signatory",FieldType:"Typed",Instructions:"Please select the age group you belong to.", SignatoryEmail:"john.doe@assuresign.com",SigningStep:"1", Required:"true",InputType:"Signatory", SignatoryInputType:"MultipleChoiceRadio"}##!}}

Note that the TypedFieldOptions are not defined in this tag. These options will be defined using separate tags – one tag for each option. For example, the following option tags might accompany the main JotBlock tag defined above:

{{!##{JotBlock:"AgeCheck",Text:"0-17",TextValue:"0-17",GraphicRenderType:"Check",Width:".025",Height:".01"}##!}} {{!##{JotBlock:"AgeCheck",Text:"18-25",TextValue:"18-25",GraphicRenderType:"Check",Width:".025",Height:".01"}##!}} {{!##{JotBlock:"AgeCheck",Text:"26-40",TextValue:"26-40",GraphicRenderType:"Check",Width:".025",Height:".01"}##!}} {{!##{JotBlock:"AgeCheck",Text:"41-55",TextValue:"41-55",GraphicRenderType:"Check",Width:".025",Height:".01"}##!}} {{!##{JotBlock:"AgeCheck",Text:"55+",TextValue:"55+",GraphicRenderType:"Check",Width:".025",Height:".01"}##!}}

In the example above, note that there are differences between typical JotBlock text tags and typed field option text tags.

• Most importantly, instead of the JotBlock name being specified using "Name", notice that for the typed field option tags it is specified using "JotBlock." This instructs AssureSign to treat the tag as a typed field option rather than as a JotBlock and to associate it with a JotBlock with the indicated name.
• In addition to the "JotBlock" property, the only supported attributes for typed field option tags are:
  • Text
  • TextValue
  • GraphicRenderType
  • Width
  • Height

Applying "Fixed" Text

In order to apply Fixed text that may not be modified by signatories, you may specify something like the following:

{{!##{Name:"MarkWithDocCompletionTime",InputType:"Fixed",FieldType:"Typed",FixedInputTimingType:"OnDocumentComplete",FontName:"CourierNew",FontSize:"Six",Border:"All",Height:"0.05",Width:"0.30",Value:"Document Completed On: [Completion Date]"}##!}}

An important item to note is that a Fixed JotBlock is not assigned to a signatory, therefore it is not necessary to specify SignatoryEmail, SignatoryEmailParameterName, SignatoryMobilePhone, or SignatoryMobilePhoneParameterName. In addition, the Value contents in this example contain a merge field. Since [Completion Date] is present only at the time of completion of the document, the FixedInputTimingType is set to "OnDocumentComplete" so that the data is applied properly.

Applying Timestamps

In order to apply a timestamp, you might use the below example:

{{!##{Name:"Timestamp", InputType:"Fixed",FontName:"TimesNewRoman",FontSize:"Twelve", FieldType:"Typed",Height:"0.025",Width:"0.25",FixedInputTimingType:"OnDocumentComplete",Value:"[{formatDate(get('Completion Date'), 'MM-DD-YYYY')}]"}##!}}

This will create the timestamp when the document is completed.  Additionally, you can format the date, as shown in the example, to exclude the time, should you choose to.

Embedding in ActualText

In many cases, the text tags (as described above) will be embedded in the normal visible PDF content. However, there may be cases where it is desirable to embed text tags using an ActualText entry in a property list for a marked-content sequence to allow Unicode support without having to embed work with embedding a Unicode font in the PDF file.
For example, a tag might be embedded in an ActualText entry in this way:

/Span <</ActualText ({{!##{Name:"JotBlock1", ...}##!}}>> BDC ... EMC

Properties that may be set on dynamically created JotBlocks are listed alphabetically:
A - H | I - R | S - Z

Signer Attachments

Signer attachment text tags work exactly like embedded JotBlocks with the exception that you must specify the SignerAttachment property. This identifies the text tag as a signer attachment instead of a JotBlock.

Properties that may be set on dynamically created signer attachments can be found here.

Limitations

Important: Due to the time required to individually scan each page in a document for text tags, AssureSign is configured to only allow submission of documents containing 250 pages or less when the ParseDocument attribute is set to true. However, this page count limit is reset to the overall page limit of 2000 pages if one or both of the

• InitialPagesToParse or
• FinalPagesToParse

attributes are set to a valid numerical value where the sum total of those values does not exceed 250. Use of these attributes will instruct AssureSign to only check the first N and/or last N pages of the document for text tags.

This can be useful in scenarios where it is known that JotBlock locations will always be at the beginning or end of the document. Use of these attributes even with documents with a smaller number of pages (ex. a 5 page document where it is known that that the signature JotBlock text tag definition will always be on the last page) because setting those flags will reduce the overall response time of the submission by allowing AssureSign to bypass unnecessary processing of pages that don't contain text tags.