Frequently Asked Questions

1. Flow of the file

Q. How does a case flow through VCPMS — from receiving and entering an application, through sending out information requests (wage documents, medical records), determining eligibility, making payments, and handling appeals?

A. Each claim is a WorkItem with a state machine that drives the end-to-end workflow. The file never leaves a single tracked record — stages are just state transitions on the same VcClaim (or FrClaim) entity. Every transition writes an audit entry and can fire notifications, document generation, and background jobs, all configured declaratively per tenant.

Stage	What happens	WorkItem mechanic
Receive	Victim applies via VCPOnline, advocate applies via VCPAdvocate, or staff creates from paper (manual + bulk intake). File is OCR'd, classified, and attached.	VcClaim created in state Draft → ApplicationIntake.
Enter / Intake	Auto-assigned to Claim Processor via org-unit routing rule. Required fields validated.	State transition triggers assignment + notification rules on WorkItemManagerConfig.
Information requests	System generates outgoing documents (OutDocument): wage request letter, medical records request, LE report request. Each is sent by SMTP (or Outlook, if configured), tracked in the same claim thread, and reopened when a response is received (incoming → InDocument linked to parent).	Document-generation rules fire on state change. Each request is its own linked WorkItem; overdue requests trigger SLA reminders.
Eligibility	Claim enters AwardInProcess → processor reviews packet → decision. Eligibility checks run against configurable rule sets (no code changes).	EligibilityCheckConfig + ValidationRule.
Award	Approved claim creates an immutable Award snapshot + AwardItem breakdown (medical, funeral, lost wages, etc.).	Award is not a WorkItem — it's the frozen decision record. Approval workflow lives on VcClaim.
Payment	Payment → PaymentItem → optional PaymentBatch. Batch goes through approval, then issuance.	Separate state machine on Payment (PendingPayment → Paid).
Appeal	If denied/reduced, VcClaimAppeal is a child WorkItem with its own state machine, linked to the original claim for audit.	Appeal outcome can reopen the parent claim or create an amended Award.

2. Digital "packets" — board review and payment determination

Q. Can staff assemble "packets" of digital files? For example: (1) a board-review packet with a clear set of only the necessary documents in one place (staff memo, LE report, email communication from prosecutor), without hunting through the system; and (2) a payment-determination packet with wage form, tax return, disability statement, medical records?

A. VCPMS treats a packet as a view over documents, not a physical bundle — so nothing is duplicated and the packet updates live as new docs arrive. Two packet mechanisms exist today; the new bulk-intake classification makes packet assembly dramatically faster because every document is already tagged with its type and category.

Board review packet — DeterminationDocket WorkItem

• Staff queue a claim for the board → add it to an open DeterminationDocket item.
• Agenda auto-aggregates: staff memo, LE / police reports (InDocumentType = PoliceReport), email communications (SecureMail threads), prior denial / appeal decisions, relevant expense bills.
• On agenda date, board members open one URL → they see the curated packet with every linked document side-by-side, no navigation required. Decisions recorded back onto the claim.
• Reviewers can add / remove individual docs from the packet without affecting the claim itself.

Payment determination packet — the Payment workspace

• When a processor prepares a payment, the UI assembles: wage forms (WageStatement), medical records (MedicalRecords), disability statements (DisabilityStatement), tax returns (TaxReturn), the related ExpenseBill / IncomeLoss sub-items, and the originating claim summary.
• Docs pull from the existing InDocument classifications — which is exactly why the new Document Classification feature matters: once a doc is tagged, it automatically flows into every future payment packet for that victim.
• Nothing is copied. If a wage form is updated, the packet reflects it immediately.

Ad-hoc packets — one-off merges

For one-off reviews ("send this package to the AG"), any WorkItem can be exported to a single consolidated PDF via the OutDocument template system. Choose a template, select which linked docs to include, the system merges them with a cover sheet.

3. Managing documents within the system

Q. How does VCPMS manage documents within the system (wage forms, medical records, etc.)?

A. Every document is an InDocument (incoming) or OutDocument (generated) — both are WorkItems, both have state machines, both get assigned and tracked exactly like a claim.

Ingestion paths

• Portal upload (victim, advocate, agency) → direct to a specific claim
• Staff intake (mail / fax) → single-file or bulk packet
• Scanner feed (adapter interface shipped; specific integrations phased in)
• Email attachments (future)

Classification & organization

• Two-level: InDocumentType (WageStatement, MedicalRecord, PoliceReport, FuneralBill, …) × InDocumentCategory (narrows within type)
• AI-classified + reviewer-correctable (see Document Classification)
• Routing rules determine which WorkItem a document gets linked to — processors rarely have to manually file
• Search by classification, date, source, OCR text content, or claim number

Actions on a document

• Split — multi-page scan that's really 3 docs → 3 separate records
• Merge — two uploads that should be one
• Reclassify — override AI
• Replace — new version while preserving history
• Approve / Reject — for documents landing in review queue
• Archive — retention policy applied per tenant

Storage

• Raw files: Azure Blob (encrypted at rest)
• Metadata + OCR text: SQL Server
• PII redactions per data-exchange rules — external portals see redacted previews; only authorized staff roles see originals

Outgoing documents (OutDocument)

• Generated from templates (DocumentTemplate) with token merge — claim number, victim name, addresses, dates
• Sent via SMTP, optionally via Outlook (calendar events, Adaptive Card actions — see the Outlook Integration guide)
• Tracked: which template, which recipient, when sent, bounce / delivery status

4. Work queue management & notifications

Q. How does each staff member get notified of tasks requiring their attention — new applications being submitted, documents that were uploaded, etc.?

A. Every staff member has a My Queue — an auto-maintained filtered view of WorkItems currently assigned to them, sorted by urgency. Assignment happens three ways, and every transition triggers notifications through a single configurable system.

How work lands in a queue

1. Automatic (rule-based) — state transitions trigger StateAssignmentRules on WorkItemManagerConfig. Example: "when a VcClaim enters ApplicationIntake, assign to any available Claim Processor I in org unit Oklahoma North."
2. Escalation — SLA timers fire when a WorkItem sits too long in a state. Reassigns up the org-unit chain (processor → supervisor → director) with notifications.
3. Manual — a processor can reassign to a teammate; all handoffs are audited.

How staff get notified

Four parallel channels, each optional and configured on WorkItemManagerConfig.NotificationRules:

Channel	When	Controlled by
In-app (bell icon)	Real-time via SignalR. New assignment, document uploaded, message received, state change on a watched claim.	User notification preferences.
Email	Digest or immediate. Can embed one-click action links.	SMTP (default) or Outlook Graph.
Outlook calendar	Deadlines, hearing dates, payment due dates as calendar events with deep-link back to the claim.	Optional Outlook Integration feature flag.
Outlook inbox (Adaptive Cards)	Approve / Reject buttons directly inside email — staff can act without leaving their inbox.	Optional, same Outlook feature.

What triggers notifications

Each WorkItem type declares its own notification events:

• VcClaim — ApplicationSubmitted, StatusChanged, AssignedToUser, DocumentUploaded, PotentialDuplicate, NewMessage, ClosedDueToInactivity, AccessRequestApproved, …
• InDocument — Received, Processed, AttachedToClaimByStaff
• Payment — Requested, Approved, Processed, Rejected
• FrClaim — Submitted, StatusChanged
• ExpenseBill, TreatmentPlan, IncomeLoss — Received, StatusChanged

Admins add / remove notification rules per tenant via the UI — no code deploys.

Queue views for staff

• My Queue — flat, personal, all WorkItem types
• Department Queue — everything in the processor's org unit
• Docket Dashboard — filtered views by state, due date, type
• Bulk Intake → My Review Queue — dedicated queue for docs flagged Review Required by the AI pipeline
• Board Queue — pending board-review claims

What it looks like operationally

A brand-new application comes in → VcClaim auto-assigned to a Claim Processor → they get in-app + email notifications instantly → the claim appears at top of their My Queue → as they request wage / medical records, each outgoing OutDocument + incoming response are linked to the same claim and show as sub-tasks in their queue → when documents are sufficient, they move the claim to next state → assignment rule routes it to the next role automatically, with notifications firing again.

Zero manual "handing off" — the state machine + rules do the routing, and the notification system makes sure nobody misses anything in their lane.

5. Finding bills not for the assigned case (erroneous-bill detection)

Q. Is there a way to find bills not for the assigned case? Example: a large bulk of medical bills submitted electronically — most are for the victim, but some are for other patients. Can VCPMS identify erroneous bills?

A. Yes, in three layers — and the bulk-intake pipeline is designed exactly for this. The key principle: the AI does not trust the submitter's declared claim. It extracts patient identifiers from the document itself and cross-checks against the database.

Layer 1 — Automatic detection at routing time

When the pipeline processes each bill, the Route stage compares extracted identifier fields (victim name, DOB, SSN last-4, claim number) against the bill's intended target WorkItem — the VcClaim the submitter linked it to.

Scenario	Automatic behavior
Extracted victim matches claim (above threshold, unique)	Auto-linked → Processed.
Extracted victim mismatches claim	Flagged with RequiresReviewReason = AmbiguousCandidates. Bill lands in the reviewer's Review Queue with the real candidate the lookup suggests. Reviewer sees: "submitted against VC-260042, but extracted victim name matches VC-260817."
No candidate matches anywhere	RequiresReviewReason = NoCandidate. Reviewer manually links, auto-creates a draft, or rejects — depending on the rule's NoMatchBehavior.

Layer 2 — Explicit mismatch reports

For a bulk submission (say, 200 bills from a hospital billing system), the workspace shows:

• Mismatch summary at the set header: "185 auto-linked, 12 review required, 3 rejected."
• Filter: "Show only review-required" → reviewer sees just the exceptions.
• Each flagged bill shows which field mismatched: "Expected victim Smith, Jane — extracted Johnson, Mary."
• Reviewer can bulk-approve the correct ones and mass-reject the erroneous ones.

Layer 3 — Cross-claim duplicate / mismatch search

Even for bills already processed, staff can search:

• InDocument list filter: victimNameOnBill != victimNameOnClaim.
• Claim-level duplicate detection: VCPMS already flags VcClaimPotentialDuplicateIdentified when two claims share SSN/DOB/name — the same lookup infrastructure powers bill-mismatch search.
• Ad-hoc search: "Find all bills attached to VC-260042 where the extracted patient name doesn't match the claim's victim."

Practical workflow for the example

1. Hospital uploads 500 bills electronically, all tagged to VcClaim VC-260042 (victim Smith).
2. Pipeline processes each bill. For each, it extracts patient name, DOB, service date.
3. Bills where extracted patient = Smith with matching DOB → auto-linked (majority).
4. Bills where extracted patient ≠ Smith → flagged with AmbiguousCandidates + the lookup's actual best-match claim (if any).
5. Processor opens the batch workspace → filters "Review Required" → sees 7 mis-assigned bills → one-click "move to VC-260817" (the real match) or reject as "wrong victim."

Short answer: yes, and the system is designed to assume the submitter may be wrong. Extraction + lookup + threshold-based auto-link is exactly the mechanism that catches erroneous bills in a bulk submission.

6. Duplicate incoming document detection

Q. A provider uploads the same bill twice, or a victim re-submits a document they already sent. Does VCPMS catch duplicates, and what happens?

A. Yes, on three keys:

• Byte-level hash — every uploaded file is SHA-256 hashed; an exact re-upload is flagged "identical file already attached" before it ever hits the pipeline.
• Extracted-field match — after OCR, if a new ExpenseBill has the same victim + service date + amount + provider TIN as an existing one on the same claim, it raises PotentialDuplicateIdentified. The bill still saves (reviewer may decide it's a legitimate corrected copy) but the UI shows a duplicate-warning chip.
• Cross-claim scan — the same file-hash check runs tenant-wide, so if a doc is uploaded to VC-260042 and then again to VC-260817, both sides get a cross-link suggestion.

Reviewers can merge the two InDocument records (keeps audit trail), mark the duplicate as superseding (archives the old version), or reject the newer one.

7. Linking one document to multiple claims / WorkItems

Q. A police report covers an incident with multiple victims; an LE report mentions several offenders. Can one InDocument be attached to multiple claims?

A. Yes. An InDocument has a primary owner (the claim or WorkItem it was first linked to) and a many-to-many relationship for cross-links.

• Primary owner is tracked in OwnedByEzEntityTypeName / OwnedByEzEntityShortName — used for the default "where does this document live" view.
• Additional claims / WorkItems are attached via the InDocumentCrossLink table, each with a reason code (SharedIncident, JointOffender, MutualVictim, SourceDocument).
• Cross-linked documents show up in all linked claims' workspaces, but edits / classification changes propagate to every view. The underlying binary is stored once.
• Access control respects the most restrictive linked claim — if a user can see any one of the linked claims, they see the doc.

Common uses: an incident police report spanning three sibling victims' claims; a court order naming multiple offenders; a consolidated medical-records release covering a parent + minor child.

8. Searching document content (OCR full-text search)

Q. Can staff search by text that appears inside a document? Example: find every claim with a document mentioning a specific prescription drug, or every bill from a specific provider name.

A. Yes, via the OCR text stored alongside every InDocument.

• When OCR runs (Azure DI AnalyzeDocumentAsync), the full extracted text is saved to the InDocument.OcrText column and indexed for full-text search.
• The Document Intake list supports a Content filter: substring, prefix, or phrase search. Matches highlight the hit in the preview.
• Cross-entity search: the global search bar searches OCR text too, so typing a drug name returns matching documents even if they're attached to different claims.
• Privacy note: OCR text is PII — access checks apply the same way as the binary file. External-client roles (VCA, Provider, etc.) only see OCR text for documents they're authorized to view.

9. Supported file formats, size limits, encryption

Q. What files can be uploaded, how big, and how secure is the storage?

Aspect	Detail
Formats	PDF, TIFF, PNG, JPG, DOCX, XLSX, plus plaintext / CSV for structured imports. Multi-page PDFs are auto-split by the pipeline if a separator page or AI boundary is detected.
Max file size	Tenant-configurable. Default 50 MB per file, 500 MB per bulk-upload batch. Large scans are chunk-uploaded with resumable sessions.
ZIP archives	Supported for bulk intake. Server-side extracts individual files and preserves filenames. Nested ZIPs not supported.
Encryption at rest	All binaries stored in Azure Blob with SSE-AES-256. Database columns (OCR text, metadata) protected by Azure SQL TDE.
Encryption in transit	TLS 1.2+ for all client ↔ server transfers. SAS tokens with short TTL for blob downloads.
PII redaction	Extracted SSN / DOB / account numbers can be masked in preview per tenant policy. Original doc is retained unredacted for authorized roles only.
Virus scan	All uploads pass through an antivirus scan before entering the pipeline; infected files quarantine automatically with a Rejected state and audit record.

10. Document retention and archival after a claim closes

Q. What happens to documents after a claim is closed or denied? How long are they kept, and can they still be retrieved?

A. Retention is configured per tenant to match each state's record-retention law (typically 7–10 years for compensation programs).

• Active phase — while the claim is open, all docs are hot-storage in Azure Blob, immediately previewable.
• Closed — when the parent VcClaim hits a terminal state (Closed, Denied, Withdrawn), documents remain accessible but can be moved to cool-tier blob storage after a tenant-configured grace period (default 90 days) to cut cost. Access is unchanged from the user's perspective — preview just takes a second longer on cold-cache.
• Archive (cold) — after N years (tenant-configured), documents move to archive-tier blob. Staff can still request retrieval; rehydration is async (minutes to hours) with notification on completion.
• Purge — at the end of the legal retention window, documents are deleted; the InDocument metadata row is retained as a tombstone with Purged = true and the deletion date, so the audit trail remains intact even after the binary is gone.

Tenant admins set retention policies via the Admin Guide → Document Retention Policy screen. Policies can differ per document type (e.g., tax returns 7 years, ID documents 3 years after closure).

For claims whose payments draw from SourceFund entities, retention windows are also driven by the fund's FundingSourceType:

• Federal-only funded (e.g., VOCA grant only) — 3 years after last payment.
• Any State-funded (state GF, court fees/fines, mixed federal+state) — 5 years after last payment.

The longer of the two windows (tenant retention policy vs. funding-source retention) applies.

11. Reprocessing a document after rule changes or misclassification

Q. An admin updates a routing rule, or a reviewer realizes the AI misclassified a batch of documents. How do I re-run the pipeline without re-uploading?

A. The orchestrator supports re-entry at any stage, per-document or per-set, without re-uploading the binary.

Per-document reprocess

• Open the document in the batch workspace → click Reprocess.
• Choose a starting stage: Classify / Extract / Route (Split and OCR rarely need rerun; their output is cached).
• Optionally: "Clear prior routing result" for a clean re-run, or "Keep as history" to append the new attempt.
• Prior RoutingResultJson snapshots into an append-only history array — you can always see what the AI said last time vs this time.
• RoutingAttemptCount increments so metrics distinguish one-shot matches from re-run corrections.

Per-set reprocess

• Open the set → Reprocess Set → choose starting stage + whether to include already-Processed docs.
• Useful after an admin updates routing rules or thresholds: re-run the whole batch and see how many more docs auto-link.

Bulk reprocess from the list

• In the Batches or Document Intake list, multi-select rows → Reprocess Selected.
• Or run a saved query (e.g., "all ExpenseBills with ConfigNotFound in the last 30 days") and reprocess the result set after fixing the underlying rule.