Guides
GuidesAPI ReferenceRecipesChangelog
Start typing to search…

Custom Properties & Configuration APIs Overview

N-central's Custom Properties APIs enable you to manage and customize property configurations across your organization's hierarchy. These APIs allow you to create, retrieve, and update custom properties for both devices and organization units, providing flexible configuration management capabilities.

API Methods

Organization Unit Custom Properties

Manage custom properties at the organization unit level, allowing you to set and maintain configuration values that apply to entire organizational segments.

Key Operations

  • Get Property (GET /api/org-units/{orgUnitId}/custom-properties/{propertyId}): Retrieve specific custom property details
  • Update Property (PUT /api/org-units/{orgUnitId}/custom-properties/{propertyId}): Modify existing custom property values
  • List Properties (GET /api/org-units/{orgUnitId}/custom-properties): Retrieve all custom properties for an organization unit

Property Types

  • TEXT: Standard text values
  • HTML_LINK: URL and web resource links
  • DATE: Date-based properties
  • ENUMERATED: Properties with predefined value sets
  • PASSWORD: Secure credential storage

Device Custom Properties

Configure and manage properties specific to individual devices, enabling granular control over device-level configurations.

Key Operations

  • Get Property (GET /api/devices/{deviceId}/custom-properties/{propertyId}): Retrieve device-specific property details
  • Update Property (PUT /api/devices/{deviceId}/custom-properties/{propertyId}): Modify device property values
  • List Properties (GET /api/devices/{deviceId}/custom-properties): Get all custom properties for a device

Default Custom Properties

Manage default property values and propagation rules across your organization hierarchy.

Key Operations

  • Get Default Property (GET /api/org-units/{orgUnitId}/org-custom-property-defaults/{propertyId}): Retrieve default property configurations
  • Update Default Property (PUT /api/org-units/{orgUnitId}/org-custom-property-defaults): Modify default property settings

Propagation Types

  • NO_PROPAGATION: Values apply only to the specified level
  • SERVICE_ORGANIZATION_ONLY: Propagate to service organization level
  • CUSTOMER_AND_SITE: Propagate to both customer and site levels
  • SITE_ONLY: Apply only to site level entities

Key Features

Flexible Property Types

Supports multiple property types (HTML_LINK, TEXT, DATE, ENUMERATED, PASSWORD) with comprehensive validation and type-specific handling. Each type maintains its own data format and validation rules.

Customizable Propagation Control

Offers granular control over how properties propagate through your organization with multiple propagation types:

  • Service organization levels
  • Customer and site combinations
  • Individual level control
  • Selective propagation to specific organizational units

Comprehensive Value Management

Manages both default and custom values for properties with:

  • Default value specification
  • Enumerated value list support for properties requiring specific options
  • Support for organization-wide property defaults
  • Device-specific property customization

Implementation Example

// Retrieve a device custom property
GET /api/devices/123456/custom-properties/789
Authorization: Bearer <YOUR_TOKEN>

// Response
{
    "propertyId": 789,
    "propertyName": "Location",
    "propertyType": "TEXT",
    "value": "Data Center 1"
}

// Update an organization unit property
PUT /api/org-units/456/custom-properties/789
Authorization: Bearer <YOUR_TOKEN>
Content-Type: application/json

{
    "value": "New Configuration Value"
}

Custom Properties and Propagation details (Org Units)

This section will describe the functionality of setting custom properties for org units via APIs and map it to the functionality seen in the UI.

Changing the default value of the custom property for the Org where the property was defined and all its descendants

N-central UI

Go to the ORG where the property was defined → Administration → Custom Properties

Select the property

  • Change the Default Value/Text to update the value.
  • Deselecting anything from the Customer/Sites will remove the property from that Org Unit, while selecting something that was not will add the property to that Org Unit
  • After making the changes choose Save and Propagate to change the value to all Org Units. Choosing Save will only change the value for this Org Unit

N-central REST API

The equivalent API operation is PUT api/org-units/{orgUnitId}/org-custom-property-defaults To use the API first get the property you want to change using GET api/org-units/{orgUnitId}/org-custom-property-defaults/{propertyId}

Using the output of get populate the body of PUT

  • Having propagate on true will update the value to all descendants, and setting it on false will only update the value for the org Unit where the property was defined
  • Removing ids from selectedOrgUnitIds is the same as deselecting from Customers/Sites in the UI, which means it will remove the property from the ids you remove from the list
  • Setting a different orgUnitId than the one where the property was defined will not do anything. It will ignore the value and take the right value from the DB
  • It is not possible to update the default value only for certain children and their descendants using this API

Updating the default value for a child and its descendants

N-central UI

Go to the child Org (in the example the property is defined at system, and I want to change for a SO and its children) → administration → custom properties

The properties that are not defined at this level will have the selection box disabled but you can still click on the name to edit its value.

  • The only input that can be changed here is the default value. Once changed you can choose to save it only for this org by clicking save or propagate it to all its descendants by clicking save and propagate.
  • This action will not update the default value for the parent which in this case is system

N-central REST API

The API Service currently does not support this action

Update the value of a property for a single OrgUnit

N-central UI

Go to the parent of the Org for which you want to change the value – for my example it is system. Go to the list of Service Organizations/Customers/Sites

Click on the Org you want to change the value for and go to Custom Properties

You can change the value of any property here and it will only change it for this Org, there is no possibility to propagate the change

N-central REST API

To update the value of the property for an Org the API used is PUT api/org-units/{orgUnitId}/custom-properties/{propertyId}. For this you only need the orgUnitId and the propertyId

It is possible to use this API call to change the value of a property for any Org Unit you need The change cannot be propagated

Notes

If a Custom Property is of type PASSWORD, the GET endpoints that return information on custom properties will NOT return the actual password value for security reasons. The value will be left blank in the response.

Updated 27 days ago