Create IoT Event Definition#

IoTEventDefinition.Create

IoTEventDefinition.CreateTemplate

IoTEventDefinition.CreateFromTemplate

Overview#

This operation is used to create an IoT Event Definition.

Setup#

No specific setup is required other than to meet the preconditions of the transaction.

Preconditions#

The IoT Event Definition does not currently exist in the system.

Sequence of Steps#

Step 1: General Data#

Provide a name for the IoT Event Definition.
Naming Restrictions

This name will identify the Event throughout the Data Platform infrastructure, so choose a name that is unique and meaningful for later reference. Furthermore, do not use any of the following characters:
```
! " # $ % & ' ( ) * + , . / : ; < = > ? @ [ \ ] ^ ` { | } ~
```
If special characters are used and a Data Set is created for this IoT Event Definition, the corresponding OData URLs must be percent-encoded to access the data successfully.
Optionally, provide a description of the IoT Event Definition.
Select the IoT Event Definition type. The available values are described in the IoTEventDefinitionType Lookup Table. This value can later be used to group event types into categories.
Choose the Retention Time in days. This parameter defines how long the event data will be stored in Kafka. If you are unsure about the value to use, set the retention time to 0 or a negative value. This will retain the event data indefinitely.
Select the Scope:
- Data Platform - allowing usage within the context of Data Platform tasks and workflows.
- Enterprise Integration - allowing the execution of workflows in response to events of this Scope that are posted by Integration Entries.
- Equipment Data - useful when dealing with Equipment events that are part of CDM/System (including Telemetry), which automatically sets to true the Create Data Set option.
- Factory Automation - allowing the creation and execution of automation jobs to be managed in the Monitoring section of the Automation panel.
- General - allowing usage within the realm of the Automation Controller and Connect IoT.
Select the Folder where this information will be stored.
Invalid Characters

When creating a new Folder to store an IoT Event Definition, do not use any of the following characters:
```
! " # $ % & ' ( ) * + , . / : ; < = > ? @ [ \ ] ^ ` { | } ~
```
If special characters are used and a Data Set is created for this IoT Event Definition, the corresponding OData URLs must be percent-encoded to access the data successfully.
Select the Owner Type. The available options are: App, Role, and User.
Depending on the Owner Type selected, you must now select either an App, a Role or a User.
If required, choose to create a Data Set. If this flag is checked, a dataset will be created for the data ingested with this event; always check this flag if direct access to the data will be required in the future (for example, Data Collections).
Select Next to choose the properties for the IoT Event Definition.

Step 2: Properties#

This step captures the actual structure of the IoT Event Definition. Here you will define the individual properties of the event.

On the left side panel, add as many properties as desired (select in the dropdown located on the top right of the grid to add, and to remove). The button allows adding top-level properties or, in case the property data type is IoT Schema, sub-properties of the main property.
For each property, specify:
- Name - This name must match the Event JSON document. It will be used internally to identify each property.
  
  Reserved Property Name Prefixes
  
  Do not use the prefixes AppProperties and SysProperties when creating new properties. These prefixes are reserved for out-of-the-box system properties and using them may cause conflicts or unexpected behavior.
- Friendly Name - Alternative name to identify the property.
- Description - Property description.
- Array - Identifies this property as an array of objects.
- Mandatory - Identifies if the property is mandatory. If set to true, this information will be used to validate all the arriving events.
- Indexed - Defines whether the property can be searched and queried. Furthermore, if true and you opted to create a Data Set, the property will become part of the key that uniquely identifies an event. Events with the same key will be automatically deduplicated; if the client sends many events with the same key, then only the event that was sent last will be saved in the data set.
  
  Info
  
  Array and Indexed properties are mutually exclusive.
- Data Type - The data type of the property (mandatory, as an enumeration), which maps to the following JSON types (shown in parentheses):
  - Boolean (integer)
  - Date (date)
  - DateTime (date-time)
  - Decimal (number)
  - EntityType (object) - Refers to an Entity Type object. In case of a versioned Entity Type, it refers to the Definition. The content of this property will be used by the enrichment process to map MES information to the original event's document.
  - File (string) - Stores the File Id.
  - Integer (integer)
  - IoT Schema (object) - Allows creating sub-groups of properties.
  - Long (sting)
  - String (string)
  - Time (time)
  - URL (uri)
- User Identifier - If enabled, it will show the user identity in reports built using this IoT Event Definition. This option is only available if the Data Type is set to String.
  User Identifier Behavior
  
  The User Identifier flag takes effect only when all of the following conditions are met:
  - There is a Data Set associated with the IoT Event Definition.
  - The CmfDataSet.IdentityAccess security feature is enabled (this is the default setting). For more information, see Features.
  - When operating in EDP mode, the AppProperties_DataSilo is included in the OData selected fields. This requirement applies only to CDM and DWH tables and is not required for ODS or ODS tables.
- Default Value - Specifies the default value of the property. If not present in the received event, this value will be set by the event validation process.
- Minimum - The minimum value for data types of type integer. The event will be rejected if this value is less than what is defined.
- Minimum - The maximum value for data types of type integer. The event will be rejected if this value is exceeded.
- Min Length - Used to check the minimum length of a property of type string.
- Max Length - Used to check the maximum length of a property of type string.
- Pattern - For scalar types of type string, the pattern, for example: ^[A-Za-z]*@gmail.com$. This must be a valid Java regular expression.
- Max File Size - For scalar types of type File, the maximum accepted file size.
- Max File Scale - Maximum file size scale if the Data Type is file (Kilobytes, Megabytes, Gigabytes).
- File Content Type - Used to select the File type the system will read. The system is able to read the following types: JSON, STEP, octet-stream, XML, CSV, excel among others.
- Shared - For IoT Schema data types. Setting an IoT Schema as shared, informs the system to create as IoT Schema object. This is useful to share JSON document definitions between Events (for example, Location definitions).

Add properties from an existing IoT Schema by choosing Copy Schema Properties from the dropdown and selecting the desired IoT Schema:

Alternatively, import a JSON or CSV schema by choosing Import JSON from the same dropdown:

Warning

If a schema is imported, a sanity check is strongly recommended as some property types can be incorrectly inferred (for example, integer instead of decimal).

Both JSON and IoT Schema are also available to elect in data type.

Select Create to complete the operation and the new IoT Event Definition will be created. If Create Data Set was checked, a Data Set with the same name and folder path will also be created in the IoTEvents root folder, which you can navigate in the Data Sets page. This Data Set will store all the data posted via this event, and make it immediately available for consumption (with OData, Grafana, among others).