Follow

Merge Fields

Last updated 2017-02-16 18:53:05 UTC

AssureSign supports the concept of merge fields which may be used to populate email notifications, DocumentTRAK notifications, or JotBlocks with document/envelope-specific data. There are two primary categories of merge fields in AssureSign:

Each item below indicates whether it may be used in Email designs, DocumentTRAK, and JotBlocks.

Global Merge Fields

Note that some merge fields are only applicable within the context of a document-level DocumentTRAK notification, whereas others are applicable for both document-level and envelope-level DocumentTRAK notifications. In the case of a merge field that is applicable for both document-level and envelope-level notifications, the returned value may be context-specific.

General merge fields available in any context:

MERGE FIELD   DESCRIPTION  EMAIL  DocumentTRAK  JOTBLOCK
[Account Logo] This will insert your logo that was uploaded for signing customization into the body of an email design. Y N N
[Authentication - Username] The username specified for the default DocumentTRAK credential account setting N Y N
[Authentication - Password] The password specified for the default DocumentTRAK credential account setting N Y N
[Company Name] The name of your organization as defined in your account settings (this could be helpful should you need to differentiate documents by specific account) Y Y Y
[Custom Message] The custom message provided (if any) for the email notification Y N N
[Recipient Name] The name of the current email recipient Y N N
[Username] The user account to whom the document/envelope is assigned in the AssureSign system Y Y Y
[User Full Name] The full name of the user to whom the document/envelope is assigned in the AssureSign system Y Y Y

Context-specific merge fields available for use with documents or envelopes:

MERGE FIELD   DESCRIPTION  EMAIL  DocumentTRAK  JOTBLOCK
[Transaction Name] The user-specified name assigned to a document or envelope during the setup process Y Y Y
[Transaction Type Name] The context (either 'Document' or 'Envelope') for the current notification Y Y Y
[Transaction Creation Date] The date the document or envelope was first created Y Y Y
[Transaction Start Date] The date on which the document/envelope signing process was started Y Y Y
[Transaction Completion Date] The date on which document/envelope signing was completed Y Y Y
[Expiration Date] The date on which the document/envelope is set to expire Y Y Y
[Cancelled Date] The date on which the document/envelope was cancelled (if applicable) Y Y Y
[Declined Date] The date on which the document/envelope was declined (if applicable) Y Y Y
[Transaction Signer Authentication Failure Date] The date on which signer authentication failed for the document/envelope (if applicable) Y Y N
[Declining Signatory] The name and email address of the signatory that declined the current document/envelope (if applicable) Y Y N
[Declining Signatory Feedback] The feedback provided (if any) by the signatory that declined signing for the document/envelope (if applicable) Y Y N
[Signatory KBA Summary] A summary of all knowledge-based authentication for signers of a document or envelope Y Y Y
[Envelope ID] The unique identifier assigned to the envelope at the time of creation and returned in the CreateEnvelope operation defined in the DocumentNOW Interface Documentation (only applicable for envelope-level notifications or document-level notifications when the document belongs to an envelope) Y Y Y
[Envelope AuthToken] This secondary envelope security token is required to perform DocumentNOW operations on a specific Envelope ID, so it may be beneficial to return this in the case that it is not being recorded at the time of envelope creation (only applicable for envelope-level notifications or document-level notifications when the document belongs to an envelope) Y Y Y
[Envelope Name] The user-specified name assigned to an envelope during the setup process Y Y Y
[Envelope Creation Date] The date on which the envelope was first created Y Y Y
[Envelope Start Date] The date on which the envelope signing process was started Y Y Y
[Envelope Completion Date] The date on which the envelope was completed (if applicable) Y Y N
[Envelope Expiration Date] The date on which the envelope is set to expire Y Y Y
[Envelope Cancelled Date] The date on which the envelope was cancelled (if applicable) Y Y N
[Envelope Declined Date] The date on which the envelope was declined (if applicable) Y Y N
[Envelope Signer Authentication Failure Date] The date on which signer authentication failed for the envelope (if applicable) Y Y N
[Signatories] A comma-separated list of the names of each signatory for the current document/envelope Y N N
[Link - Document Signing] The signatory-specific signing link for the current document/envelope. If the current recipient is not a signatory for the document/envelope (i.e. originating user recipient or custom recipient), no signing link will be available so this will be rendered as a hash (#). Y N N
[Link - Final Document] A link to view the completed document/envelope Y N N
[Completed Document] The binary file data (Base64-encoded) for the completed document PDF N Y N
[Completed Document and Completion Report] The binary file data (Base64-encoded) for the for the completed document with the document completion report appended PDF N Y N
[Document Completion Report] The binary file data (Base64-encoded) for the document completion report PDF N Y N
[Envelope Completion Report] The binary file data (Base64-encoded) for the envelope completion report PDF N Y N
[Envelope Status] A status code indicating the current status of the document (EST = Envelope Started, ECO = Envelope Completed, ECA = Envelope Cancelled, ESD = Envelope Declined, EEX = Envelope Expired, SAF = Signer authentication failed) N Y N
[Attachment - Envelope Completion Report] This merge field will attach the envelope completion report to an email if the report is under 10MB and will show no content for the merge field itself. If it is over 10MB, then a warning will appear will as the merge field text. Y N N

Specialized merge fields only available for use in feedback or signer authentication failure notifications:

MERGE FIELD   DESCRIPTION  EMAIL  DocumentTRAK  JOTBLOCK
[Signatory Name] The name of the signatory that triggered the notification (i.e. submitted feedback, declined signing, etc.) Y Y N
[Signatory Email] The email address for the signatory that triggered the notification (i.e. submitted feedback, declined signing, etc.) Y Y N
[Signatory Authentication Failure Details] Details regarding the cause for a signatory authentication failure Y Y N
[Signatory Feedback] The feedback submitted by a signatory Y Y N
[Signatory KBA Result] The result of knowledge-based authentication for a signatory Y Y N
[Signatory KBA Result Details] Details regarding the result of knowledge-based authentication for a signatory Y Y N

Merge fields only available for use with documents:

MERGE FIELD   DESCRIPTION  EMAIL  DocumentTRAK  JOTBLOCK
[Document ID] The unique identifier assigned to the document at the time of launch and returned in the submit operations defined in the DocumentNOW Interface Documentation Y Y Y
[Document AuthToken] This secondary document security token is required to perform DocumentNOW operations on a specific Document ID, so it may be beneficial to return this in the case that it is not being recorded at the time of document launch Y Y Y
[Document Name] The user-specified name assigned to a document during the setup process Y Y Y
[Order ID] Your specific information that is passed when a document is launched, and will be critical to return if it represents a unique data key in your system Y Y Y
[Signing Step] This integer string could be beneficial in multi-step document signing operations where the web notification is intended to be used to return an interim response after a signing step is completed Y Y N
[Document Creation Date] The date on which document was first created Y Y Y
[Document Start Date] The date on which the document signing process was started Y Y Y
[Step Completion Date] The date on which the specified signing step was completed (only applicable on signing step-level notifications) Y Y N
[Completion Date] The date on which the document was completed (if applicable) Y Y Y
[Document Expiration Date] The date on which the document is set to expire Y Y Y
[Document Cancelled Date] The date on which the document was cancelled (if applicable) Y Y N
[Document Declined Date] The date on which the document was declined (if applicable) Y Y N
[Document Signer Authentication Failure Date] The date on which signer authentication failed for the document (if applicable) Y Y N
[Original Document] The binary file data (Base64-encoded) for the original document that was passed into AssureSign N Y N
[Interim Document] The binary file data (Base64-encoded) for the document in progress (only applicable prior to a document being completed/cancelled/declined/expired) N Y N
[Document Status] A status code indicating the current status of the document (DST = Document Started, DCO = Document Completed, DCA = Document Cancelled, DSD = Document Declined, DEX = Document Expired, SAF = Signer authentication failed) N Y N
[Link - Original Document] A link to the originally uploaded document Y N N
[Link - Interim Document] A link to the in-progress version of a document Y N N
[Attachment - Original Document] This merge field will attach the original document to an email if the document is under 10MB and show no content for the merge field itself. If it is over 10MB, then a warning will appear will as the merge field text. Y N N
[Attachment - Final Document] This merge field will attach the final document to an email if the document is under 10MB and show no content for the merge field itself. If it is over 10MB, then a warning will appear will as the merge field text. Y N N
[Attachment - Document Completion Report] This merge field will attach the document completion report to an email if the report is under 10MB and will show no content for the merge field itself. If it is over 10MB, then a warning will appear will as the merge field text. Y N N

Template-specific Merge Fields

You may also manually enter bracket-enclosed names of parameters or JotBlocks that exist for specific templates when configuring the email designs, DocumentTRAK designs, or Fixed JotBlocks. This may be data passed in via the DocumentNOW services (parameters) or text data entered by a signer in a JotBlock field. Care will need to be taken to consider where merge fields are used as some merge fields such as the document completion date ( [Document Completion Date] ) are not available until a document is completed and cannot be used effectively earlier in the signing process. In the context of email or DocumentTRAK designs, consider naming your designs appropriately so that later assignment in a specific template will be done without confusion.

You will need to know the exact name of the parameter or JotBlock in the template where this merge field will be used. For example:

You will be creating a template to be signed by a prospective customer. The customer will be entering their contact phone number at the time of signing. You will be naming the typed JotBlock “Customer Phone Number” in the template creation interface. The email design is to be sent on document completion, and the JotBlock is required to be filled in by the customer. Therefore, considering that this email design will always be used for that specific template, you type the merge field

[Customer Phone Number]

in the body of your email design in the email design editor where it should be populated.

It would be possible to re-use an email or DocumentTRAK design which contains custom parameter or JotBlock merge fields where each template using the design contains the specific named parameter/JotBlock. The following should be considered when creating email or DocumentTRAK designs which return template specific data:

  • If creating the design prior to the template, then keep track of the parameter and JotBlock names used in order to ensure the data will be returned to you properly later on.
  • If creating the template first, then you can always edit the workflow after creation to assign the email or DocumentTRAK design that contains references to parameters/JotBlocks previously created in the template.
  • If you specify a correct merge field that is either not required to be filled in or that is assigned a value in a later step, then your email design will treat the merge field as normal text
  • It is possible to “pass-through” data that is sent as an integration parameter through the DocumentNOW web services rather than being populated by signer entry; merely specify the name of the parameter as the merge field.
  • You will be warned when the workflow is validated for errors if a string appears to be a merge field entry (a bracket enclosed value) but does not match any configured parameter, JotBlock or globally available merge field on the template. In this case, the workflow will still be saved properly but may not perform as expected.

Security Considerations

It is important to consider what types of data you may be passing in emails and DocumentTRAK web notifications. For example, personal customer information passed in a DocumentTRAK web notification should be sent only using a secure SSL (HTTPS) connection. What is important is that you analyze the data you are passing and sending and ensure that you are complying with your internal best practices on treatment of customer data.

Was this article helpful?
0 out of 1 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.