Payroll management

Product context crash course

Overall problem space

• In France, health insurance is billed to companies which in turns deduct part of the health coverage price directly from each collaborator payslip (exact amount depending on the company participation)
• This means that Alan like other health insurers needs to share to its customers the amount to apply on each payslip. For a given collaborator, the exact amount depends on:
  • the company contract price structure and the number of beneficiaries
  • the coverage start date as we apply a pro rata (including for partner or child enrollments, which is Alan specific = non industry standard)
• Additionally, as Alan handles exemption for our customers (unlike most other insurer), a data flow back to our customer is required in any case to not apply health premiums on exempted employees' payslip.

The core of our challenges is about efficiently sharing back information every month to payroll managers and reduce the number of actions requiring manual actions from them.

Payroll knowledge bits in no specific order

• We let customer configure on which day of the month they want to receive info from us (stored in company.day_to_send_pay_info)
• Most payroll software automatically compute primaries coverage prices once the right config is set based on work contract date but not beneficiaries pro-rata + they still lack exemption data until it's inputted based on data shared by Alan.
• Regularization requires manual action on payroll managers' side.
• There's a company feature pay_info_month_shift allowing to close payroll for a different month (example: close Feb payroll in January)

What we offer to our customers

• Payroll tool + corresponding export that exposes billing_changes data.
• Legacy pay CSV are files that are generated during every monthly payroll closure. Currently sunset and set for removal on December 2025. The file has been replaced by the payroll tool file which is a dynamically generated file based on the same data as the payroll tool.
• A payroll integration with PayFit via API. Look for get_pay_info/v<int:version>/<siret> API endpoint.
• Some Civil servants companies rely on a tailored made payroll integration based on CSV files. Look in the folder components.fr.internal.civil_servant_payroll_integration. This one is a bit different from others as it's an export of affiliation data with specific business logic rules (instead of billing data).

Technical details

High level overview of what happen when payroll is closed for a company

The following schema illustrate what's inside the function handle_generate_pay_csv which is triggered by a CRON job and is only run on a company day_to_send_pay_info.

graph TD
    cron[Daily cron] -->|CRON job| pe
    subgraph pe [update premium entries]
        A[(Coverage data)] -->|update_affiliation_premium_entries_for_contract| B[(Premium entries)]
    end
    subgraph bl [update billing change]
        C["\+"]
        C -->|update_billing_changes| E[(Billing changes)]
    end
    D[Affiliation data] --> C
    pe --> C
    bl ---->|Mark month payroll as closed| F[(MonthlyPayrollInformation)]
    F -->|Generate pay csv - legacy| pay_csv

    subgraph pay_csv
        direction LR
        B1(Premium entries) -->  B3["\+"]
        B2(live affiliation data) --> B3
        B3 --> H[(pay csv)]
    end

    pay_csv --> ALM
    subgraph ALM ["Civil servant specific payroll integration (ALM files)"]
        direction LR
        I[(Affiliation data)] -->|take_affiliation_snapshot| J["\+"]
        K[(Account setting)] -->|get_renoirh_payroll_file_config| J
        J --> L[(affiliation_snapshot_entry)]
        L -->|generate_file_for_delivery_group| M[(renoirh_custom_payroll_files)]
    end

Hold "Alt" / "Option" to enable pan & zoom

Payroll tool

• It's available from the admin dashboard
• It exposes billing_changes data that are computed daily to reflect the latest affiliation changes.
• A file export is also available that format billing_changes data into a specific format.

DSN reconciliation tool

• It's available from the admin dashboard
• This tool is about spotting gaps between Alan affiliation data and customers' data received through DSN.

ALM files = Civil servants payroll integrations.

• This specific integration is configured via the account setting civil_servant_centralized_payroll_management which stores in the metadata the companies in the scope of the integration.
• The output is a set of 2 csv files in very specific format. See specs here ⧉
  • one file contains all the "closing"/termination movements
  • the other, all the "opening"/new affiliation movements
• One how-to documented here ⧉
• Technically, it's based on a taking a monthly snapshots of affiliation data and comparing the current month one to the previous one to infer the movements.
  • We have a first layer corresponding to the function take_affiliation_snapshot. It's only responsibile for taking a snapshot and only contain minimal business logic:
    • ignore end dates later than current payroll month
    • ignore passive agents (covered by default ones) if the config flag is set in the corresponding account setting
  • The second layer corresponds to the function generate_file_for_delivery_group and contains most of the business logic. It will load the affiliation snapshot entries and infer the movements and apply the business logic rules detailed in the specs.
• Full tech framing here ⧉