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

# Add a Custom Property

> Expose a Polarion custom field as a property on an entity type in your Nextedy POWERSHEET data model so it can be displayed and edited in the sheet.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Prerequisites

* The custom field must already be defined in Polarion (**Administration > Custom Fields**)
* The entity type must exist in your `domainModelTypes` section
* Access to the data model YAML via **Menu > Configuration > Edit Model**

<Steps>
  <Step title="Identify the Custom Field">
    Locate the custom field ID in Polarion. Custom field IDs typically use the `c_` prefix.

    | Polarion Setting           | Example                 |
    | -------------------------- | ----------------------- |
    | Custom field ID            | `c_probability`         |
    | Display name               | Probability             |
    | Field type                 | Enum / String / Integer |
    | Applicable work item types | `hazard`                |
  </Step>

  <Step title="Add the Property (Simple Form)">
    For most cases, add the property name directly under the entity type's `properties` section. The property name must match the Polarion field name.

    ```yaml theme={null}
    domainModelTypes:
      UserNeed:
        polarionType: userNeed
        properties:
          description:
          severity:
          component:
          c_customRating:
    ```

    Setting the value to `null` (empty after the colon) uses default configuration: the property is readable, updatable, and uses the property name as the Polarion field name.
  </Step>

  <Step title="Add the Property (Extended Form)">
    For custom fields that need additional configuration, use the extended property format.

    ```yaml theme={null}
    domainModelTypes:
      Hazard:
        polarionType: hazard
        properties:
          description:
          severity:
          c_probability:
            customFieldName: c_probability
            readable: true
            updatable: true
    ```

    ### Property Configuration Options

    | Property          | Type    | Default    | Description                                                                          |
    | ----------------- | ------- | ---------- | ------------------------------------------------------------------------------------ |
    | `name`            | string  | (key name) | Property name used in queries and binding paths.                                     |
    | `customFieldName` | string  | None       | Polarion custom field ID. Required when the property name differs from the field ID. |
    | `readable`        | boolean | `true`     | Controls whether the property is visible in the sheet.                               |
    | `updatable`       | boolean | `true`     | Controls whether the property can be edited in the sheet.                            |
    | `scalar`          | boolean | `true`     | `true` for single values, `false` for collections.                                   |

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/3Zik2OH750CE3kB4/powersheet/diagrams/guides/data-model/add-custom-property/diagram-1.svg?fit=max&auto=format&n=3Zik2OH750CE3kB4&q=85&s=75617c59e49b6d6ab40fc1a92946562b" alt="diagram" style={{ width: "480px", maxWidth: "100%" }} width="480" height="160" data-path="powersheet/diagrams/guides/data-model/add-custom-property/diagram-1.svg" />
    </Frame>
  </Step>

  <Step title="Add a Column for the Property">
    After adding the property to the data model, reference it in your sheet configuration:

    ```yaml theme={null}
    columns:
      c_customRating:
        title: Custom Rating
        width: 120
    ```

    For properties on related entity types, use the full binding path:

    ```yaml theme={null}
    columns:
      systemRequirements.systemRequirement.c_customRating:
        title: SR Rating
        width: 120
    ```
  </Step>

  <Step title="Configure Enum Properties">
    If the custom field is an enumeration, you can optionally constrain the allowed values:

    ```yaml theme={null}
    domainModelTypes:
      Hazard:
        polarionType: hazard
        properties:
          c_probability:
    ```

    <Info title="Verify in application">
      Enum values must match the exact option IDs defined in Polarion's enumeration configuration. Check **Administration > Enumerations** for the correct IDs.
    </Info>
  </Step>

  <Step title="Configure Read-Only Properties">
    To make a property visible but not editable:

    ```yaml theme={null}
    properties:
      c_calculatedScore:
        readable: true
        updatable: false
    ```
  </Step>

  <Step title="Verify">
    1. Save the data model
    2. Reload the powersheet document
    3. You should now see the custom property displayed in the sheet column

    If the column shows empty values, verify:

    * The `customFieldName` matches the Polarion field ID exactly
    * The custom field is defined for the correct work item type in Polarion
    * The property `readable` is not set to `false`

    <Warning title="Built-in vs Custom Fields">
      Built-in Polarion fields (like `description`, `severity`, `title`) do not need a `customFieldName`. Custom fields (prefixed with `c_`) require the exact Polarion custom field ID. Using the wrong field ID results in empty columns without error messages.
    </Warning>
  </Step>
</Steps>

## See Also

* [Create an Entity Type](/powersheet/guides/data-model/create-entity-type) -- define the entity type that holds the property
* [Configure a Relationship](/powersheet/guides/data-model/configure-relationship) -- add navigation properties for related entities
* [Set Entity Permissions](/powersheet/guides/data-model/set-permissions) -- control read/write access at the property level
* [Properties](/powersheet/reference/data-model/properties) -- full property configuration reference
* [Debug Custom Field Issues](/powersheet/guides/troubleshooting/debug-custom-field-issues) -- troubleshoot custom field problems

<LastReviewed date="2026-07-02" />