Troubleshoot QCDS Builder Validation and Field-Placement Problems

Common validation blockers, missing assignments, invalid Dropdown configuration, document readiness issues, geometry/placement mistakes, and how to isolate a Template-specific problem with a simpler test PDF.

This guide applies to All plans; sender and follows the accepted QC Digital Signature 2.0.7 implementation. Where older walkthrough language differs from the current interface or source behavior, use the current QCDS state as the authority.

Before You Begin

  • Start with a clean PDF. QCDS current Template intake is PDF-only; convert DOC/DOCX or other source formats to PDF before upload.
  • Choose a stable document layout before placing fields because field coordinates are tied to the PDF page geometry.
  • Use a simple test PDF first when diagnosing rendering or placement so document complexity is not confused with a builder problem.

Step-by-Step Workflow

  1. Reproduce the issue once, if safe, and record the exact QCDS screen/action and visible message or reference.
  2. Check the current QCDS Status page and the owning object (workspace, Template, Request, signer, delivery, or completed artifact) before changing unrelated settings.
  3. Use the narrow test appropriate to the symptom: Joomla mail test, simple PDF, test Contact, provider Test Connection, Scheduled Task health, or entitlement refresh.
  4. Correct only the failing layer and retry the supported action.
  5. Verify the original transaction/evidence remains intact and gather safe non-secret diagnostics if support is still required.

Common validation blockers

A Template is reusable document preparation. It stores the protected PDF source, field layout, assignments/properties, and published version used to start future Requests. Editing and publishing a later Template version does not rewrite Requests that were already sent. The Use action should be treated as the handoff from reusable preparation into one transaction-specific Request.

For Troubleshoot QCDS Builder Validation and Field-Placement Problems, verify this behavior using the actual object involved rather than a generic assumption. A global administrator setting, a sender-workspace preference, a reusable Template, and a sent Request have different ownership and history rules. QCDS is intentionally designed so changes for future work do not silently rewrite the evidence of an already-sent transaction.

Missing assignments

A Template is reusable document preparation. It stores the protected PDF source, field layout, assignments/properties, and published version used to start future Requests. Editing and publishing a later Template version does not rewrite Requests that were already sent. The Use action should be treated as the handoff from reusable preparation into one transaction-specific Request.

For Troubleshoot QCDS Builder Validation and Field-Placement Problems, verify this behavior using the actual object involved rather than a generic assumption. A global administrator setting, a sender-workspace preference, a reusable Template, and a sent Request have different ownership and history rules. QCDS is intentionally designed so changes for future work do not silently rewrite the evidence of an already-sent transaction.

Invalid Dropdown configuration

A Template is reusable document preparation. It stores the protected PDF source, field layout, assignments/properties, and published version used to start future Requests. Editing and publishing a later Template version does not rewrite Requests that were already sent. The Use action should be treated as the handoff from reusable preparation into one transaction-specific Request.

Document readiness issues

A Template is reusable document preparation. It stores the protected PDF source, field layout, assignments/properties, and published version used to start future Requests. Editing and publishing a later Template version does not rewrite Requests that were already sent. The Use action should be treated as the handoff from reusable preparation into one transaction-specific Request.

Geometry/placement mistakes

A Template is reusable document preparation. It stores the protected PDF source, field layout, assignments/properties, and published version used to start future Requests. Editing and publishing a later Template version does not rewrite Requests that were already sent. The Use action should be treated as the handoff from reusable preparation into one transaction-specific Request.

How This Fits into the QCDS Workflow

A Template is reusable preparation, not a live signature transaction. QCDS versions published Template work so future Requests can use a new layout while older sent Requests remain based on their frozen snapshot.

Use Template versioning as the safety boundary: improve future preparation without altering the immutable snapshot already attached to an older Request.

Verify the Result

  • The Template validates and a new test Request renders the expected field/content behavior without changing older Requests.
  • The Completed PDF/Package opens, preserves the signed source and evidence, and the Audit Trail remains readable.
  • A direct follow-up test confirms the change affects future/current workflow behavior without rewriting historical sent Request evidence.

Common Mistakes to Avoid

  • Publishing before running Validate and resolving actual configuration problems.
  • Assuming a later Template edit will update a Request that was already sent.
  • Asking signers to sign again when only final PDF generation or completion delivery failed.
  • Replacing a prior valid artifact before a regeneration attempt has been verified.

Troubleshooting

  • If the PDF preview or completed artifact fails, reproduce with a small known-good PDF and check QCDS Status/Scheduled Task health before changing field data.

Operational Best Practice

Test meaningful changes with controlled data before relying on them in production. Keep QCDS, Joomla mail, Scheduled Tasks, and entitlement health observable; preserve successful Requests and completed evidence; and make the smallest change that solves the actual problem. For handoff or support, record the QCDS version, relevant Request/Template reference, the exact action taken, and the visible result without including secrets.

Community Discussion

Want to compare workflows, share practical tips, or discuss how you use this QCDS feature? Visit the QC Digital Signature Community. For private support, bug reports, account-specific issues, or feature requests, use the QuantaCade support system.