> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Custom Fields

> Admin settings page for managing custom field definitions on GR policy records — create, edit, enable/disable, and delete per-tenant policy metadata fields.

The Policy Custom Fields page (`/gr/settings/policy-custom-fields`) renders `PolicyCustomFieldsPage`, which manages `pf_custom_field_definitions` records scoped to `entity_type = 'gr_policy'`.

## Overview

`PolicyCustomFieldsPage` uses the platform PF-16 custom fields system:

* `useCustomFieldDefinitions('gr_policy')` — fetches all custom field definitions for the `gr_policy` entity type.
* `useCustomFieldMutation` — provides `createDefinition`, `updateDefinition`, and `deleteDefinition` mutations.

The page renders a table with columns for field name, type, and enabled/disabled toggle (a `Switch`). Each row has edit (pencil) and delete (trash) icon buttons. A **+ Add Field** button opens a `Dialog` containing `CustomFieldDefinitionForm`. Deletion uses a confirmation `AlertDialog`.

The `ENTITY_TYPE` constant is `'gr_policy'`, ensuring fields defined here appear only on policy forms and detail views.

## Who it's for

Requires permission: `gr.policies.custom-fields.manage` (`GR_PERMISSIONS.POLICIES_CUSTOM_FIELDS_MANAGE`). Users without this permission cannot access this route.

## Before you start

* You must hold `gr.policies.custom-fields.manage`.
* Custom fields defined here will appear on the policy creation wizard and policy detail forms for all users in the organization.
* Coordinate with compliance before adding fields that might capture regulated data.

## Steps

<Steps>
  <Step title="Open Policy Custom Fields settings">
    Navigate to `/gr/settings/policy-custom-fields`. The page loads all `pf_custom_field_definitions` for `entity_type='gr_policy'`.
  </Step>

  <Step title="Review existing fields">
    The table shows each field's name, type, and enabled status. Use the toggle switch to enable or disable a field without deleting it.
  </Step>

  <Step title="Add a new custom field">
    Click **+ Add Field**. The `CustomFieldDefinitionForm` dialog opens. Enter the field name, select a type, and set options if applicable. Save to create the definition.
  </Step>

  <Step title="Edit an existing field">
    Click the pencil icon on a field row. The same form opens pre-populated with the field's current values. Save to update.
  </Step>

  <Step title="Delete a field">
    Click the trash icon. A confirmation dialog (`AlertDialog`) asks you to confirm deletion. Confirm to call `deleteDefinition`.
  </Step>
</Steps>

## Key concepts

* **pf\_custom\_field\_definitions** — platform table (PF-16) storing per-tenant custom field schemas; scoped by `entity_type`.
* **entity\_type = 'gr\_policy'** — ensures these fields appear only on policy records.
* **CustomFieldDefinitionForm** — shared platform form component for creating or editing a custom field definition.
* **enabled toggle** — controls whether the field appears on forms without permanently removing the definition.

## Related

<Columns cols={2}>
  <Card title="Governance & Compliance" icon="scale-balanced" href="/gr/overview">
    Governance & Compliance core overview.
  </Card>

  <Card title="Governance & parity" icon="clipboard-check" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/gr.tsx
  * src/cores/gr/pages/settings/PolicyCustomFieldsPage.tsx
  * src/platform/permissions/constants.ts
  * src/platform/custom-fields/index.ts
</Accordion>