Inception here means onboarding employees and dependents from an Excel upload (files.action = inception or related actions like missed_inception, addition, dependent_addition). The same three-step pipeline runs for those actions; this page focuses on the inception path.

Manual policy inception (form UI under policy_tranction/inception) is a separate flow in PolicyTransactionController — not covered by these three functions.

Overview

In short:

• Step 1 — Format: Headers, column count/order, per-cell type and mandatory rules.
• Step 2 — Data: Family-level checks (Self row, duplicates, policy terms, DB conflicts).
• Step 3 — Preprocess: Premium via rack rates, then insert employees and inception policy transaction.
• Large files (> 1 MB) run steps 1–3 as background jobs via JobWorker.

Key files and routes

Routes (group /employee, filter authMVC):

• GET /employee/upload — upload screen
• POST /employee/upload — upload + start validation (upload-action-type=inception)
• GET /employee/excel_error/{file_id} — returns files.reason JSON for the error modal

REST upload (mobile/HR): POST employeeRest/employeeUpload — same pipeline via EmployeeRestController.

Sync vs background jobs

After upload the UI usually shows files.status = inprogress until jobs finish. Poll notifications or refresh the upload list; use /employee/excel_error/{id} when status is failed.

Entry points

Job chain for inception (and missed_inception / addition / dependent_addition):

excelFileFormatValidation → excelFileDataValidation → employeesOnboardPreprocess

Step 1: excelFileFormatValidation

Runs on the uploaded sheet before any DB business rules.

• Loads file from writable/uploads/excel/{file_name}.
• Uses $inception_excel_columns when action is inception (same column set for addition / dependent_addition / missed_inception).
• Checks policy has terms and slab rates configured — otherwise fails early.
• Validates each data row: mandatory (by action code I), date/mobile formats, allowed lists, custom helpers (DOB, relationship, SI, mobile duplicate, etc.).
• Stops at first empty row (treated as end of data).

Common format error codes

On failure: files.status = failed, reason JSON with row/column errors; user notification via pull notification.

Lead-policy branch: If inception file is for a policy created from leads (policy_entry_from == 3 and is_from_lead set), format validation queues compareMemberDataAndInceptionData instead of going straight to data validation.

files.reason shape (debugging)

Stored as JSON string on files.reason. Typical failure payload:

{
  "error_type": 1,
  "error_summary": { "4": 2, "1": 1 },
  "error_data": {
    "3": {
      "dob": { "error": ["Invalid date format"], "value": "01/01/1990" }
    }
  }
}

• error_type — 1 = format step, 2 = data step
• error_summary — counts per error code (after aggregation)
• error_data — keyed by Excel row number (1-based, header is row 1)

Step 2: excelFileDataValidation

Runs after format passes. Groups rows by EMP ID (family) and applies business rules.

Typical inception checks:

• Self row required (unless GMC parents policy allows otherwise).
• No duplicate names within the same family in the file.
• Employee code must not already exist for inception / addition / enrollment.
• Dependent rules vs policy_terms (family composition, LGBTQ flag, etc.).
• Name + emp id consistency vs database (name_and_empid_check_in_db).

On success for inception: queues job employeesOnboardPreprocess. Other actions queue different jobs (deletion, correction, etc.).

Common data-validation error codes

Step 3: employeesOnboardPreprocess

Calculates premium and writes members to the database.

1. Reload Excel; group by emp_id.
2. For each family: calculate_premium_new() using policy terms + slab rates + rack config.
3. employeesOnboardProcess() — insert/update employees, employee_polices, create policy_transaction (inception).
4. If at least one family inserted → files.status = success; else failed with rack-rate message.

Optional second path: client_policy_id without file_id — converts enrolled DB members to inception (enrollment → inception), not from Excel.

TPA batch: When batch_file_id is present on the job payload, success also queues updateEmployeeDataFromTpa, reconTpaApiDataWithEmployeepolicies, and initializeDeletionProcessForTpaApiData (multi-file TPA reconcile flow).

Inception Excel columns

Defined in EmployeeServiceController::$inception_excel_columns. Header row must match exactly — 19 columns (A–S), row 1 only. Dates use format d-M-Y (e.g. 4-Apr-1990). One Self row per EMP ID; other rows are dependents.

Sample file: use the download link on the employee upload screen (environment-specific).

Family row layout example

All rows with the same EMP ID (column B) are treated as one family. Step 2 requires exactly one Self row in that group; dependents share the same EMP ID. Step 3 runs premium and DB insert once per family.

Example: one employee (EMP001) with spouse and son — three data rows plus header.

Rules illustrated:

• Same EMP ID on rows 2–4 → one family processed in step 3.
• Self on row 2 only — row 3 without Self would fail with code 14.
• DOB uses d-M-Y; ages are checked against relationship (e.g. Son vs Self).
• PED (PRE EXISTING AILMENTS) = 0 or 1 on every member for inception.
• BASIC COVER SI must match slab rules when the policy uses SI-based racks (often same amount across the family).
• Columns H–S can be blank for inception when not mandatory; phone/email must be unique in the file if filled.

A second employee in the same file uses a different EMP ID (e.g. EMP002) with its own Self row — each EMP ID is a separate family loop in preprocess.

Developer steps

1. Confirm policy has policy_terms JSON and slab/rack rates for the client policy.
2. Upload via /employee/upload with action inception; note file_id in response or files table.
3. If status = failed, call GET /employee/excel_error/{file_id} or read files.reason.
4. Map error_data row keys back to Excel (row 1 = header).
5. If format passes but preprocess fails with rack message, debug calculate_premium_new (see rack-rate doc) and SI/slab config.
6. For stuck inprogress, check job queue / JobWorker logs for the three job names.

Common pitfalls

• Policy not ready — missing policy_terms or slab rates fails step 1 with code 5.
• Missing Self row — one Self per EMP ID in the file (code 14 in step 2).
• Wrong header row — column count or name mismatch (code 5 / 6).
• Rack rate / SI — preprocess succeeds only if calculate_premium_new returns data for every family.
• File status — watch files.reason JSON for row-level errors after failure.