Launched in August 2024, the new Text Tagging feature revolutionizes how developers prepare dynamic documents for digital signatures. It simplifies the integration process by using document content to define field anchors, eliminating the need for complex PDF libraries.

Who Is This Article For?

This article explores the functionality of Text Tagging, demonstrates its implementation through a sample web application, and highlights its potential to streamline document workflows across various industries. Whether you're a developer, product manager, or project lead, understanding Text Tagging can significantly enhance your digital signature integration capabilities with SIGNiX.

The Problem: Signature Fields on Dynamic Documents

Before Text Tagging, documents submitted to SIGNiX via the API required pre-existing fields in static PDFs. While this approach worked fine when developers could embed fields using desktop tools like Adobe Acrobat, it posed challenges for dynamic documents, where content “reflows” from transaction to transaction due to variables. These reflowing documents often caused signature fields and other important elements to move, complicating the signing process.

Existing SIGNiX integrations could handle dynamic documents by introducing PDF libraries, but this approach often led to increased costs and complexity for developers.

The Solution: Text Tagging

Text Tagging eliminates the need to create and manage PDF libraries to place fields in dynamic PDFs, making it easier and more cost-effective for developers. Moreover, text tagging makes it easier for technically savvy staff to use no-code or light-coding solutions (e.g., Microsoft Word, HTML, etc) to generate documents ready for the signature workflow. By aligning with similar workflows in other e-signature platforms, text tagging provides customers a seamless transition to SIGNiX if they’re migrating from other e-signature providers.

How Does Text Tagging Work?

Text Tagging works by scanning the document for specific keywords or phrases called anchors (e.g. “Signature:” or “Lessee:”) to place signature fields in the correct positions. Developers can define where these fields appear relative to those anchors based on a simple coordinate system.

The lower-left corner of the anchor text serves as the origin point of the signature field. A coordinate system (measured in points, or 1/72 inch) is used to position fields relative to the origin. You can then define the field’s height, width, and position based on offsets.

When submitting a transaction via the API, the SubmitDocument method extends to include one or more <TextTagField> elements.

These elements specify details such as:

• Anchor text: "Signature:"
• X-offset: 150 points to the right
• Y-offset: 10 points down
• Width: 120 points
• Height: 24 points

An alternative to using visible anchor text is "white text tagging". This involves using text that's the same color as the page background, making it invisible to the human eye but detectable by the system. This approach is particularly useful for documents with multiple fields, allowing for unique identifiers like %SIG1% that only the application and SIGNiX can see.

Click here for more technical details on Text Tagging.

Here’s a sample structure:

<Form>
    <RefID>ZoomJetPackLease</RefID>
    <Desc>Zoom Jet Pack Lease</Desc>
    <FileName>ZoomJetPackLease.pdf</FileName>
    <MimeType>application/pdf</MimeType>
    <TextTagField> ... </TextTagField>
    <Length>165238</Length>
    <Data>...</Data>
    ...
</Form>

Note that the <TextTagField> elements replace the normal SubmitDocument elements for fields, which is important for developers familiar with the previous method.

Click here for more technical details on the SubmitDocument API call.

Creating a Demo Implementation

We’ve created a sample application for developers to review, modify, or use as the foundation of another project. It’s written in Python, utilizing Flask and several other Python modules. Developers will need to install the open-source WebKit HTML To PDF utility (wkhtmltopdf).

Click here to access the GitHub repository.

How the Demo Works

To understand the Text Tagging feature’s role in an end-to-end solution, the demo application goes beyond the call to SIGNiX and demonstrates step-by-step the lifecycle of a simple transaction:

1. Originate the transaction: A lease manager starts the process.
2. Create a dynamic document: A template dynamically generates an HTML document.
3. Convert HTML to PDF: The dynamic HTML document is converted to a PDF using open-source tools.
4. Configure document metadata: Define the document set, field tagging info, and field-to-signer assignments.
5. Assign signers: Define who signs what, in what order, and how.
6. Submit the transaction: Build the SubmitDocument call and serialize it into the required XML format.

The demo also includes a static document for comparison, helping developers understand the differences between handling static and dynamic documents.

These steps are wrapped into a simple web application easily accessed via a browser.

Creating Text Tagging Templates

In the demo application, the dynamic document has two signature fields and two date fields automatically populated by SIGNiX when the document is signed.

The content of the document can vary (for example, more jet packs could be added to the list of vehicles being leased). However, the signature lines are always positioned relative to specific text anchors, such as "LESSOR:" and "LESSEE:" for signature fields.

To handle these fields, the application defines a "document set" object in a JSON-like format. 

Here's an expanded version of the document set object, including both dynamic and static document examples:

# This function is used to create an object that is used to populate the docs data

def docs_data_create():
    docs_data = {
        "doc_set_description": "Zoom Jet Pack Lease Documents",
        "docs_list": [
            {
                "ref_id": "ZoomJetPackLease",
                "desc": "Zoom Jet Pack Lease",
                "file_name": "ZoomJetPackLease.pdf",
                "mime_type": "application/pdf",
                "doc_source_type": "dynamic",
                "doc_source_location": "zoom-lease-agreement.html",
                "tagging_type": "text_tagging",
                "tagging_data": [
                    {
                        "tag_name": "LesseeDate",
                        "field_type": "date_signed",
                        "is_required": "yes",
                        "anchor_text": "Date:",
                        "bounding_box": {
                            "x_offset": 30,
                            "y_offset": 0,
                            "width": 90,
                            "height": 12
                        }
                    },
                    {
                        "tag_name": "LessorDate",
                        "field_type": "date_signed",
                        "is_required": "yes",
                        "anchor_text": "As",
                        "bounding_box": {
                            "x_offset": 30,
                            "y_offset": 0,
                            "width": 90,
                            "height": 12
                        }
                    },
                    {
                        "tag_name": "Lessor",
                        "field_type": "signature",
                        "is_required": "yes",
                        "anchor_text": "LESSOR:",
                        "bounding_box": {
                            "x_offset": 150,
                            "y_offset": 6,
                            "width": 120,
                            "height": 24
                        },
                        "member_info_number": 1,
                        "date_signed_field_name": "LessorDate",
                        "date_signed_format": "MM/dd/yy"
                    },
                    {
                        "tag_name": "Lessee",
                        "field_type": "signature",
                        "is_required": "yes",
                        "anchor_text": "LESSEE:",
                        "bounding_box": {
                            "x_offset": 45,
                            "y_offset": 6,
                            "width": 120,
                            "height": 24
                        },
                        "member_info_number": 2,
                        "date_signed_field_name": "LesseeDate",
                        "date_signed_format": "MM/dd/yy"
                    }
                ]
            },
            {
                "ref_id": "ZoomJetPackSafetyAdvisory",
                "desc": "Zoom Jet Pack Safety Advisory",
                "file_name": "ZoomJetPackSafetyAdvisory.pdf",
                "mime_type": "application/pdf",
                "doc_source_type": "static",
                "doc_source_location": "zoom-safety-advisory.pdf",
                "tagging_type": "pdf_fields",
                "tagging_data": [
                    {
                        "tag_name": "SignatureField",
                        "field_type": "signature",
                        "member_info_number": 2,
                        "date_signed_field_name": "DateField",
                        "date_signed_format": "MM/dd/yy"
                    }
                ]
            }
        ]
    }

    return docs_data

Constructing the SubmitDocument Call

The sample application uses Python's ElementTree module to construct the XML for the SubmitDocument call. Here's a quick overview of the process:

1. The sx_request_init function builds the call from the bottom up.
2. It uses helper functions from sx_request_create_functions.py to create XML elements.
3. The XML structure is then serialized to a string:

xml_str = ET.tostring(transaction, encoding='utf-8', method='xml').decode()

Ready to see Text Tagging in Action?

Visit the GitHub repository to download or fork the sample project, review the code, and see how Text Tagging works in a simplified signature workflow:

https://github.com/kmsignix/zoom-jet-packs

To send transactions to SIGNiX, you’ll need a developer account. To request one or to learn more about SIGNiX and Text Tagging, complete the following form: