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

# Custom attributes: Extensibility guide

This guide details the **Custom Attributes** framework in Zenskar. This system allows you to extend the standard data model for **Customers**, **Contracts**, and **Products**, ensuring the platform adapts to your specific business logic, reporting requirements, and third-party integrations.

***

## 1. Core concepts: The data extensibility framework

Custom Attributes (also referred to as Custom Fields or Metafields) are the primary mechanism for adding bespoke data points to Zenskar’s core objects.

### Why use custom attributes?

Standard SaaS schemas often lack the granularity required for complex B2B operations. Custom attributes solve this by providing:

* **Structural integrity**: Unlike free-text "Notes" fields, custom attributes use defined data types (integer, boolean, etc.) to ensure data consistency across thousands of records.
* **Downstream automation**: Attributes are assigned a permanent **Property Key Name**. This key acts as the technical anchor for API integrations and Webhooks to pass data to external systems like your CRM or ERP.
* **Governance**: Admin-defined rules, such as the **Mandatory Field** toggle, ensure that your team captures critical information every time a new record is created.

### Supported objects

Custom attributes can be independently configured for each of the following core objects:

| Object       | Common use cases                                        | Example custom attributes                              |
| :----------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **Customer** | CRM sync, regional tax compliance, account tiering.     | `Salesforce_Account_ID`, `VAT_Number`, `Account_Tier`  |
| **Contract** | Project tracking, legal metadata, sales commissions.    | `Project_Code`, `Legal_Review_Status`, `Commission_ID` |
| **Product**  | Technical provisioning, inventory SKUs, categorization. | `Hardware_SKU`, `Server_Region`, `License_Type`        |

***

## 2. Quickstart guide: Setting up custom attributes

This quickstart covers adding a custom field to any of the three supported objects.

1. **Navigate to Settings**: Go to **Settings** > **Custom Attributes**.
2. **Select object**: Scroll to the object you wish to extend (**Customer**, **Contract**, or **Product**).
3. **Add Property**: Click the **+ ADD NEW PROPERTY** button.
4. **Property details**:

   <br />

   | Configuration field        | Action / Description                                                                                                                                                                         | Example / Options                            |
   | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- |
   | **Select Business Entity** | Define the scope of the attribute.                                                                                                                                                           | Applicable to all or specific legal entities |
   | **Property Name**          | The user-facing label shown in the UI.                                                                                                                                                       | *Sales Region*                               |
   | **Property Key Name**      | The backend system ID (auto-generated but editable before save).                                                                                                                             | `sales_region`                               |
   | **Data Type**              | The format of the data allowed in the field. See the [Reference section for available data types](https://docs.zenskar.com/docs/custom-attributes-extensibility-guide#supported-data-types). | Text, Integer, Boolean, etc.                 |
   | **Default Value**          | (Optional) The value pre-filled for new records.                                                                                                                                             | *N/A* or *0*                                 |
   | **Mandatory Field**        | Toggle to require completion before saving.                                                                                                                                                  | Yes (Required) / No (Optional)               |
5. **Review and Save**: Click **ADD**.

<Callout icon="📚">
  When you open the [create or edit side panel for a Customer, Contract, or Product object](https://docs.zenskar.com/docs/custom-attributes-extensibility-guide#accessing-the-slide-panel) and select a business entity, all custom attributes configured for that entity automatically appear in the Custom Attributes section, either pre-filled with their default values or as empty fields. Review and update the pre-filled values if needed, and complete any empty fields before saving.
</Callout>

<Callout icon="❗️" theme="error">
  **Immutability**: Once you click **ADD**, the **Property Key Name** and **Data Type** become permanent. They cannot be changed or deleted later. Ensure the key name is exactly as you want it for your API/integration needs before committing.
</Callout>

***

## 3. How-to guides

### Advanced management of custom attributes

#### Edit a custom attribute

Attributes can be modified after creation to update UI labels, but structural elements remain locked to prevent breaking integrations:

1. **Navigate to Settings**: Go to **Settings** > **Custom Attributes**.
2. Open the kebab menu (three-dot icon) for the desired attribute and select **Edit**.
   * **What you CAN change**: Property name, default value, mandatory toggle, and business entity scoping.
   * **What you CANNOT change**: Property key name and data type.
     <Callout icon="🚧" theme="warn">
       For Products, business entity scoping is disabled as products are global in scope.
     </Callout>

#### Delete a custom attribute

<Callout icon="🚧" theme="warn">
  Definitions **cannot be deleted**. To retire an attribute, we recommend renaming it to `[DEPRECATED] Name` and disabling the **Mandatory** toggle.
</Callout>

***

### Fill in custom attributes on an object

1. Access the slide panel:

   <Callout icon="📚">
     **About the slide panel**: The side-panel interface is used throughout the platform to ensure a consistent experience across the Customer, Contract, and Product modules.  Regardless of which object you are working with, the slide panel functionality remains identical.
   </Callout>

   | Object        | To Create (Navigation)                            | To Edit (Navigation)                                          |
   | :------------ | :------------------------------------------------ | :------------------------------------------------------------ |
   | **Customers** | **Customers** > Click **ADD CUSTOMER** button     | **Customers** > Click row > Click **Edit** button (top right) |
   | **Contracts** | **Contracts** > Click **ADD NEW CONTRACT** button | **Contracts** > Click row > Click **Edit** button (top right) |
   | **Products**  | **Products** > Click **ADD PRODUCT** button       | **Products** >  Click row > Click **Edit** button (top right) |

   <br />
2. **Select business entity:** Choose the entity at the top of the slide panel first. This determines which custom attributes load into the form.
   <Callout icon="🚧" theme="warn">
     For Products, business entity scoping is disabled as products are global in scope.
   </Callout>
3. **Expand custom attributes:** Scroll to the bottom of the slide panel and click the **> Custom Attributes** section header.
4. **Input data:** Fill in your specific fields. Mandatory fields must be completed before the system allows you to save.
5. **Save:** Click **CREATE** (for new records) or **UPDATE** (for edits).

***

## 4. Reference: Technical specifications

### Supported data types

| Data type    | Description                               | Usage example               |
| :----------- | :---------------------------------------- | :-------------------------- |
| **Text**     | Alpha-numeric characters and strings.     | `Internal_Notes`            |
| **Integer**  | Whole numbers without decimals.           | `Employee_Count`            |
| **Boolean**  | True or False values (toggle).            | `Is_Tax_Exempt`             |
| **Array**    | A list of multiple values.                | `Assigned_Tags`             |
| **Float**    | Numbers with decimal points.              | `Discount_Percentage`       |
| **Dropdown** | A pre-defined list of selectable options. | `Region` (APAC, EMEA, AMER) |

### API object mapping

Note that the naming convention for the container object varies depending on the object being accessed.

| Object       | API Field Name      |
| :----------- | :------------------ |
| **Customer** | `custom_data`       |
| **Contract** | `custom_attributes` |
| **Product**  | `custom_attributes` |

<Callout icon="🚧" theme="warn">
  Note: The Customer object uses `custom_data` instead of `custom_attributes`. This is a known inconsistency in the current API and will be aligned in a future release.
</Callout>

### API reference

Use these endpoints to manage the definitions of your custom attributes programmatically.

| Method  | Endpoint                                                                                   |
| :------ | :----------------------------------------------------------------------------------------- |
| `POST`  | [Create definition](https://docs.zenskar.com/reference/create-custom-attribute-definition) |
| `GET`   | [Get definition](https://docs.zenskar.com/reference/get-custom-attribute-definition)       |
| `GET`   | [List definitions](https://docs.zenskar.com/reference/list-custom-attribute-definitions)   |
| `PATCH` | [Update definition](https://docs.zenskar.com/reference/update-custom-attribute-definition) |

### Configuration Metadata

| Field                 | Editable?       | Technical impact                 |
| :-------------------- | :-------------- | :------------------------------- |
| **Property Name**     | ✔ Yes           | None (Label only).               |
| **Property Key Name** | ✘ **Permanent** | **High**: Used in API/Webhooks.  |
| **Data Type**         | ✘ **Permanent** | **High**: Determines validation. |
| **Default Value**     | ✔ Yes           | Low: Affects new records.        |
| **Mandatory**         | ✔ Yes           | Medium: Blocks save if null.     |