skills/walla/references/custom-fields.md

# Custom field workflows

Custom fields are an Enterprise capability. Use the MCP's `custom-fields` reference as the authoritative model for data references, output schemas, and host interaction.

## Reuse an existing type

1. Call `list_custom_field_types(teamId)` before proposing a new build.
2. If a suitable type exists, use its real `customFieldTypeId` with `form_apply_edits` and `fieldType: CUSTOM`.
3. Re-read the form and verify the attached type and version information.

## Build a new type

Follow the state machine exactly:

1. Call `start_custom_field_build` with the team, a clear name, and a concrete description of the field's behavior and saved value.
2. Poll `get_custom_field_build` until the state is `awaiting_your_code`.
3. Call `get_custom_field_scaffold`. Treat the returned scaffold and allowed file paths as authoritative; do not invent SDK APIs, imports, or unsupported files.
4. Implement the smallest complete field, then call `submit_custom_field` with the required files.
5. Poll `get_custom_field_build`. On `try_again`, retry the same poll. On `build_failed`, use the returned errors to revise and resubmit.
6. At `ready_to_review`, give the user the returned `previewUrl` and ask them to review the rendered field.
7. Call `approve_custom_field_build` only after the user has approved the preview. Approval registers a reusable type and immutable version.
8. Attach the returned `customFieldTypeId` to a form with `form_apply_edits`, then verify with `get_form`.

## Data and privacy rules

- Declare the value shape through the build's output schema and keep it aligned with what the field saves.
- Request only the form or hidden-field data the component genuinely needs. Never add broad data references for convenience.
- Use real field IDs from the target form, including same-batch aliases only where the editing contract permits them.
- Do not make a custom field observe itself.

## Build lifecycle

- A team has a limited number of builds in flight. If an abandoned build occupies a slot, offer `cancel_custom_field_build` only after the user confirms they no longer want it.
- Cancellation is irreversible for the build and tears down its preview. It cannot cancel an approved version.
- Do not start a replacement build merely to work around a transient state. Poll or resubmit within the existing build as the returned state directs.