Bridge to a Docassemble interview

No description provided.

Proposed lightweight Docassemble → LITEFile handoff contract

The Docassemble interview should hand LITEFile everything it already knows about the filer, case, parties, and generated documents, together with semantic string hints about likely filing classifications. LITEFile should treat those hints as defaults, not authoritative e-filing metadata.

LITEFile owns resolution against the court's current filing types, document types, party types, filing components, optional services, and numeric codes, and may override a hint when live court metadata or a clerk correction requires it. Information already collected by the interview—including filer identity/contact information, court and docket information, party names/roles/addresses, relevant case facts, representation information, and generated documents—should prepopulate the LITEFile draft and should not be requested again unless missing, ambiguous, or being corrected.

A clerk correction should also stay attached to the same filer-visible matter. Internally LITEFile can preserve immutable submission attempts/revisions for audit purposes, but the filer should not have to understand an "archived case" or duplicate case record.

Docassemble side

Docassemble describes the legal filing and points to data it already has. It should not need to carry Tyler numeric codes.

litefile:
  schema_version: 1
  jurisdiction: massachusetts

  # Stable semantic intent owned by us, not Tyler.
  filing_intent: petition_to_seal_eviction_record

  # Suggestions only. LITEFile resolves these against current live choices.
  filing_type_name_hints:
    - Petition to Seal Eviction Record
    - Seal Eviction

  case_category_name_hints:
    - Summary Process

  case_type_name_hints:
    - Summary Process

  # Reuse information the interview already collected.
  case:
    existing_case: true
    docket_number:
      source: docket_number
    court_name:
      source: trial_court

  filer:
    source: users[0]
    include:
      - name
      - address
      - email
      - phone
      - is_form_filler

  parties:
    - source: users
      semantic_role: tenant
      case_side_hint: defendant
    - source: other_parties
      semantic_role: landlord
      case_side_hint: plaintiff

  documents:
    - source: petition_to_seal_eviction_attachment
      role: lead
      form_name: Petition to Seal Eviction Record

  # Optional additional facts LITEFile may need for filing, if the
  # interview already knows them. Do not ask the filer twice.
  known_filing_facts:
    representation:
      source: users[0].is_form_filler
    case_lookup:
      source: case_search_results

The important distinction is that values such as tenant, defendant, Summary Process, and Petition to Seal Eviction Record are semantic facts or hints. Values such as 1729 or 101805 should not be part of the interview contract.

LITEFile side

LITEFile owns the mapping from semantic intent/hints to the court's current metadata, plus validation, correction, fees, submission, and clerk-return handling.

handoff:
  accepted_schema_versions:
    - 1

  # These may arrive as hints from an interview, but LITEFile is authoritative.
  litefile_owned_metadata:
    - court_code
    - case_category_code
    - case_type_code
    - case_subtype_code
    - filing_type_code
    - document_type_code
    - filing_component_code
    - party_type_code
    - optional_services
    - payment_and_fee_metadata

  # Preserve the upstream suggestion and its provenance even if we override it.
  preserve_hint_provenance: true

filing_intents:
  petition_to_seal_eviction_record:
    filing_type_name_aliases:
      - Petition to Seal Eviction Record
      - Seal Eviction
      - Petition to Seal Eviction

    case_category_name_aliases:
      - Summary Process

    party_role_hints:
      tenant:
        likely_case_sides:
          - defendant
      landlord:
        likely_case_sides:
          - plaintiff

    documents:
      lead:
        form_name_aliases:
          - Petition to Seal Eviction Record

resolution:
  # Prefer explicit curated aliases; then compare with live court metadata.
  use_live_court_metadata: true
  numeric_codes_are_cacheable_not_authoritative: true

  on_unique_match: preselect
  on_multiple_matches: ask_user
  on_no_match: ask_user

corrections:
  clerk_return:
    create_revision_of_existing_filing: true
    preserve_case_parties_and_documents: true
    expose_only_fields_needing_correction: true
    keep_prior_submission_snapshot_immutable: true

Conceptually, the boundary is:

Docassemble owns the legal interview and generated documents; LITEFile owns the filing transaction.

That means a missing identifier becomes ordinary needs_input state in LITEFile rather than a Docassemble variable-resolution failure, and a wrong filing classification can be corrected against current court metadata without rerunning or recomputing the interview.

Follow-up: why this should be a lightweight adapter, not a Docassemble e-filing integration

I compared this proposed bridge against the current production-style integration in docassemble-MAPetitionToSealEviction and against LITEFile's current durable-draft / submission architecture. The main architectural benefit is sharper than just "reuse LITEFile UI":

The adapter should move the e-filing transaction out of Docassemble's variable-resolution graph.

The current MAPetition integration is a useful example of why. Its e-filing path has to force evaluation of a long list of filing-specific variables before submission (case category/type, filing parties, per-document filing component/type/attorney, fees, etc.). It also carries numeric defaults such as filing type 101805 and party type codes, and has a workaround setting filing_attorney = "" because that required value surfaced only in production in one case. See also SuffolkLITLab/docassemble-MAPetitionToSealEviction#199.

Those failures are disproportionately expensive in Docassemble: one field we did not realize was required can become an undefined-variable / dependency-order problem or require changing interview logic just to make the filing bundle complete. A lightweight bridge should instead allow a partial but durable filing draft to be created successfully.

Adapter responsibilities

Keep this layer deliberately small. It should:

Build a versioned handoff payload from facts/documents the interview already has.
Transfer or securely reference generated documents.
Authenticate the source application.
Supply a source id + idempotency key/document hashes so repeated handoff attempts do not create duplicate drafts.
Redirect the filer to the resulting LITEFile draft.

It should not grow methods for Tyler code lookup, filing-type resolution, party-type resolution, filing components, fee calculation, optional services, or final submission. If it does, we have recreated EFSPIntegration with an HTTP hop in the middle.

A successful handoff should mean "draft created", not "filing is valid." For example:

{
  "draft_id": "18427",
  "state": "needs_input",
  "issues": [
    {
      "code": "party_type_required",
      "path": "parties[0].party_type",
      "message": "Choose the party type required by this court."
    }
  ],
  "continue_url": "..."
}

That is the key usability difference: a missing identifier becomes ordinary editable draft state instead of a broken/interrupted interview.

LITEFile should be authoritative for mutable filing metadata

Docassemble remains authoritative for substantive legal answers and generated-document contents. LITEFile should be authoritative for the filing transaction and values that are court/EFSP metadata, including:

court/category/case-type codes
filing/document/component codes
party type codes
optional services
fee/payment metadata
envelope/submission ids and filing status
clerk-return/rejection metadata

Upstream numeric codes can be accepted only as hints. Preserve the semantic value and provenance, then resolve against current court metadata. A useful per-field model is roughly:

semantic value:  "Petition to Seal Eviction Record"
suggested code:   "101805"
suggested by:     Docassemble interview vX
resolved code:    <current live code>
resolved from:    Tyler metadata
resolved at:      <timestamp>
user confirmed:   true/false
clerk corrected:  true/false

This is especially important because numeric filing codes are an implementation detail that can differ across environments or change over time.

Correction / clerk-return lifecycle

The biggest improvement over tight Docassemble coupling should be repair without recomputing the legal interview.

If the court rejects a filing because the filing type, party type, document type, component, or other filing metadata is wrong, the desired flow is:

submitted filing / revision 1 (immutable)
        ↓ clerk rejection
correction draft / revision 2 (mutable)
        ↓ copy case + parties + documents
        ↓ mark only affected metadata as needing review
        ↓ resolve against live metadata
        ↓ revalidate / requote / review
resubmit

The filer should experience this as "Correct and resubmit" on the same matter, not as starting a new case or rerunning the Docassemble interview.

If the clerk instead requires a substantive document correction, LITEFile should send the filer back to the source interview (or another document-correction workflow), accept the replacement PDF into the same correction draft, and preserve the filing metadata already assembled in LITEFile.

LITEFile already has much of the right foundation here: durable FilingDraft state, partial updates that preserve omitted values, explicit edit-from-review paths, central payload validation, and submission states that distinguish confirmed rejection from ambiguous outcomes. The remaining product gap is a first-class submitted filing → clerk rejection → cloned correction draft workflow. Current user guidance still effectively has the filer correct the PDF and start a new filing.

Why this is better than tight Docassemble coupling

For the organizations choosing between the two approaches:

Tight Docassemble coupling	Lightweight LITEFile adapter
One application and one linear user journey	Two application surfaces / handoff
Can be fastest for one stable form in one court	Better when many interviews/courts share the same filing infrastructure
Filing requirements become interview variables/dependencies	Filing requirements become durable editable draft state
Missing metadata can break variable resolution or force interview changes	Missing metadata can be represented as `needs_input` and repaired later
Numeric code/default fixes often require interview releases	Live code resolution and corrections can be centralized in LITEFile
Clerk metadata corrections can force a restart/recompute	Clerk metadata corrections can edit/clone a filing revision
Easier deployment/auth topology	Requires source-app auth, handoff schema/versioning, PII/retention decisions, and a clean return/continuation UX
Good when substantive and filing branching are intrinsically inseparable	Good when legal-document generation and filing transaction can evolve independently

So I would use tight coupling when the integration is genuinely small/stable and the single-app experience matters more than repairability. I would prefer this adapter when we expect multiple guided interviews, changing court metadata, or clerk-return workflows.

Concrete acceptance criteria for #106

I think this issue is complete when we have at least:

The main design rule I would keep visible in this issue is:

Docassemble owns the legal interview and documents; LITEFile owns making the filing fileable, editable, correctable, and safely submittable.

Questions to answer:

What is the review stage here? Probably OK to just have a review of the codes at the end, not right at the handoff stage. Even for Illinois.
Handoff should just be high-level

Navigation Menu

Repository navigation

Bridge to a Docassemble interview #106

Proposed lightweight Docassemble → LITEFile handoff contract

Docassemble side

LITEFile side

Follow-up: why this should be a lightweight adapter, not a Docassemble e-filing integration

Adapter responsibilities

LITEFile should be authoritative for mutable filing metadata

Correction / clerk-return lifecycle

Why this is better than tight Docassemble coupling

Concrete acceptance criteria for #106

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Bridge to a Docassemble interview #106

Description

Activity

nonprofittechy commented on Sep 4, 2026

Proposed lightweight Docassemble → LITEFile handoff contract

Docassemble side

LITEFile side

nonprofittechy commented on Sep 4, 2026

Follow-up: why this should be a lightweight adapter, not a Docassemble e-filing integration

Adapter responsibilities

LITEFile should be authoritative for mutable filing metadata

Correction / clerk-return lifecycle

Why this is better than tight Docassemble coupling

Concrete acceptance criteria for #106

nonprofittechy commented on Sep 14, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions