Guided Documents

A Guided Document is an official, third-party-authored fillable PDF - an IRS form, a specific bank's mandated authorization form, a government compliance form - filled programmatically with data collected through a VaultWorkflow session. The participant answers your workflow's questions once; VaultWorkflow produces both your own branded VaultPDF document and the exact official form your recipient requires, from the same submission.

Why Guided Documents Exist

Some recipients don't accept a VaultPDF-branded document, no matter how complete the data is - they require their own form. The IRS requires Form W-9. Some banks require their own ACH/direct-deposit authorization PDF. Government agencies require their own compliance forms.

Historically this meant a second, disconnected step: export the collected data, re-key it into the official PDF by hand, and hope nothing was transcribed incorrectly. Guided Documents remove that step - the same fields your workflow already collected are mapped directly onto the official form's fields.

Two Ways to Generate a Guided Document

There are two distinct configuration points, and they behave differently. Using the wrong one for your use case will silently produce the wrong output.

Standalone - templateSettings.officialForm

Set on a .vpdf template's own templateSettings, this makes that entire render become the Guided Document fill - VaultWorkflow's normal pdfmake render is skipped entirely, and the filled official form is the only output of that render call.

{
  "templateSettings": {
    "officialForm": {
      "enabled": true,
      "formPath": "OfficialForms/w9.pdf",
      "formLibrary": "templates",
      "mappingPath": "mappings/w9-mapping.yaml",
      "mappingLibrary": "configurations",
      "rejectXfa": false
    }
  }
}

Auto-trigger - templateSettings.guidedDocuments

This is the shape used by real production workflows (see Vendor Onboarding). Set an array of Guided Document configs on the same .vpdf template that seals your normal branded PDF. Each entry is captured into the session's postSealActions at creation time, and every enabled entry is automatically filled from the same sealed workflow data - as an additional artifact, right after the main PDF is sealed. Your branded VaultPDF and every configured Guided Document are both produced from one submission.

{
  "templateSettings": {
    "workflow": {
      "enabled": true,
      "recipients": [{ "email": "vendor@example.com", "displayName": "Vendor Contact" }]
    },
    "guidedDocuments": [
      {
        "enabled": true,
        "formPath": "OfficialForms/w9.pdf",
        "formLibrary": "templates",
        "mappingPath": "mappings/w9-mapping.yaml",
        "mappingLibrary": "configurations",
        "rejectXfa": false,
        "outputName": "w9"
      }
    ]
  }
}

Each array entry accepts the same properties as the standalone shape, plus outputName (optional) - a short label used for the generated file's name; defaults to the form's own filename. A failure filling one entry is logged and does not block the others or the main seal.

Configuration Properties

Both shapes above share the same per-document properties:

Field Mapping

The mapping config is a YAML file that maps fieldKeys already collected by your workflow onto the official form's own field names. This example reflects the real, verified field structure of IRS Form W-9 - notably, its Line 3a federal tax classification is seven independent checkboxes, not a single radio group, so multiple mapping entries share one fieldKey with a single-entry valueMap each:

formId: w9
formVersion: "Rev. March 2024"

fields:
  - fieldKey: full_name
    targetField: "topmostSubform[0].Page1[0].f1_01[0]"
    targetType: text

  # Line 3a - seven independent checkboxes sharing one fieldKey. An unmatched
  # value means "not this box" - never a fallback to raw truthiness, which
  # would incorrectly check every box since the shared value is always non-empty.
  - fieldKey: entity_type
    targetField: "topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[0]"
    targetType: checkbox
    valueMap: { sole_proprietor: "checked" }

  - fieldKey: entity_type
    targetField: "topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[1]"
    targetType: checkbox
    valueMap: { c_corporation: "checked" }

  - fieldKey: entity_type
    targetField: "topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[5]"
    targetType: checkbox
    valueMap: { llc: "checked" }

  - fieldKey: tax.ssn_part1
    targetField: "topmostSubform[0].Page1[0].f1_11[0]"
    targetType: text

overflow:
  sourceArrayPath: line_items
  nativeRowLimit: 3
  crossReferenceMode: field
  crossReferenceField: remarks_field
  crossReferenceText: "See attached Continuation Schedule ({{count}} additional rows)"

Field Mapping Properties

Overflow

When a repeating data set exceeds the official form's native row capacity, the excess rows are rendered as a continuation schedule and attached after the filled form. The overflow block controls this:

Accessibility

Filled fields are marked read-only rather than flattened specifically to preserve whatever tab order and screen-reader semantics the original form already had - flattening a field into static content would strip that structure entirely.

Retrieving the Generated Document

A Guided Document produced via the auto-trigger shape is uploaded as its own file alongside the sealed workflow PDF - it is never merged into the sealed PDF's pages, and there is no separate email or notification for it.

To download it, open the item's Lifecycle Dialog from the SharePoint activity list and go to the Related Files tab. Each generated document appears as its own row, labeled Guided Document - <OUTPUTNAME> (matching whatever outputName was set on that entry, or the form's own filename if it wasn't), with a Download button that resolves a signed URL on click - the same mechanism used for the sealed PDF and the immutable audit archive.

Design Decisions

Electronic Evidence vs. Electronic Signature

Guided Documents are designed for governed business data collection, not PDF editing or signature capture. When a workflow is submitted, REFRACT Platform authenticates the submitter, validates business rules, applies approval routing, generates the official document (where configured), and writes an immutable audit record covering the full submission - the same governance spine every VaultWorkflow session already goes through.

Why not sign externally-generated PDFs? VaultESign within REFRACT Platform is intentionally scoped to documents REFRACT Platform itself generates. Signing works by re-rendering the signed document from its own template and data model, with the signature injected - a mechanism that depends on the original .vpdf template's structured layout. A third-party-authored PDF (an IRS form, a bank's own form) has no such template behind it; there is nothing for VaultESign to re-render. Keeping VaultESign scoped this way guarantees document integrity, cryptographic verification, complete lifecycle traceability, and consistent signature validation across every signed document the platform produces.

Official third-party PDF forms remain authoritative source documents in their own right. REFRACT Platform populates them but does not alter their native signature behavior. Where a signed copy of the official document is required, route the generated Guided Document through your organization's preferred electronic signature solution, or a physical/ink signing process, as a separate step after it's produced.

Guided Form Packs

REFRACT Platform ships one verified Guided Document today - IRS Form W-9, paired with the Vendor Onboarding workflow (see Vendor Onboarding). Every field mapping was built and confirmed against a real copy of the form, including a hybrid-XFA revision, using the field-extraction process described above.

Beyond W-9, the same pattern applies to any officially-mandated fillable form - a Guided Document Pack pairs a workflow's data collection with one or more official forms filled from that submission. The categories below illustrate where this pattern fits; they are not a pre-built catalog:

W-8BEN and W-4 are the recommended next two packs - both are, like W-9, primarily straightforward data-collection-and-fill forms with a similar shape and complexity to what's already built and verified. (I-9 is sometimes raised as an Employee Onboarding candidate too, but it involves employer-side physical identity-document inspection and attestation under penalty of perjury - materially more than a data fill, and not recommended as a "safe" next pack without separately scoping that process.)

Every Guided Document Pack shares the same underlying architecture, not a bespoke build per form: the same VaultWorkflow portal renders the data-collection steps from the pack's YAML schema (there is no per-pack custom UI), and the same officialFormRenderer fills whatever AcroForm PDF the pack's mapping targets.

Why are new packs delivered by REFRACT, not self-service? Building one requires real engineering work beyond declaring a mapping file: obtaining the actual current-revision PDF, extracting its true field names and structure (never guessed from the form's visual layout), authoring and validating the mapping against that real form, integrating the required workflow fields, and end-to-end testing against real submitted data. Skipping any of these steps produces a mapping that fails silently rather than loudly - a field just comes back blank. To keep new packs accurate and supportable, they're developed and validated by REFRACT rather than configured by customers directly.