Integration Documentation: PM-49 — Revenue Cycle Automation Rules Engine

​

Overview

​

Platform Foundation Dependencies

​

Internal PM Dependencies

​

API Contracts

​

PM-49 → PM-09 (Payment Posting)

{
  organization_id: string;      // UUID
  claim_id: string;             // UUID
  adjustment_code: string;      // e.g., "SB-WRITEOFF", "CONTR-ADJ"
  adjustment_amount: number;    // Decimal
  reason_text: string;          // Human-readable reason
  rule_execution_id?: string;   // UUID (for audit trail)
}

{
  success: boolean;
  adjustment_id?: string;       // UUID if success
  error_code?: string;          // e.g., "CLAIM_NOT_FOUND", "INSUFFICIENT_BALANCE"
  error_message?: string;
}

• CLAIM_NOT_FOUND: Claim ID does not exist
• INSUFFICIENT_BALANCE: Balance lower than adjustment amount
• INVALID_ADJUSTMENT_CODE: Unrecognized code
• ORG_MISMATCH: Claim does not belong to organization

​

PM-49 → PM-29 (Denial Management)

{
  organization_id: string;      // UUID
  denial_id: string;            // UUID
  resubmission_reason: string;  // e.g., "auto-resubmit CO-4 modifier"
  correction_notes?: string;    // Optional correction instructions
  rule_execution_id?: string;   // UUID (for audit trail)
}

{
  success: boolean;
  resubmission_id?: string;     // UUID if success
  error_code?: string;          // e.g., "DENIAL_NOT_FOUND", "FILING_DEADLINE_PASSED"
  error_message?: string;
}

• DENIAL_NOT_FOUND: Denial ID does not exist
• FILING_DEADLINE_PASSED: Resubmission past filing deadline (resolved via PF-96)
• ALREADY_RESUBMITTED: Denial already has pending resubmission
• ORG_MISMATCH: Denial does not belong to organization

​

PM-49 → PM-45 (Collections)

{
  organization_id: string;      // UUID
  account_id: string;           // UUID or claim_id
  collections_tier: string;     // e.g., "early", "standard", "final"
  transfer_reason: string;      // Human-readable reason
  rule_execution_id?: string;   // UUID (for audit trail)
}

{
  success: boolean;
  collections_entry_id?: string; // UUID if success
  error_code?: string;           // e.g., "ACCOUNT_NOT_FOUND", "ALREADY_IN_COLLECTIONS"
  error_message?: string;
}

• ACCOUNT_NOT_FOUND: Account/claim ID does not exist
• ALREADY_IN_COLLECTIONS: Account already assigned to collections tier
• INELIGIBLE_PAYER: Payer type excluded from collections (e.g., Medicaid in some states)
• ORG_MISMATCH: Account does not belong to organization

​

Event Contracts

​

Events Consumed

​

Events Published

​

Scheduled Processing

1. Fixed hourly cron: 0 * * * * — runs every hour
2. Dispatcher logic:
   • For each organization, resolve effective timezone (site timezone if available, otherwise org default)
   • Calculate current local time in that timezone
   • If local time matches target hour (02:00 for rules, 03:00 for scoring), enqueue/execute for that organization
   • Skip organizations already processed in current day window
3. Job targets:
   • pm-rcm-rule-batch invokes rcm-execute-rules with organization_id when tenant-local time is 02:00
   • pm-rcm-queue-scoring invokes rcm-score-work-queue with organization_id when tenant-local time is 03:00
4. Metadata: Batch execution persists timezone used for audit reproducibility (see spec §Scope clarification table)

​

Security Considerations

• All tables enforce organization-scoped RLS
• Execution records are immutable (no UPDATE/DELETE policies)
• Rule activation requires segregation of duties (creator != activator, except Director override)
• No PHI in rule definitions — rules reference account properties only
• Jurisdiction-aware filing deadlines via PF-96

​

Validation Checklist

• Event contracts match EVENT_CONTRACTS.md entries
• API contracts documented for PM-09/PM-29/PM-45 interactions (see API_CONTRACTS.md and API Contracts section above)
• Platform layer usage aligned with PLATFORM_INTEGRATION_LAYERS.md
• Integration matrix entry in CROSS_CORE_INTEGRATIONS.md