Skip to main content

Product Metadata Configuration

Introduction​

This guide explains how to configure custom metadata for your IoT products and devices in the Data Engine platform. Metadata allows you to track additional product-specific information without modifying the database schema.

Use Cases:

  • Track environmental sensor readings (temperature, humidity, pressure)
  • Store device location information
  • Record maintenance schedules and status
  • Manage custom business-specific attributes
  • Store certification or compliance information

Two-Step Process:

  1. Define the structure at the product level (what fields and types)
  2. Fill in values for each device

Prerequisites​

For Product Metadata Configuration:​

  • Access to the Data Engine Backoffice
  • Superadmin role (only superadmins can define product metadata structures)
  • An existing product in the system

For Device Metadata Values:​

  • Access to the Data Engine Backoffice
  • Authenticated user account
  • A product with defined metadata structure
  • An existing device associated with that product

Step-by-Step Guide​

Part 1: Configure Product Metadata Structure​

This defines what metadata fields will be available for all devices of this product type.

Step 1: Navigate to Product Settings​

  1. Log in to the Data Engine Backoffice as a superadmin
  2. Navigate to Dashboard → Products
  3. Select the product you want to configure
  4. Click on the Settings tab

Step 2: Access Product Metadata Section​

  1. Scroll down to the "Product Metadata Structure" section
  2. This section appears below the main product form
  3. Only visible to users with superadmin role

Step 3: Add Metadata Fields​

  1. Click the "Add Field" button
  2. A new row appears with two inputs:
    • Key: The identifier for this metadata field (e.g., "temperature")
    • Type: The data type for this field

Available Types: | Type | Description | Example Use Case | |------|-------------|------------------| | string | Text data | Location, serial number, description | | number | Numeric data | Temperature, humidity, battery level | | boolean | Yes/No data | Is active, maintenance required, certified | | date | Date data | Last maintenance, installation date, expiry date |

Example Configuration:

Key: temperature     Type: number
Key: location        Type: string
Key: isActive        Type: boolean
Key: lastMaintenance Type: date

Step 4: Save the Structure​

  1. Click "Save" button at the bottom of the form
  2. A success message confirms the metadata structure is saved
  3. All devices of this product can now use these metadata fields

Important Notes:

  • Field keys should be descriptive and use camelCase (e.g., "lastMaintenance")
  • Avoid spaces in keys
  • Choose the most specific type (use number for numeric data, not string)
  • All fields are required when filling device values

Step 5: Modify or Remove Fields (Optional)​

To remove a field:

  1. Click the trash icon (🗑️) next to the field
  2. Click "Save"
  3. Warning: This will remove this field from ALL devices of this product

To modify a field:

  1. Change the key or type directly in the form
  2. Click "Save"
  3. Warning: Changing keys creates a new field and removes the old one from all devices

Part 2: Fill Device Metadata Values​

Once the product metadata structure is defined, you can fill in values for individual devices.

Step 1: Navigate to Device Settings​

  1. Navigate to Dashboard → Devices
  2. Select the device you want to configure
  3. Click on the Settings tab

Step 2: Open Metadata Drawer​

  1. Scroll down to find the "Manage Metadata" button
  2. Click the button
  3. A drawer slides in from the right side showing the metadata form

Step 3: Fill in Metadata Values​

The form automatically generates input fields based on the product's metadata structure:

Field Types and Inputs:

String fields:

  • Text input box
  • Enter any text value
  • Required (cannot be empty)

Number fields:

  • Number input box
  • Enter numeric values only
  • Can include decimals (e.g., 25.5)
  • Validation prevents non-numeric input

Boolean fields:

  • Checkbox
  • Check for "true", uncheck for "false"

Date fields:

  • Date picker
  • Select date from calendar
  • Format: YYYY-MM-DD

Example Values:

temperature: 25.5
location: Building A, Room 101
isActive: ✓ (checked)
lastMaintenance: 2025-11-01

Step 4: Save Metadata Values​

  1. Click the "Save Metadata" button at the bottom of the form
  2. A success toast notification appears
  3. The drawer closes automatically
  4. Values are immediately saved to the database

Step 5: Edit Existing Values (Optional)​

  1. Click "Manage Metadata" button again
  2. Form loads with existing values pre-filled
  3. Modify any values
  4. Click "Save Metadata"
  5. Updated values replace previous ones

Examples​

Example 1: Environmental Sensor Product​

Product Metadata Structure:

Key: temperature     Type: number
Key: humidity        Type: number
Key: pressure        Type: number
Key: location        Type: string
Key: calibrationDate Type: date

Device #1 Values:

temperature: 22.5
humidity: 45.2
pressure: 1013.25
location: Warehouse North, Shelf A3
calibrationDate: 2025-10-15

Device #2 Values:

temperature: 19.8
humidity: 52.0
pressure: 1012.80
location: Warehouse South, Shelf B7
calibrationDate: 2025-10-20

Example 2: Smart Lock Product​

Product Metadata Structure:

Key: serialNumber    Type: string
Key: isActive        Type: boolean
Key: batteryLevel    Type: number
Key: installDate     Type: date
Key: firmwareVersion Type: string

Device Values:

serialNumber: SL-2025-001234
isActive: ✓
batteryLevel: 85
installDate: 2025-01-15
firmwareVersion: 2.3.1

Example 3: GPS Tracker Product​

Product Metadata Structure:

Key: trackingInterval Type: number
Key: geoFenceEnabled  Type: boolean
Key: simCardNumber    Type: string
Key: activationDate   Type: date

Device Values:

trackingInterval: 30
geoFenceEnabled: ✓
simCardNumber: 89012345678901234567
activationDate: 2025-02-01

Best Practices​

Naming Conventions​

Good Key Names:

  • temperature - clear and concise
  • lastMaintenance - descriptive camelCase
  • isActive - boolean prefix
  • batteryLevel - clear measurement

Avoid:

  • temp - too abbreviated
  • Last Maintenance - contains spaces
  • data1 - not descriptive
  • value - too generic

Type Selection​

Choose the right type:

  • Use number for any numeric measurements (temperature, battery level, intervals)
  • Use string for text, IDs, descriptions, and version numbers
  • Use boolean for yes/no, on/off, active/inactive states
  • Use date for timestamps, schedules, and date tracking

Why types matter:

  • Correct type enables proper validation
  • Number fields prevent invalid input
  • Boolean fields provide checkbox UI
  • Date fields provide date picker

Planning Your Structure​

Before creating fields:

  1. List all information you need to track
  2. Group related information
  3. Choose appropriate types
  4. Use consistent naming conventions
  5. Consider future needs (but don't over-engineer)

Recommended limits:

  • Keep metadata fields under 20 for usability
  • Use descriptive but concise key names
  • Group related products with similar structures

Handling Changes​

Adding new fields:

  • Safe to add at any time
  • Existing devices will show empty values for new fields
  • Users must manually fill in values

Removing fields:

  • ⚠️ Permanent action - removes data from ALL devices
  • Cannot be undone
  • Export device data before removing important fields

Changing field types:

  • Creates a new field, removes old one
  • ⚠️ Existing values are lost
  • Instead: create new field with different key, migrate data, then remove old field

Troubleshooting​

Problem: "No metadata fields defined" message appears​

Cause: The product doesn't have a metadata structure defined yet

Solution:

  1. Ensure you're logged in as superadmin
  2. Navigate to product settings
  3. Add metadata fields using "Add Field" button
  4. Save the structure

Problem: Can't see "Product Metadata Structure" section​

Cause: Your account doesn't have superadmin role

Solution:

  • Contact your system administrator to upgrade your role
  • Only superadmins can configure product metadata structures
  • Regular users can only fill device values

Problem: "Manage Metadata" button doesn't appear on device page​

Cause: The product associated with this device doesn't have metadata structure defined

Solution:

  1. First configure the product metadata structure (as superadmin)
  2. Then the button will appear on device settings pages

Problem: Metadata values disappear after saving​

Cause: The keys you entered don't match the product metadata structure (auto-cleanup removed them)

Solution:

  1. Check the product metadata structure
  2. Ensure you're only filling fields that exist in the structure
  3. If you need different fields, update the product structure first (as superadmin)

Problem: Can't save numeric value in number field​

Cause: Value contains non-numeric characters

Solution:

  • Enter numbers only (digits 0-9)
  • Decimals allowed with period (e.g., 25.5)
  • No commas, spaces, or text
  • Negative numbers allowed with minus sign

Problem: Date picker shows wrong format​

Cause: Browser locale settings

Solution:

  • Date is stored in ISO format (YYYY-MM-DD) regardless of display
  • Select date from picker rather than typing
  • System handles conversion automatically

Problem: Checkbox value not saving correctly​

Cause: Form state issue

Solution:

  • Try refreshing the page
  • Re-open the metadata drawer
  • If persists, check browser console for errors

Advanced Topics​

Understanding Auto-Cleanup​

When you save device metadata, the system automatically:

  1. Validates all keys against product metadata structure
  2. Removes any keys not in the product structure
  3. Keeps only valid metadata fields

Example:

  • Product has: ["temperature", "location"]
  • You try to save: ["temperature", "location", "customField"]
  • System saves: ["temperature", "location"] (customField removed)

This ensures data consistency across all devices.

Metadata Storage​

  • All metadata values stored as strings in the database
  • Type information comes from product structure
  • UI converts strings to appropriate types for display
  • Example: "true" (string) displayed as checkbox, "25.5" (string) displayed as number input

API Integration​

If you're integrating with the API directly:

Get device with metadata:

GET /device/:id

Returns device object including metadata array.

Update device metadata:

PUT /device/:id/metadata
Content-Type: application/json

[
  { "key": "temperature", "value": "25.5" },
  { "key": "location", "value": "Building A" }
]

See Product Metadata API Documentation for full details.

Support​

For technical issues or questions: