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.

GPM item attributes (entity_type = GPM_ITEM)​

GPM item attributes use the same FND EFF model with entity_type = 'GPM_ITEM'. The steps are identical to the DCM example above; the only difference is the entity type and data types used.

Create an insurance category​

POST /persist/v2/fnd_categories
{
  "category_code": "INS_DEFINED_EVENTS",
  "category_name": "Defined Events",
  "entity_type": "GPM_ITEM",
  "description": "Coverage attributes for defined insurable events"
}

Define COVERAGE attributes​

Insurance attributes commonly use the COVERAGE data type, which stores a status code (INCLUDED, EXCLUDED, LIMITED, OPTIONAL, NOT_LISTED) in text_value:

POST /persist/v2/fnd_category_attrs
[
  {
    "category_id": "<INS_DEFINED_EVENTS id>",
    "attr_code": "EV_FIRE",
    "attr_name": "Fire",
    "data_type": "COVERAGE",
    "required": false,
    "display_order": 1
  },
  {
    "category_id": "<INS_DEFINED_EVENTS id>",
    "attr_code": "EV_STORM",
    "attr_name": "Storm Damage",
    "data_type": "COVERAGE",
    "required": false,
    "display_order": 2
  }
]

Assign the category to GPM items​

POST /persist/v2/fnd_category_assignments
{
  "category_id": "<INS_DEFINED_EVENTS id>",
  "entity_type": "GPM_ITEM"
}

Record coverage values for a GPM item​

POST /persist/v2/fnd_category_values
[
  {
    "assignment_id": "<assignment id>",
    "attr_id": "<EV_FIRE attr id>",
    "entity_id": "<gpm item UUID>",
    "text_value": "INCLUDED"
  },
  {
    "assignment_id": "<assignment id>",
    "attr_id": "<EV_STORM attr id>",
    "entity_id": "<gpm item UUID>",
    "text_value": "LIMITED"
  }
]

See GPM Attributes and Values for the full list of COVERAGE status codes and access control rules.