Visit onboard is the Visit wellness onboarding flow used for eligible members under a selected client policy. The browser first checks how many members are still pending, then starts a background job that pages through employee_polices rows, groups each family by emp_code, sends one payload per family to the external Visit API, and stores the returned referenceId back into employee_polices.wellness_onboard.

Overview

Prerequisites

Before testing or using this feature, confirm that the selected client policy has a valid wellness_plan_id configured in the policy edit screen. This mapping is one of the core prerequisites checked by the current query.

Entry points

The current implementation is split across two browser-facing routes and one queued job handler:

$routes->get("checkWellnessOnboardStatus/(:any)", "EmployeeController::checkWellnessOnboardStatus/$1");
$routes->get("initiateWellnessOnboard/(:any)", "EmployeeController::initiateWellnessOnboard/$1");

'initiateWellnessOnboardJob' => [
    'type' => 'CC',
    'handler' => 'App\Controllers\EmployeeController',
],

On the admin page, app/Views/employee_upload.php calls the count endpoint when a policy is selected, shows the CTA only when the count is greater than zero, and asks for user confirmation before calling the initiate endpoint.

Eligibility rules

Both checkWellnessOnboardStatus() and initiateWellnessOnboardJob() use nearly the same base query. A member is considered eligible only when all of these conditions are true:

The status endpoint returns a count of matching member rows, not a count of grouped families. That is why the button text says employees, while the job later sends one API payload per family group.

Async flow

1. Check the pending count

   checkWellnessOnboardStatus($client_policy_id) runs the eligibility query and returns count($data).

2. Queue the first job

   initiateWellnessOnboard($client_policy_id) inserts a job with the name initiateWellnessOnboardJob and payload ['client_policy_id' => ...].

3. Worker resolves the handler

   JobWorker::$event_class_mapping maps that job name back to EmployeeController.

4. Process one page of rows

   The job defaults to page = 1, per_page = 50, and calculates the SQL offset from those values.

5. Group the current page by family

   Rows are grouped by emp_code before building API payloads.

6. Send to Visit and persist the response

   The job posts each family payload, then stores the returned referenceId into all member rows for that family.

7. Queue the next page only when needed

   If the current query returns exactly per_page rows, the job assumes more data may exist and queues page + 1.

Jobs::addJob([
    'job_name' => 'initiateWellnessOnboardJob',
    'payload'  => [
        'client_policy_id' => $client_policy_id,
        'page'             => $page + 1,
        'per_page'         => $perPage,
    ]
]);

The legacy method initiateWellnessOnboardJobOLD() still exists in the controller, but the active queue mapping points to the current initiateWellnessOnboardJob() implementation.

Family payload

The job builds one outbound payload per emp_code. The first row in the family is used as the policy-level reference, and every family member becomes one entry in memberDetails.

[
    'policyDetails' => [
        'policyNumber'    => $primary['policy_no'],
        'employeeId'      => $empCode,
        'policyName'      => 'GMC',
        'policyStartDate' => $primary['cp_policy_start_date'],
        'policyEndDate'   => $primary['policy_end_date'],
        'plan'            => $primary['wellness_plan_id'],
        'source'          => 'NHANCE',
        'employer'        => $primary['short_name'],
        'employeeCode'    => $empCode,
    ],
    'memberDetails' => [
        [
            'memberId'         => $row['id'],
            'name'             => $row['name'],
            'phone'            => $row['mobile'],
            'email'            => $row['email_corporate'],
            'relationshipName' => $this->mapRelationship($row['relationship'], $row['gender']),
            'gender'           => $row['gender'] == 'M' ? 'Male' : 'Female',
            'dob'              => $row['dob'],
        ],
    ],
]

API integration

sendFamiliesToWellnessApi() uses the CI4 cURL service and reads its runtime configuration from environment values:

Each family is posted as JSON with http_errors = false and a 30 second timeout. The helper stores the raw API result back onto the in-memory family array under apiResponse so the next step can decide whether to persist anything.

$response = $client->post($endpointUrl, [
    'headers' => [
        'Content-Type'  => 'application/json',
        'Authorization' => 'Basic ' . getenv('WELLNESS_ONBOARD_AUTHORIZATION'),
    ],
    'body'        => json_encode($family),
    'http_errors' => false,
    'timeout'     => 30,
]);

If the HTTP client throws, the exception is captured into apiResponse['error'] with a synthetic statusCode of 0.

Response examples

Visit success response (HTTP 2xx with a body the job can decode). updateWellnessOnboardResponseToDB() reads referenceId from the decoded JSON and writes it to employee_polices.wellness_onboard for each policyDetails[].memberId (employee policy row id).

{
  "message": "success",
  "body": "The policy details are posted successfully",
  "policyDetails": [
    {
      "memberId": "100001",
      "name": "Primary Member Example",
      "phone": "9000000001",
      "email": "primary.member@example.com",
      "relationshipName": "husband",
      "gender": "Male",
      "dob": "1962-11-25"
    },
    {
      "memberId": "100002",
      "name": "Dependent Member Example",
      "phone": "9000000001",
      "email": "dependent.member@example.com",
      "relationshipName": "son",
      "gender": "Male",
      "dob": "1996-02-13"
    }
  ],
  "referenceId": "00000000000000000000-NHANCE-1700000000123"
}

Visit failure responses (same endpoint; when validation or business rules fail, the body typically looks like one of these). In these cases the current persistence step skips updating rows because there is no referenceId.

{
  "message": "failed",
  "errorMessage": "Invalid name"
}

{
  "message": "failed",
  "errorMessage": "Invalid mobileno"
}

{
  "message": "failed",
  "errorMessage": "invalid [\"null\",\"string\"]: 100010"
}

The last shape is a schema-style rejection: the bracketed part describes the expected type(s), and the trailing id is the member identifier the API could not accept (shown here as a placeholder id, not production data).

Database updates

Successful persistence is done by updateWellnessOnboardResponseToDB(). The method expects the Visit API response to contain a referenceId. That value becomes the new wellness_onboard value for every member in the family.

The code collects all row updates for the page and writes them in one updateBatch(..., 'id') call, using each memberDetails[].memberId as the primary key.

$allUpdates[] = [
    'id'               => $memberPk,
    'wellness_onboard' => $referenceId,
];

$this->employeePolicyModel->updateBatch($allUpdates, 'id');

Failure behavior

Developer steps

1. Keep the browser trigger and route definitions in sync

   If you rename the route or change the method, update both Routes.php and the AJAX calls in employee_upload.php.

2. Do not move the heavy loop back into the web request

   initiateWellnessOnboard() should remain a thin queue trigger. The batching work belongs in the job handler.

3. Preserve family grouping assumptions

   emp_code is the family key. If source data changes, make sure all related members still group together correctly.

4. Validate required member data before rollout

   Fields such as emp_code, relationship, gender, dob, mobile, and email_corporate affect payload quality.

5. Keep the queue mapping intact

   If you rename initiateWellnessOnboardJob, update the corresponding entry in JobWorker::$event_class_mapping.

6. Verify runtime configuration before testing

   The queue worker must be running, and both wellness environment variables must be present before QA can validate the end-to-end flow.

Common pitfalls