---
alias: user-guide-iot-event-definition-index
tags:
- data platform
description: "This documentation outlines the structure of IoT event definitions for data ingestion"
---

# IoT Event Definition

:lock: IoTEventDefinition.**Show**

## Overview

**IoT Events** serve as the primary mechanism for ingesting data into Data Platform. For more information, see [[tutorials-eventingestion]].

An **IoT Event Definition** is the entity that represents the structure of an event that can be sent to Data Platform via host APIs. It defines the schema of the event, which is used to validate it before it can be accepted by Data Platform.

Each **IoT Event Definition** is internally represented by a JSON document which is the actual information unit stored and passed between Data Platform components.

## Data Access Security

An **IoT Event Definition** can name the objects that restrict access to its event data through their **Data Groups**. When a user reads that data through a **Data Set**, Data Platform returns only the rows that the user can reach.

The `DataGroupsToApplySecurityLevel` property holds this configuration. It maps the name of each object to a value of `true` or `false`:

* `true` - the **Data Group** of that object restricts access to each row.
* `false` - that object does not restrict access.

When more than one object is set to `true`, a user sees a row only when they can reach the **Data Group** of every one of those objects.

Each system **IoT Event Definition** has a default value. It sets the objects of the ISA-95 hierarchy to `false`, and sets the main object of the definition to `true`. For example, the `ResourceLayout` definition sets `Resource` to `true`. It sets `Enterprise`, `Site`, `Facility`, and `Area` to `false`.

The event data records the **Data Group** of every object that the event touches, and this property names the objects that restrict access. A `MaterialOperations` row, for example, carries the **Data Groups** of the **Product**, the **Parent Material**, the **Material**, the **Product Group**, and the **Flow**. The definition sets `Material` to `true`, so the **Data Group** of the **Material** decides whether Data Platform returns the row. The other values stay on the row, and Data Platform does not check them.

![A MaterialOperations row showing five captured Data Groups. Only the Material Data Group is used to filter the row.](../../../../operationguide/system-administration/security/diagrams/cdm_captured_data_groups.drawio.svg)

The restriction removes whole rows. A user who receives a row can read every column of it, including the columns that describe objects set to `false`.

The event data must carry both the `Header_DataGroupRefs` and the `Header_DataGroups` columns for the restriction to apply. If either column is missing, the restriction does not apply, and Data Platform returns every row.

!!! info
    In version 12.0.0, the Create IoT Event Definition wizard does not show this property. To set it, export the IoT Event Definition, edit the property in the exported file, and import the file again. For the procedure, see [Building for Row-Level Security](https://developer.criticalmanufacturing.com/explore/guides/customizations/dataplatform/row-level-security/) in the Developer Portal.

For more information about how Data Platform applies the restriction, see [[operation-guide-data-set-data-access-security|Data Set Data Access Security]].

## Tying Everything Together

```mermaid
graph LR
    A1[IoT Schema] --- Main[IoT Event Definition] --- A3[Data Set]
    A1[IoT Schema] --- N1[IoT Event Schema Properties]
  
classDef mermaid_title color:#000, fill:#fafafa, stroke:#fafafa, stroke-width:0x, font-size:100%, font-weight:200;
classDef mermaid_start color:#000, fill:#fafafa, stroke:#fafafa, color:#fafafa, stroke-width:0x, font-size:100%, visibility: hidden;
classDef mermaid_businessdata color:#000, fill:#65CDE8, stroke:#65CDE8, stroke-width:0px, font-size:100%;
classDef mermaid_nonbusinessdata color:#000, fill:#B7DEE8, stroke:#B7DEE8, stroke-width:0px, font-size:100%;
classDef mermaid_entity color:#000, fill:#FB9F53, stroke:#FB9F53, stroke-width:0px, font-size:100%;
classDef mermaid_entitylinked color:#000, fill:#FCD5B5, stroke:#FCD5B5, stroke-width:0px, font-size:100%;
classDef mermaid_context color:#000, fill:#B9CDE5, stroke:#B9CDE5, stroke-width:0px, font-size:100%;
classDef mermaid_optional color:#000, fill:#B7DEE8, stroke:#65CDE8, stroke-width:1px, font-size:100%, stroke-dasharray: 5 5;
class Main mermaid_entity
class A1,A2,A3,A4,A5,A6,A7,A8,A9,A10 mermaid_businessdata
class L1,L2,L3,L4,L5,L6 mermaid_entitylinked
class C1,C2,C3,C4,C5,C6 mermaid_context
class N1,N2,N3,N4,N5,N6 mermaid_nonbusinessdata
```