template-archive Signature Blocks

It would be very useful to be able to create clause templates that can represent signature blocks.

This would allow a user (end-user or vendor product) to render a CiceroMark contract to PDF (containing both clauses and signature blocks) and to send the PDF to an electronic signature service, and have the signature input fields automatically inserted in the correct position in the document.

The major electronic signature solutions all support features to auto-place signature blocks, and related signature metadata, based on text in the PDF document. Essentially this involves specifying a regex string to look for in the PDF, and when the string is found an input field, or signature entry field, is positioned at the location of the text.

DocuSign: https://support.docusign.com/en/guides/AutoPlace-New-DocuSign-Experience
Adobe Sign: https://helpx.adobe.com/sign/using/text-tag.html
HelloSign: https://app.hellosign.com/api/textTagsWalkthrough

Contract Text

DocuSign Tabs

Proposed Design

Signature blocks are identical to other clauses.

Example: https://github.com/accordproject/cicero-template-library/tree/master/src/signature-name-date

Sample grammar:

Signature: {{signatureAnchorTag}}

Title: {{titleAnchorTag}}

Full name: {{nameAnchorTag}}

Date signed: {{dateAnchorTag}}

Favorite Color: {{favoriteColorAnchorTag}}

Sample model:

asset SignatureClause extends AccordClause {

  @DocuSignTab("Text")
  o String favoriteColorAnchorTag

  @DocuSignTab("Title")
  o String titleAnchorTag optional

  @DocuSignTab("SignHere")
  o String signatureAnchorTag

  @DocuSignTab("FullName")
  o String nameAnchorTag

  @DocuSignTab("DateSigned")
  o String dateAnchorTag
}

The signature block can be inserted into a contract and the 3 anchor tag values entered. These anchor tag values are then used by the e-signature product to auto-place the corresponding input fields and the signature entry field onto the generated PDF for the contract. Note that Concerto decorators may be used to supply additional vendor specific field level metadata.

Identifying Signature Blocks

Upstream projects and embedding products will commonly need to visually and programmatically distinguish signature blocks from regular clauses. Signature blocks must have the keyword signature-block in their list of keywords, specified in package.json.

Runtime Requirements

Vendor products may use the signature-block keyword to identify signature blocks. They can then use the values of the contract data (anchor tag values) to parameterise the creation of the electronic signature envelope, or API calls to send the rendered PDF for signature.

To support a signature block for the seller and a signature block for the buyer, the values of the template variables must encode the email (or other identifier) for the intended recipient. They must also be unique within the generated PDF so that the auto-place logic positions the signature block and other fields correctly.

Signature: "{{sn}}|[email protected]"

Title: "{{title}}|[email protected]"

Full name: "{{fullName}}|[email protected]"

Date signed: "{{dateSigned}}|[email protected]"

Favorite Color: "{{favoriteColor}}|[email protected]"

Challenges

The anchor tags themselves should be invisible in the generated PDF — usually this is by making the text colour white, so that they are not visible against the white background of the PDF.

To support this the CiceroMark -> HTML transformation should add a data-concerto-field attribute to the variable in the generated HTML, allowing CSS (or similar) to be used to control the colour and style of variables based on class names.

The existing code for the ToHtmlStringVisitor is:

        case 'Variable': {
            parameters.result += `<span class="variable" name="${thing.name}">${thing.value}</span>`;
        }
            break;
        case 'FormattedVariable': {
            parameters.result += `<span class="variable" name="${thing.name}" format="${thing.format}">${thing.value}</span>`;
        }
            break;
        case 'EnumVariable': {
            const enumValues = encodeURIComponent(JSON.stringify(thing.enumValues));
            parameters.result += `<span class="variable" name="${thing.name}" enumValues="${enumValues}">${thing.value}</span>`;
        }

This code should be extended to also include the FQN for the type of the variable. E.g.

<span class="variable" data-concerto-field="org.accordproject.signature.SignatureClause.signatureAnchorTag" name="signatureAnchorTag">/sn1/</span>

Questions and Issues

By adding data-concerto-field names in the ToHtmlStringVisitor this logic cannot be shared with other output formats, that might need similar white-on-white support in the future. For example, if we implement a native CiceroMark -> PDF transformation, or a CiceroMark -> DOCX transformation.
Accord Project doesn't have a built-in transformation from CiceroMark to PDF, however there are existing tools to convert HTML to PDF. See https://github.com/accordproject/markdown-transform/issues/51

Jun 19 '20 08:06 dselman

I would advocate for a keyword of signature-block rather than signature-clause, the latter feels semantically wrong to me.

Also, can we put the FQN in another attribute, something like data-concerto-type to keep it HTML5 compliant? https://html.spec.whatwg.org/#embedding-custom-non-visible-data-with-the-data-*-attributes

On a separate note, this reminds me that we should change the class attributes to follow the class naming conventions that have been started in web-components IMO, e.g. ui-cicero___foo.

Jun 19 '20 19:06 mttrbrts

Hi @mttrbrts & @dselman - This might be a red herring (so please ignore if it is) but could this not be tied into identity in some way? For our implementation, we are "signing" our agreements using 2FA and other proofs of identity and then storing these in an immutable data store along with the contract instance. This constitutes the legal signature. In the longer term, we'd ideally want the signed contract instances linked to actual digital signatures (for smart legal contracts deployed to, for example, Fabric or Corda) but that's a conversation for another day. Thoughts?

Jun 20 '20 07:06 martinhalford

I would advocate for a keyword of signature-block rather than signature-clause, the latter feels semantically wrong to me.

Agreed.

Also, can we put the FQN in another attribute, something like data-concerto-type to keep it HTML5 compliant? https://html.spec.whatwg.org/#embedding-custom-non-visible-data-with-the-data-*-attributes

Sounds good.

Jun 20 '20 12:06 dselman

Hi @mttrbrts & @dselman - This might be a red herring (so please ignore if it is) but could this not be tied into identity in some way? For our implementation, we are "signing" our agreements using 2FA and other proofs of identity and then storing these in an immutable data store along with the contract instance. This constitutes the legal signature. In the longer term, we'd ideally want the signed contract instances linked to actual digital signatures (for smart legal contracts deployed to, for example, Fabric or Corda) but that's a conversation for another day. Thoughts?

For this issue I'm focused on the "simplest thing that can work" for the basic PDF sent out for electronic signature use case (DocuSign, Adobe Sign, HelloSign et al). Let's track additional requirements in another issue.

Jun 20 '20 12:06 dselman

For this issue I'm focused on the "simplest thing that can work" for the basic PDF sent out for electronic signature use case (DocuSign, Adobe Sign, HelloSign et al). Let's track additional requirements in another issue.

Okay. Fair call. I'll raise a separate issue to discuss identity.

Jun 21 '20 00:06 martinhalford