---
title: "Dynamic Field Surface Spec"
slug: dynamic-field-surface-spec
section: Globus Core
status: stable
description: "The contract every partner portal must honour so any new Workflow Studio field, once classified via the Field Classification Contract, automatically appears in the right place in the right portal — without a code change."
last-updated: 2026-10-07
---

# Dynamic Field Surface Spec

The contract every partner portal must honour so any new Workflow Studio field, once classified via the Field Classification Contract, automatically appears in the right place in the right portal — without a code change. Spec only; no portal code lives here.

> **Build status: not started (verified against BackOfficePrototype `development`, 2026-07-28).**
>
> Nothing in this spec exists in code yet. There is no `surfaces` slot on Workflow Studio field metadata, and the surface names `recruiter.summary`, `recruiter.profile`, `host.talent_card`, `host.profile`, `staff.profile`, and `workflow_tab_only` appear nowhere in the codebase. The "Additional Information" auto-render section, the authoring-time fallback warning, and the new-field notification rule are all unimplemented.
>
> What *does* exist today and is the current audience mechanism: the step-level `data_scope` column on `workflow_steps` (`staff_only`, `staff_and_host_after_placement`, `staff_and_recruiting_partner`, `staff_and_host_and_recruiting_partner` — see `WORKFLOW_STEP_DATA_SCOPES` in `shared/models/workflow.ts`) plus the platform PII registry enforced by `server/middleware/piiRedactor.ts` and `server/lib/redactForRole.ts`. Pages that cross-reference this spec (Applicant vs Application, Host Portal Governance, Partner Portal Governance, Glossary) describe target state, not shipped behaviour.

> **Studio decides where; portals do what they're told**
>
> Today the Applicant Portal renders Studio fields dynamically; the Recruiter and Host Portals do not. A new field added in Workflow Studio lands in portal_step_snapshots and is technically reachable via the generic Workflow tab on the staff view, but it never appears on the cards and profiles partners actually look at. This spec closes that gap by defining a small set of named surfaces, the rendering contract each surface implements, and the fallback / warning rules that make the gap loud rather than silent. It consumes the metadata defined in the Field Classification Contract and depends on it being authored first.

## Problem: Studio Adds Fields, Partner Portals Don't See Them

Workflow Studio is the source of truth for what a program collects. When a program admin publishes a new step or adds a new field, the Applicant Portal renders it on the next load — that path is dynamic. The Recruiter Portal and the Host Portal were both built around hardcoded sections (summary cards, profile sections, talent cards), so a new Studio field is captured but invisible on the surfaces partners look at every day.

The silent-failure path

- A program admin adds a field in Workflow Studio (e.g. “Driver's License Class” on a Camp Counselor workflow).
- The applicant fills it in; the value lands in the snapshot row for the application.
- The host's talent card and applicant profile render their hardcoded sections — neither knows about the new field.
- The host calls the program manager asking why they can't see the driver's license info, even though they were told it was being collected.
- No error. No warning. The data is captured but invisible where the host actually decides.
## Surface Taxonomy

A field surface is a named, partner-facing destination on a portal that a Workflow Studio field can be tagged to. The surface set is closed and small on purpose — every surface listed here is a place a partner already looks, so a field tagged to a surface is guaranteed to be seen. The surfaces slot on every Studio field (defined by the Field Classification Contract ) takes its values from this taxonomy.

### Named Surfaces

| Surface | Portal | Location | Purpose |
| --- | --- | --- | --- |
| | portal | location | purpose |

_(row above is a template, repeated for each data row)_

> **A field can be tagged to multiple surfaces**
>
> The surfaces value is an array. A driver's-license-class field for a camp counselor workflow might carry ["host.talent_card", "host.profile", "staff.profile"] — appearing on the host's grid card, the host's deep view, and the staff view, while being invisible to recruiters. Per-partner visibility narrowing on top of this is handled by the step's data scope (which determines whether the step is projected to a given audience at all) and by the platform PII registry (which always masks the registered field types), not by adding more surfaces.

### workflow_tab_only — The Fallback Surface

workflow_tab_only is the default destination for any field whose surfaces slot is empty. The value is captured normally and is reachable from the staff Workflow tab keyed by step_key, but no recruiter, host, or curated staff section ever displays it. This surface exists so the spec can be exhaustive — every field has a surface, even if that surface is “nowhere visible to a partner.” It is paired with the authoring-time warning (below) so the fallback is always a deliberate choice.

## Rendering Contract

Every applicant detail view in every partner portal must honour the rules below for fields tagged to one of its surfaces. These rules are minimal on purpose — the goal is a deterministic mapping from field metadata to rendered row with no portal-side decisions.

### The “Additional Information” Section

Every applicant detail view that exposes a profile-level surface (recruiter.profile, host.profile, staff.profile) must include an Additional Information section. This section auto-renders every Studio field tagged for the surface, in the order defined below, using the field's authored label, with the projector applying the step's data scope and the platform PII registry before the row reaches the portal. The section is present even if the workflow currently tags zero fields for the surface — the empty state renders “No additional information.” This guarantees that the next time a field is tagged, it appears without any portal change.

Card-level surfaces (recruiter.summary, host.talent_card) do not have a separate “Additional Information” section — they auto-render the tagged fields directly on the card body, after the hardcoded fields, with the same ordering rule.

### Label & Rendering Rules

### Ordering & Grouping

Fields inside Additional Information are ordered by step order in the published workflow, then by field order within the step. There is no portal-side re-ordering and no per-partner customization (explicitly out of scope — see below). If the Field Classification Contract is later extended with a surface_group slot, this spec will be revised to honour it; until then, step order is the single ordering signal.

### Field Metadata Shape Consumed

The portal consumes the field-level metadata defined on Field Classification Contract → Metadata Shape . The relevant slots for this spec are:

// Per-field metadata, partial — only the slots this spec reads

"label": "Driver's License Class",

"surfaces": ["host.talent_card", "host.profile", "staff.profile"]

// Audience visibility is NOT a per-field property:

// - the step that owns this field carries a single data-scope dropdown

// (staff_only / staff_and_host_after_placement /

// staff_and_recruiting_partner / staff_and_host_and_recruiting_partner)

// - the platform PII registry hard-masks passport, DOB, SSN,

// background-check detail, and medical regardless of step scope

The portal does not read scope or core — those decide where the value is stored / whether other systems may bind to it, not where it renders. Storage routing is owned by Globus (see the Field Classification Contract's runtime audit).

## Fallback & Authoring-Time Warning

### Untagged-Field Default

A field with an empty surfaces array defaults to workflow_tab_only. It is captured, stored per the field's scope, and reachable from the staff Workflow tab — and it is invisible everywhere else. This default is the same behaviour as today, made explicit. Nothing about a published workflow regresses by adopting this spec.

### Workflow Studio Warning Rule

Workflow Studio must show a visible warning at authoring time on any field whose surfaces slot is empty, with copy along the lines of:

⚠️ This field has no partner surface. It will be captured but will only appear on the staff Workflow tab. No recruiter or host will see it. If that is intentional, dismiss this warning to confirm.

The warning must be dismissible per-field (acknowledging the fallback is a valid choice for staff-only data) but must persist its dismissal state on the field metadata so the warning re-fires if the field is later edited and the surfaces slot is re-cleared. The rules-coverage panel on the Workflow Studio canvas (per Workflow-to-Rules Coverage Panel ) gains a new column counting the number of unsurfaced fields per step. The warning never blocks publishing — it makes the silent-failure path loud, not impossible.

> **Implementation gap, surfaced not fixed**
>
> The Workflow Studio authoring UI does not yet render the surfaces input or the warning above (this is the same gap reported as FCC1 on the Field Classification Contract's authoring audit). This spec defines what the warning must look like and when it must fire; building it is a follow-up against the Workflow Studio page.

## New-Field Notification Rule

When a published workflow change introduces a new field on a partner-visible surface, the affected partner orgs must be notified. This page only specifies the rule — the notification dispatcher, channel routing, and per-recipient preferences are owned by Notifications and per-portal preference systems.

### Trigger

| field | value |
| --- | --- |

### Recipients

| field | value |
| --- | --- |

### Template Reference

| field | value |
| --- | --- |

## Partner Visibility Matrix — Restated In Surface Terms

The Partner Visibility Matrix on the Applicant vs Application page is, today, a static list of fields per partner type. This spec re-frames it as “what surfaces exist, and what currently fills them” — so the matrix becomes a snapshot of a dynamic system rather than a list that must be edited every time a field is added.

| Surface | Filled today by | What changes under this spec |
| --- | --- | --- |
| surface | filledByToday | whatChanges |

_(row above is a template, repeated for each data row)_

The Partner Visibility Matrix on Applicant vs Application Data cross-links this page as the authoritative surface enumeration. The per-field tables on that page remain useful as a snapshot of what currently fills each surface; they are not the surface contract.

## Out of Scope (Tracked Separately)

- Implementing the “Additional Information” section in any actual portal — implementation is per-portal follow-up against this spec.
- Building the new-field notification dispatcher — only the trigger and recipient rules are defined here; wiring lives on the notifications side.
- Per-partner customization (each partner choosing which surfaces or fields they care about) — explicitly deferred.
- Re-architecting portal navigation, replacing existing hardcoded sections, or changing the Host Portal Contract — this spec is additive on top of what is already there.
- Adding per-field surface_group ordering hints — out of scope until step order proves insufficient.
## Related Pages

Field Classification Contract

Defines the per-field metadata (label, surfaces) this spec consumes, plus the step-level data scope dropdown and platform PII registry that together replace per-field redaction — that replacement is a settled product decision, recorded in code as DEPRECATED_DATA_ACCESS_TERMS in shared/contracts/dataAccessContract.ts. The surfaces slot defined there takes its values from this page's taxonomy and is likewise not yet built.

Partner Visibility Matrix

The static visibility matrix this spec restates in surface terms. The matrix page now cross-links here as the authoritative surface enumeration.

Partner Portal → Applicant Detail View

The recruiter detail surfaces this spec adds an Additional Information section to. References this spec as a required contract.

Host Portal → Dynamic Applicant Data Rendering

The host-side dynamic renderer this spec constrains to surface-tagged fields. References this spec as a required contract.

Workflow Studio → Coverage Panel

Where the unsurfaced-field count column is added. The authoring-time warning fires inside the Studio canvas.

Notifications

The dispatcher that delivers the new-field notifications defined here. This spec only specifies the trigger, recipients, and template reference.