Objective
- Let portal users (agents or clients) complete missing required information directly from the job portal — especially via reminder deep links — instead of replying by text/email and requiring staff to re-enter values on the work order.
- Reduce reminder churn and coordinator manual work; make required-info collection feel like structured self-service rather than back-and-forth.
- Give companies control over whether the feature is enabled, which contact roles can use it, and which fields appear in the portal.
Background
- Missing access, utilities, and other required-info fields often trigger multiple action-flow reminders. Today the reply path is unstructured: the contact texts or emails back, and staff copy values into the internal work order.
- Action flows can already detect missing required info via
required-info-{id}conditions and send reminders, but the portal does not offer a completion path. - The client portal already supports self-service flows for agreements, payments, and repair lists (role permissions + deep links). Required info should follow the same pattern.
- Contact roles already define a portal permission key
info(“Information — Can update required information for the job”) inPORTAL_PERMISSIONS/contactRolesSchema.ts, but it is not wired in the client job UI. The job timeline includes a “Collect Information” step that is currently always marked complete. - Internal workorder editing already handles required-info saves with price/duration impact via
RequiredInfoSection.tsxandWorkorderPriceChangeConfirmModal.tsx/recalculateChargesForRequiredInfo. - Required info fields today support a
hiddenflag (excluded from online scheduler inPropertyMoreInfo.tsx); portal visibility needs a separate toggle. - Spectora sync is out of scope: Attik job type does not push required info to Spectora, so no Spectora write path is needed for this work.
Product decisions
- Company opt-in (Schedule Settings)
- Add a schedule-settings toggle (in
scheduleSettingsSchema.ts/ Settings → Schedule) so companies explicitly enable portal required-info completion. - When disabled, portal users cannot edit required info regardless of role permission.
- Price / duration changes
- If a portal save would change affected service line prices or job duration, show the same preview pattern as the internal workorder (
WorkorderPriceChangeConfirmModal/WorkorderPriceChangeConfirmPanel). - Portal difference: do not offer “save without changing price/duration.” The user must confirm the update (accept price/duration change) or cancel. No staff-only bypass.
- Contact role permission
- Gate portal editing with the existing
infoportal permission on contact roles. - Companies choose which roles receive it via Settings → Contact Roles (
ContactRoleListItem.tsx,PORTAL_PERMISSIONS). - No default grant to all roles — assignment is per company configuration.
- Per-field portal visibility
- Add a new required-info field toggle (separate from
hidden, which controls online scheduler visibility). - Only fields marked portal-visible and assigned to services on the job and currently empty/missing should appear in the portal completion UI.
- All field types supported
- Portal supports all required-info types when portal-visible:
text,number,select,date,boolean, andindicator. - Reuse the same inputs as scheduler/workorder via
RequiredInfoResolver/RequiredInfoAccordion— no type exclusions. - Indicator fields expose all three options in portal: N/A, Yes, No (stored as
n/a,true,false), matching internal behavior. Selecting N/A counts as a completed value (field no longer missing).
Scope
Backend
attik-backend/src/models/scheduleSettingsSchema.ts— new company-level enable flag for portal required-info completion.attik-backend/src/models/requiredInfoSchema.ts— new portal visibility field (distinct fromhidden).attik-backend/src/models/contactRolesSchema.ts— existinginfopermission; ensure portal PATCH routes enforce it plus schedule-settings flag and field visibility.- Portal-scoped inspection update route (or extension of existing portal inspection routes in
inspection.ts/ portal key permissions) — allowrequiredInfoValuesupdates only for permitted, portal-visible, missing fields on the job. - Reuse pricing/duration preview logic from
recalculateChargesForRequiredInfobefore commit; portal save applies changes only after user confirms (no info-only escape hatch). - Activity / audit logging for portal-origin required-info updates (who, which fields).
Frontend — Settings
- Schedule settings UI — toggle to enable portal required-info completion.
attik-frontend/src/app/tools/settings/required-service-info/RequiredInfoListItem.tsx— portal visibility switch (alongside existing Required / Hidden controls).- Contact roles UI already lists
infopermission; verify label/copy matches this feature once live.
Frontend — Client portal
attik-frontend/src/app/client/job/[slug]/— new “Information needed” section (or activate timeline “Collect Information” step) showing missing portal-visible fields.- Deep link support from reminders:
?section=…pattern consistent with agreements/invoice sections inJobAccordion.tsx/Timeline.tsx. - Client-facing price/duration confirm modal (fork or variant of
WorkorderPriceChangeConfirmPanelwithoutonSaveWithoutPrice). - Reuse
RequiredInfoAccordion/RequiredInfoResolverfor all field types.
Action flows
- Reminder emails/SMS can link to the portal completion section; existing
required-info-{id}conditions should stop firing once values are saved (no new trigger strictly required for MVP).
Acceptance criteria
- [ ] Schedule setting off → portal users cannot edit required info even with
infopermission. - [ ] Schedule setting on + role has
info→ user sees only missing, portal-visible required fields for services on the job. - [ ] All field types render and save in portal: text, number, select, date, boolean, indicator (including indicator N/A / Yes / No).
- [ ] Save that changes price or duration → confirm modal with preview; user must confirm or cancel (no save-without-price option).
- [ ] Save with no price/duration impact → persists without confirm modal.
- [ ] Activity log records portal required-info updates.
- [ ] Reminder deep link opens the correct portal section.
- [ ]
hiddenand portal visibility toggles operate independently (scheduler vs portal).
References
attik-backend/src/models/scheduleSettingsSchema.tsattik-backend/src/models/requiredInfoSchema.tsattik-backend/src/models/contactRolesSchema.tsattik-frontend/src/util/types/serverTypeCollection/contact.ts(PORTAL_PERMISSIONS,info)attik-frontend/src/app/tools/inspections/[id]/components/RequiredInfoSection.tsxattik-frontend/src/app/tools/inspections/[id]/components/WorkorderPriceChangeConfirmModal.tsxattik-frontend/src/util/functions/schedulingHelpers/recalculateChargesForRequiredInfo.tsattik-frontend/src/components/scheduling/RequiredInfoResolver.tsxattik-frontend/src/app/client/job/[slug]/components/Timeline.tsxattik-frontend/src/app/client/job/[slug]/components/JobAccordion.tsxattik-frontend/src/components/scheduling/RequiredInfoAccordion.tsx