Overview

This guide walks you through managing custom properties in the N-central platform. The Custom Properties API allows you to create, retrieve, and manage property configurations across your organization hierarchy and devices. You'll learn how to:

1. Manage organization unit custom properties
2. Handle device custom properties
3. Configure default property settings
4. Set up property propagation rules
5. Work with different property types

Organization Unit Custom Properties

Get Organization Unit Property

Retrieve a specific custom property for an organization unit.

Request

GET /api/org-units/{orgUnitId}/custom-properties/{propertyId}
Authorization: Bearer <YOUR_JWT_HERE>

Response

{
    "propertyId": 1624300373,
    "propertyName": "Location",
    "propertyType": "TEXT",
    "value": "Head Office",
    "enumeratedValueList": []
}

List Organization Unit Properties

Retrieve all custom properties for an organization unit.

Request

GET /api/org-units/{orgUnitId}/custom-properties
Authorization: Bearer <YOUR_JWT_HERE>

Parameters:

• pageNumber (optional): Page number for pagination
• pageSize (optional): Items per page
• sortBy (optional): Field to sort by
• sortOrder (optional): ASC or DESC

Response

{
    "data": [
        {
            "propertyId": 1624300373,
            "propertyName": "Location",
            "propertyType": "TEXT",
            "value": "Head Office"
        }
    ],
    "totalItems": 1
}

Update Organization Unit Property

Modify an existing organization unit custom property.

Request

PUT /api/org-units/{orgUnitId}/custom-properties/{propertyId}
Authorization: Bearer <YOUR_JWT_HERE>
Content-Type: application/json

{
    "value": "New Value"
}

Response

{
    "_warnings": [
        "Property Type is ignored during update."
    ]
}

Device Custom Properties

Get Device Property

Retrieve a specific custom property for a device.

Request

GET /api/devices/{deviceId}/custom-properties/{propertyId}
Authorization: Bearer <YOUR_JWT_HERE>

Response

{
    "propertyId": 1624300373,
    "propertyName": "ConfigSetting",
    "propertyType": "TEXT",
    "value": "Standard"
}

List Device Properties

Retrieve all custom properties for a device.

Request

GET /api/devices/{deviceId}/custom-properties
Authorization: Bearer <YOUR_JWT_HERE>

Response

{
    "data": [
        {
            "propertyId": 1624300373,
            "propertyName": "ConfigSetting",
            "propertyType": "TEXT",
            "value": "Standard"
        }
    ],
    "totalItems": 1
}

Update Device Property

Modify a device custom property.

Request

PUT /api/devices/{deviceId}/custom-properties/{propertyId}
Authorization: Bearer <YOUR_JWT_HERE>
Content-Type: application/json

{
    "value": "Updated Value"
}

Response

{
    "_warnings": [
        "Property Type is ignored during update."
    ]
}

Default Custom Properties

Get Default Property

Retrieve default custom property settings.

Request

GET /api/org-units/{orgUnitId}/org-custom-property-defaults/{propertyId}
Authorization: Bearer <YOUR_JWT_HERE>

Response

{
    "propertyId": 1624300373,
    "propertyName": "StandardConfig",
    "orgUnitId": 11090,
    "propertyType": "TEXT",
    "value": "Default Value",
    "selectedOrgUnitIds": [11089, 11090]
}

Update Default Property

Modify default property settings and propagation rules.

Request

PUT /api/org-units/{orgUnitId}/org-custom-property-defaults
Authorization: Bearer <YOUR_JWT_HERE>
Content-Type: application/json

{
    "propertyId": 186156786,
    "propertyName": "StandardConfig",
    "propagationType": "SERVICE_ORGANIZATION_ONLY",
    "defaultValue": "Standard Setting",
    "propagate": false,
    "selectedOrgUnitIds": [209, 210]
}

A successful update returns a 204 status code.

Property Types and Configuration

Property Types

All custom properties must be one of the following types:

1. TEXT

   • Standard text values
   • No special formatting required
   • Most flexible type for general configuration

2. HTML_LINK

   • URLs and web resources
   • Must be valid URL format
   • Used for reference links and resources

3. DATE

   • Date values
   • Must use valid date format
   • Useful for scheduling and tracking

4. ENUMERATED

   • Predefined value sets
   • Values must match enumerated list
   • Good for standardized options

5. PASSWORD

   • Secure credential storage
   • Special handling for sensitive data
   • Enhanced security measures

Propagation Types

When configuring default properties, available propagation types are:

• NO_PROPAGATION

  • Values apply only to specified level
  • No inheritance by child units

• SERVICE_ORGANIZATION_ONLY

  • Propagates to service organization level
  • Doesn't affect lower levels

• SERVICE_ORGANIZATION_AND_CUSTOMER_AND_SITE

  • Full hierarchy propagation
  • Affects all levels below

• CUSTOMER_AND_SITE

  • Propagates to customer and site levels
  • Skips service organization level

• SITE_ONLY

  • Applies only to site level
  • No upward or downward propagation

Error Handling

The API uses standard HTTP status codes with detailed error responses:

Status Codes

• 200: Success
• 204: Success (no content)
• 400: Invalid request
• 401: Authentication failed
• 403: Insufficient permissions
• 404: Resource not found
• 429: Rate limit exceeded
• 500: Server error

Error Response Format

{
    "status": 400,
    "message": "Invalid request format",
    "errors": [
        {
            "field": "propertyValue",
            "message": "Value exceeds maximum length"
        }
    ]
}