Automated Invoicing

Business process and UX workflows

See https://www.figma.com/file/5vA2MaqUFjElG3nJayFYbv/IV-Invoicing-Flow-and-ux?node-id=0%3A1

Design constraints

1. The system should provide centralized methods aligned closely to the steps in the business process workflow with equivalent inputs/outputs for each step
   • Benefit: future iterations of the business process can be designed within a framework that maps to isolated impacts within the codebase
   • Benefit: an MVP can be brought into operation with scaffolded elements that can later be replaced with minimal rework
2. The system should be agnostic in the long-run to what account/invoicing system is used to publish invoices
   • Approach: The last step before export will generate generic invoice structure: subject, lines [ item, description, quantity, price ]
   • Benefit: QuickBooks could be replaced with a different accounting system some day
   • Benefit: Hospital invoicing and payment could be brought in-house and integrated with the portal experience some day
3. Invoices will be generated per time period following closeout of the payroll process for same time periods
4. The system should be able to render invoice data for a given set of shifts consistently at any point in time
   • Benefit: Applying policy/rate changes shouldn’t need to be carefully timed and coordinated with invoices being generated
   • Benefit: Invoices can be regenerated after corrections are made to policy/rates or code
   • Question: What does this look like long term when the bigger formulas change instead of just rates? i.e. should the code go so far as be required and tested to maintain multiple code paths based on effective dates of new formulas?
   • Question: How valuable is this vs making it the invoicing/accounting system’s responsibility to snapshot invoices?

Implementation

Phase 1: MVP

Scope: Operationalize an automated workflow for generating invoices for hospital customers that provides a minimal viable replacement for the current manual workflow.

Features

• Rates based on hospital geo
• Rates overridable per-hospital from CATS profile or onboarding
• Canceled shifts can be marked as billable to be included in timesheet review and on invoices
• Both a CSV and SDK approach to publishing invoices to QuickBooks will be made available inline with existing Payroll publish workflow
  • Tracking invoiced shifts against the invoice they were included on (SDK publish flow only)
• QuickBooks UI leveraged for invoice review and approve workflow

Limitations

• Only two layers of rate-setting: geo lookup and per-hospital override
• Rates lookup will be pulled from a BI process’ output without history/effective dates, and subject to its update frequency
• Changes to rates and generation of invoices will need to be closely coordinated
• Invoices will not be sent automatically, but left to be reviewed and then sent from QuickBooks
• Shifts can only be recorded as invoiced and mapped to specific invoices if the SDK publish flow is used
• Entire invoice publish process will be blocked if any included hospitals are yet to be published/linked to QuickBooks

Data model

• Cached read of Geo->Rate lookup table from BI warehouse table
• Cached read of QuickBooks items table
• Add cancelled_billable boolean column to shifts table, default to false, set to true when admin checks
• Add quickbooks_invoice_id integer column to shifts table, default to null, write after SDK publish

Stories

• CATS-365 As an admin, I can no longer add custom adjustments on-the-fly from the timesheets view
• CATS-366 As an admin, I can see geo base rate after selecting geo during onboarding
• CATS-367 As an admin, I can see effective base rate in header area when viewing hospital profile
• CATS-368 As an admin, I can see geo base rate alongside geo selection when editing hospital profile details
• CATS-369 As an admin with the extra-admin-features feature flag, I can set/change/remove override base rate when editing hospital profile details
• CATS-370 As an admin, I can update geo rates via Sharepoint spreadsheet and BI workflow
• CATS-371 As an admin, I can mark a cancelled shift as billable in the cancel-shift modal from the schedule view
• CATS-372 As an admin, I can mark a cancelled shift as billable while approving a cancel change request
• CATS-373 As an admin, I can see cancelled shifts that have been marked as billable on the timesheets review screen, and they are identifiable as such
• CATS-378 As an API user, I can retrieve a list of billable shifts for a selected time period and optionally a selected customer
• CATS-376 As an API user, I can retrieve a CATS-centric data tree for invoice rendering for a selected time period and optionally a selected customer
• CATS-374 As an admin, I can publish invoices to QuickBooks via SDK for a selected time period
• CATS-375 As an admin, I can download a CSV of invoices for a selected time period

Open Questions

• When an item doesn’t exist yet in QuickBooks, should we create it on-the-fly or crash?
  • Creating on-the-fly would be preferable, as otherwise we would need to pre-check the entire batch for nonexisting items in order to crash before partially writing invoices. New items can be created with only the generated name and defaulted to the Service type.

Phase 2: Remove scaffolding

• Manage rate tables with effective dates and audit history
• Formalize closeout workflow across payroll and invoicing
• Standardize on SDK-based publish flow
• Expose manual trigger for republishing one or all invoices following corrections
• Enhanced CRUD for custom rate adjustments (e.g. setting an expiration date, adjusting amounts)
• CRUD for geos (may also need region support by then)

Phase 3: Continuous improvement

• Send invoices automatically
• More advanced methods for setting/adjusting rates
• Integration with hospital portal / dashboards

Parking lot

These stories have been considered but indefinitely deferred:

• As an admin, I can set an override base rate during onboarding