Skip to main content

How to Configure Extensible Fields

This guide walks through creating categories, defining attributes, assigning them to entity types, recording values, and querying extensible field data. It uses a DCM (Device Control Management) vending machine as the example entity.

For background on how extensible fields work, see the Extensible Fields explanation.

Create a category​

Insert a row into fnd_categories to define a named group of attributes for vending machines:

POST /persist/v2/fnd_categories
{
  "category_code": "DCM_VENDING",
  "category_name": "Vending Machine Configuration",
  "entity_type": "DCM_DEVICE",
  "description": "Physical and operational attributes for vending machine devices"
}

Define attributes​

Insert rows into fnd_category_attrs to declare what fields this category provides:

POST /persist/v2/fnd_category_attrs
[
  {
    "category_id": "<DCM_VENDING id>",
    "attr_code": "MAX_SLOTS",
    "attr_name": "Maximum Slots",
    "data_type": "NUMBER",
    "required": true,
    "display_order": 1
  },
  {
    "category_id": "<DCM_VENDING id>",
    "attr_code": "TEMP_RANGE",
    "attr_name": "Temperature Range",
    "data_type": "TEXT",
    "required": false,
    "display_order": 2
  },
  {
    "category_id": "<DCM_VENDING id>",
    "attr_code": "ACCEPTS_CASH",
    "attr_name": "Accepts Cash",
    "data_type": "BOOLEAN",
    "required": true,
    "default_value": "false",
    "display_order": 3
  },
  {
    "category_id": "<DCM_VENDING id>",
    "attr_code": "POWER_CLASS",
    "attr_name": "Power Class",
    "data_type": "LOOKUP",
    "lookup_type": "DCM_POWER_CLASS",
    "required": false,
    "display_order": 4
  }
]

Assign the category to an entity type​

Insert a row into fnd_category_assignments to make the DCM_VENDING category available on all DCM_DEVICE entities of subtype VENDING_MACHINE:

POST /persist/v2/fnd_category_assignments
{
  "category_id": "<DCM_VENDING id>",
  "entity_type": "DCM_DEVICE",
  "entity_subtype": "VENDING_MACHINE"
}

To apply the category to all device types regardless of subtype, omit entity_subtype.

Record values for a specific entity​

Once assigned, record values in fnd_category_values for a specific device (e.g. device DCM-00123):

POST /persist/v2/fnd_category_values
[
  {
    "assignment_id": "<assignment id>",
    "attr_id": "<MAX_SLOTS attr id>",
    "entity_id": "DCM-00123",
    "number_value": 30
  },
  {
    "assignment_id": "<assignment id>",
    "attr_id": "<TEMP_RANGE attr id>",
    "entity_id": "DCM-00123",
    "text_value": "2-8°C"
  },
  {
    "assignment_id": "<assignment id>",
    "attr_id": "<ACCEPTS_CASH attr id>",
    "entity_id": "DCM-00123",
    "boolean_value": true
  },
  {
    "assignment_id": "<assignment id>",
    "attr_id": "<POWER_CLASS attr id>",
    "entity_id": "DCM-00123",
    "text_value": "CLASS_A"
  }
]

Query extensible field data​

Retrieve all categories for an entity type​

To find all categories applicable to DCM devices:

GET /persist/v2/fnd_categories?entity_type=eq.DCM_DEVICE&active=eq.true

Retrieve attribute definitions for a category​

To list all attributes defined for the DCM_VENDING category:

GET /persist/v2/fnd_category_attrs?category_id=eq.<DCM_VENDING id>&order=display_order.asc

Retrieve values for a specific entity​

To read all extensible field values for device DCM-00123:

GET /persist/v2/fnd_category_values?entity_id=eq.DCM-00123

Join values with attribute definitions​

To retrieve values alongside their human-readable attribute names and data types, join fnd_category_values with fnd_category_attrs:

GET /persist/v2/fnd_category_values?entity_id=eq.DCM-00123&select=*,attr:fnd_category_attrs(attr_code,attr_name,data_type)

This returns each value record enriched with the attribute metadata, making it straightforward to render a custom attributes panel without a separate request for the definitions.

Retrieve values for multiple entities of the same type​

To retrieve extensible fields for all devices assigned to the DCM_VENDING category:

GET /persist/v2/fnd_category_values?assignment_id=eq.<assignment id>&select=entity_id,attr_id,text_value,number_value,date_value,boolean_value

Filter by entity_id within that result set to group values by device.