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:

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:

   
   

   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.	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.

📚

When you open the create or edit side panel for a Customer, Contract, or Product object 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.

❗️

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.

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.

     🚧

     For Products, business entity scoping is disabled as products are global in scope.

Delete a custom attribute

🚧

Definitions cannot be deleted. To retire an attribute, we recommend renaming it to [DEPRECATED] Name and disabling the Mandatory toggle.

Fill in custom attributes on an object

1. Access the slide panel:

   📚

   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.

   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)

   
   

2. Select business entity: Choose the entity at the top of the slide panel first. This determines which custom attributes load into the form.

   🚧

   For Products, business entity scoping is disabled as products are global in scope.

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

API object mapping

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

🚧

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.

API reference

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

Configuration Metadata