> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payer Portal Automation (RPA) — Integration Documentation

> Created: 2026-04-07 Status: \U0001F4DD Planned

**Spec:** PM-51
**Created:** 2026-04-07
**Status:** 📝 Planned

***

## Overview

PM-51 provides browser-based RPA (Robotic Process Automation) for payer portal interactions: claim status checks, remittance/EOB downloads, and eligibility verification for payers without EDI support. It operates as an automation layer that extends PM-08, PM-02, and PM-09 with portal-sourced data.

***

## Platform Foundation Dependencies

| Dependency                       | Integration Type           | Description                                                                                                                |
| -------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| PF-01 (Organizations & Sites)    | Direct dependency          | Organization context for multi-tenant bot configurations                                                                   |
| PF-02 (RBAC)                     | Direct dependency          | Permission checks for RPA admin role (9 permission keys)                                                                   |
| PF-10 (Notifications)            | Platform Integration Layer | Alert notifications on consecutive bot failures (`pm.rpa.consecutive_failures`)                                            |
| PF-11 (Documents)                | Platform Integration Layer | Storage for downloaded remittance documents and error screenshots                                                          |
| PF-75 (Credential Vault)         | Direct dependency (DB FK)  | Encrypted portal credential storage via `pf_credential_vault` + `vault.secrets`; decryption via `pf_retrieve_credential()` |
| FW-46 (Durable Execution Worker) | Platform Integration Layer | Long-running bot execution (5–15 min) exceeds Edge Function 60s limit; RPA jobs enqueued to FW-46 worker                   |

***

## Event Contracts

### Published Events

**1. `pm.rpa.execution_completed`**

* **Publisher:** PM (RPA — durable worker job `rpa-execute-bot`)
* **Subscribers:** PM-08 (claim status refresh), PM-09 (staged documents available)
* **Payload:**
  ```typescript theme={null}
  {
    execution_id: string;
    bot_configuration_id: string;
    bot_type: 'claim_status' | 'remittance_download' | 'eligibility_check';
    status: 'success' | 'partial' | 'failed';
    records_updated: number;
    records_failed: number;
    organization_id: string;
  }
  ```
* **Status:** 📝 Planned

**2. `pm.rpa.consecutive_failures`**

* **Publisher:** PM (RPA — `rpa-failure-alerter` Edge Function)
* **Subscribers:** PF-10 (Notifications)
* **Payload:**
  ```typescript theme={null}
  {
    bot_configuration_id: string;
    bot_name: string;
    payer_name: string;
    consecutive_failure_count: number;
    last_error_summary: string;
    organization_id: string;
  }
  ```
* **Status:** 📝 Planned

***

## Same-Core Dependencies (PM Internal)

| Spec                             | Relationship                                                                         | Detail                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| PM-08 (Claims Management)        | **Extends** — PM-51 updates `pm_claims` status fields with `source = 'rpa_portal'`   | Direct table write (same core); PM-08 owns claim lifecycle               |
| PM-02 (Eligibility Verification) | **Extends** — PM-51 populates eligibility data for non-EDI payers into PM-02 records | PM-02 owns `pm_eligibility_checks`; PM-51 feeds portal-sourced responses |
| PM-09 (Payment Posting)          | **Extends** — PM-51 stages downloaded remittance documents for PM-09 processing      | `pm_rpa_staged_documents` queue → PM-09 posting workflow                 |
| PM-43 (Payer Contract Modeling)  | **Delegates** — PM-51 may reference contract rates (read-only)                       | No writes to PM-43 tables                                                |
| PM-44 (ERA Reconciliation)       | **Complements** — PM-51 provides non-ERA remittance as alternative data source       | PM-44 stays ERA-centric; PM-51 covers portal-scraped remittances         |

***

## Edge Functions

| Function                 | Trigger             | Description                                                              |
| ------------------------ | ------------------- | ------------------------------------------------------------------------ |
| `rpa-schedule-runner`    | Cron (configurable) | Finds active bots due for execution; enqueues jobs to FW-46              |
| `rpa-failure-alerter`    | Cron                | Checks consecutive failures against threshold; sends PF-10 notifications |
| `rpa-screenshot-cleanup` | Daily cron          | Deletes error screenshots older than 30 days                             |
| `rpa-execution-archiver` | Daily cron          | Aggregates 30+ day executions into daily summaries                       |

**Durable Worker Job:** `rpa-execute-bot` (FW-46) — Headless browser execution with PF-75 credential decryption, navigation engine, data extraction.

***

## Security Considerations

* Portal credentials decrypted only at bot execution time via `pf_retrieve_credential()` SECURITY DEFINER function
* Execution logs contain claim/member identifiers only — no clinical PHI
* Error screenshots stored with RLS and auto-purged after 30 days
* Legal/compliance review required per payer before production deployment (ToS compliance)

***

## Contract Validation

* [ ] Event payloads match schema (pm.rpa.execution\_completed, pm.rpa.consecutive\_failures)
* [ ] PF-75 credential vault FK and decryption pattern validated
* [ ] FW-46 durable worker job interface confirmed
* [ ] PF-10 notification delivery verified
* [ ] PM-08 claim status update with `source = 'rpa_portal'` attribution