Add a field to the lead form (end-to-end)

Goal: add a new field — we’ll use occupation (the buyer’s job, a free-text field) — to the broker “New Deal” form, and have it travel all the way to Dynamics 365. Read Broker submits a lead first if the flow isn’t fresh.

A field is a cross-repo contract, not just code

A new lead field crosses three repos (frontend, backend, crms-middleware) and the Azure Logic App + Dynamics org owned by the CRM team. The code below gets the value to the Logic App; whether it lands in Dynamics depends on the Logic App/entity accepting a matching field. Agree the Dynamics field name with the CRM team before you start — that’s the value below marked ⟵ confirm with CRM.

The path a field takes

New Deal form ──▶ NewDealFormInterface ──▶ POST /api/broker/leads
   (frontend)                                     │
                                                  ▼
                          SubmitLeadRequest (validate) ──▶ SubmitNewLead (forward)
                             (backend)                          │
                                                                ▼
                          SubmitNewLeadRequest (validate) ──▶ SubmitNewLeadRequestMapper
                             (crms-middleware)                  │  occupation ⟶ <dynamics field>
                                                                ▼
                                                        Azure Logic App ──▶ Dynamics 365

You edit three request classes, one mapper, and the form — and you touch i18n. Below, per repo.

1 · Frontend (broker app)

Repo frontend, app apps/orascom-broker-app. Edit exactly these:

• src/definitions/interfaces/inputs/new-deal.ts two interfaces
• src/pages/new-deal/new-deal.tsx form + payload
• public/locales/en/translation.json labels
• public/locales/ar/translation.json labels (partial stub — add here too)

1. new-deal.ts — add the field to both interfaces:

   // NewDealInputInterface (Formik value shape — camelCase)
   occupation?: string;
   // NewDealFormInterface (API request body — snake_case, the backend's field name)
   occupation?: string;

   For a single word like occupation the two names match. For a multi-word field they diverge — the Formik interface stays camelCase (jobTitle) while the request interface uses snake_case (job_title) — and you map between them in submitHandler.

2. new-deal.tsx — four edits inside NewDeal():

   • initialValues (~line 378): occupation: ''
   • Add a <Field> block inside <Form> (copy the “First name” block, ~397–414), with a <label>{t('occupation')}</label> and <ErrorMessage name="occupation" />.
   • schema (Yup, ~206): add a rule if needed, e.g. occupation: yup.string() (required fields also gate the submit button via !isValid).
   • submitHandler mappedData (~247–293): map it into the body — occupation: values.occupation (guard it like budget/phone_2 if it can be empty).

3. i18n — add occupation (label + placeholder + any validation message) to both en/translation.json and ar/translation.json. Arabic is a partial stub, so if you skip it the label renders in English even in Arabic mode.

Tip

No change to src/api/deal.ts or src/utils/deal.ts — they forward the whole NewDealFormInterface. Only touch those if you add a new endpoint, not a new field.

2 · Backend (Laravel API)

Repo backend. The minimal case is one file:

1. app/Http/Requests/Broker/SubmitLeadRequest.php — add the field + rule to rules():

   'occupation' => ['nullable', 'string'],

   That’s it for send-to-CRM: SubmitNewLead::prepareRequestData forwards the entire validated array under the same keys, so occupation reaches the middleware automatically.

2. Only if the field must be stored locally (rare — the local user_requests table is a thin audit record, not a copy of the lead):

   • app/Models/UserRequest.php — add the column to $fillable (fields not in $fillable are silently dropped by create()).
   • Add a migration under database/migrations/ (pattern: 2024_11_20_113757_add_country_code_column_to_user_requests_table.php).

3. Parity — if the field is cross-persona, mirror it in the shopper request (app/Http/Requests/Shopper/SubmitLeadRequest.php + ShopperSubmitNewLead) and the sales-man request (app/Http/Requests/SalesMan/Lead/SubmitLeadRequest.php + SalesMan\Lead\SubmitNewLead).

3 · Middleware + Dynamics

Repo crms-middleware. Two files — validate the field, then map it to a Dynamics field name:

1. app/Http/Requests/Api/Portals/Broker/SubmitNewLeadRequest.php — add the unified key to rules(). Required: $request->validated() drops anything not declared here.

2. app/Mapper/SubmitNewLeadRequestMapper.php — add one entry to the Dict schema:

   'jobtitle' => new Str('occupation'),   // 'jobtitle' ⟵ confirm with CRM

   The array key is the Dynamics field name (agree it with the CRM team); the constructor arg is the unified request key. Use Decimal for money-like numbers (as clientbudget), Str otherwise.

3. No client/config change — the same Logic App URL (LEAD_CRM_SUBMIT_NEW_LEAD_URL) is reused. Only touch config/services.php/env if you point at a different upstream.

Verify it end-to-end

1. Lint + type-check the frontend: yarn nx lint orascom-broker-app and tsc -p apps/orascom-broker-app/tsconfig.app.json --noEmit (plain tsc --noEmit checks nothing in this Nx app).
2. Backend: add/adjust a Feature test under tests/Feature/Api/Broker/… (happy + validation + auth-failure), run php artisan test.
3. Manually: run the broker app (yarn start:broker, port 4201), submit a lead with the new field, and confirm the value reaches the CRM. If you can’t see it land in Dynamics, that’s the Logic App / field-name contract — go back to the CRM team.
4. Contracts: update backend/docs/openapi.yaml and crms-middleware/docs/portals-openapi.yml.

Reality check

If your field appears in the request but never in Dynamics, the code is fine — the Logic App or the Dynamics lead entity isn’t accepting jobtitle. That’s a CRM-team change, not a portal change. This is the single most common reason “I added the field but it’s not saving.”

Next: ship this as a real PRThe full clone → run → change → test → PR → verify walkthrough.