Troubleshooting Docusign Integration

This guide outlines common issues users may encounter when using DocuSign within our platform, along with troubleshooting steps to help resolve them.

 

Invalid Signature Tag

An invalid signature tag prevents documents from being signed correctly, leading to workflow disruptions. With our recent error-handling updates, the system now detects invalid signature tags and prevents file uploads to a REPORT block when an issue is found. Users will see a prompt stating: "Invalid signature tag."

For existing apps (or those deployed before this update), identifying the issue can be more challenging since error handling only occurs during file upload. However, here are some indicators that the signature tag may be invalid:

• The signature field does not appear automatically when the recipient opens the document. (For example, the designated space for signature doesn’t appear, requiring manual placement of the signature field from the DocuSign menu).
• Recipient signatures do not appear on the final signed document.

 

Root Cause & Troubleshooting

The "Invalid signature tag" error occurs when one or more DocuSign tags are broken or split. This often happens because Word or other document editors insert XML tags when elements are copied and pasted from another source.

Since DocuSign relies on properly formatted tags, any break in the structure prevents it from recognizing the signature field.

 

How to Check for Broken DocuSign Tags

1. Open the affected document in Microsoft Word.
2. Go to File → Save As → and select Word XML Document to save the file as an .xml format.
3. Open the converted file and search for the DocuSign tag by typing "[[sign" in the search function.
4. Review the results to check if the tag is broken into multiple parts.

Below is an example of a working signature tag:

 

Meanwhile, here’s an example of a broken signature tag:

** As shown above, we can see that the tag is split into separate parts instead of appearing as a whole.

 

How to Fix Broken Tags

1. Open the document in Microsoft Word.
2. Delete and manually reinsert the DocuSign tags (avoid copying and pasting).
3. Save the document and upload the updated template to Checkbox.

If No Broken Tags Are Found

If the tags appear correct but the issue persists, the file may be corrupted. In this case, you may try the following steps:

1. Open Google Docs.
2. Click the Open file picker (envelope icon) and upload the template.
3. Once the document loads, go to File → Download as → Microsoft Word (.docx).
4. Upload the newly downloaded version to the required DOC GEN blocks.

How to Prevent Broken Tags

To prevent signature tags from breaking:

1. Type the entire tag in one go, rather than making edits mid-way.
   • Word automatically tracks changes and may insert hidden XML elements when edits are made.
   • For example, if you initially type [[signature1_doc1]] but correct a mistake mid-typing, Word may store hidden formatting data, causing DocuSign to misread the tag.
2. Avoid using the Checkbox Word Add-in to insert tags.
   • The add-in inserts tags in the format [[signature#_doc#]], which requires manual adjustments to match the recipient order.
   • Typing them manually ensures accuracy and avoids formatting conflicts.

• •  

•