Manually Mark Claim Batch as Sent

1. What does this feature do? (High-Level Overview)

This feature lets billing users close out a pending claim batch in the app when the EDI file has already been delivered to the clearing house outside the app (for example, uploaded manually through the clearing house portal). It keeps the batch status, the associated notes, and the audit log in sync without contacting the clearing house. This feature is currently available.

2. Who is this for? (Roles & Permissions)

• Users with manage_claims (Manager, Owner): Can mark a downloaded, pending batch as sent and optionally record a reason. The reason is shown in the batch tooltip and stored in the audit log.

3. Business Rules & Enforcements

• Rule 1: Only batches with status pending can be marked as sent manually. A descriptive validation error is returned for any other status.
• Rule 2: The batch must have been downloaded first. The system requires both a downloaded_at timestamp and a persisted clearing house on the batch before the action can run.
• Rule 3: The clearing house persisted on the batch must still be active for that location at the moment of the action; otherwise the request is rejected.
• Rule 4: A reason is optional. If provided, it must be between 5 and 1000 characters. If left empty, the system stores the default reason Sent manually to CH.
• Rule 5: When the action succeeds, the system updates the batch in a single transaction: status becomes sent, the submission timestamp and submitting user are recorded, sent_manually is flagged true, and the reason is saved.
• Rule 6: The clearing house provider is propagated to every child claim in the batch, mirroring the automated submission flow.
• Rule 7: All linked RBT and BCBA notes are marked as billed so they are excluded from future batch generation.
• Rule 8: A dedicated audit log entry is written under the claim_batches log with the submitter name and the reason, surfaced in the System Audit Logs view without breaking the standard event=updated filter.

4. UI Placement

1. Reports > Billing Collections > Batches: Entry point to the claim batches list.
2. Claim batches list (/claims): Each row in the actions column shows an orange wrench button next to the send button. The wrench is only visible when the batch is pending and has been downloaded.
3. Status column tooltips: A blue info icon next to the pending status reminds users to download the batch first to unlock the action. A second blue info icon next to a sent status shows who marked the batch manually and the reason captured.

5. How-To Guide (Step-by-Step)

Scenario A: Mark a downloaded pending batch as sent

1. Open Reports > Billing Collections > Batches.
2. Locate the target batch. It must show status pending and you must have already downloaded its EDI file.
3. Click the orange wrench button in the actions column.
4. Read the confirmation dialog. Optionally enter a short reason explaining why the batch is being closed manually (minimum 5 characters if you decide to type something).
5. Click Yes, mark as sent.
6. On success, the batch status moves to sent, the row updates, and a “Sent manually” tooltip becomes available next to the new status.

Scenario B: Review which batches were closed manually

1. Open Reports > Billing Collections > Batches.
2. Filter the list by the sent_manually parameter to isolate batches that were closed through this action.
3. Hover the blue info icon next to the sent status to see who performed the action and the reason that was recorded.
4. Cross-check the entry in the System Audit Logs view to see the full activity log, including the submitter name and the reason.

6. What happens if…? (Edge Cases / FAQ)

• Q: What happens if I try to mark a batch that has not been downloaded yet?
  • A: The action is blocked. The wrench button is hidden in the UI, and the API returns a validation error stating the batch must be downloaded before it can be marked as sent. Downloading the batch first persists the clearing house selection that the action requires.
• Q: What happens if the clearing house used at download time was later deactivated?
  • A: The action is blocked with a validation error. Reactivate the clearing house for that location, or re-download the batch against a currently active clearing house, before retrying.
• Q: Are the notes inside the batch affected?
  • A: Yes. All RBT and BCBA notes linked to the batch are marked as billed, exactly as they would be after a successful automated submission. They will not appear in future claim generation pickers.