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#

1. Provide a name for the IoT Event Definition.

   Warning

   This name will identify the Event throughout the Data Platform infrastructure. Use a name that is meaningful for later reference.

2. Optionally, provide a description of the IoT Event Definition.

3. 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.
4. Choose the Time to Live (TTL) in days. This is an optional parameter that informs you of the number of days this event will be stored in the Data Platform. If left blank (default), the system will store this event indefinitely (this is the recommended setting).
5. 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.
6. Select the Folder where this information will be stored.
7. Select the Owner Type. The available options are: App, Role, and User.
8. Depending on the Owner Type selected, you must now select either an App, a Role or a User.
9. 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).
10. 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.

1. 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.

2. For each property, specify:

   • Name - This name must match the Event JSON document. It will be used internally to identify each property.
   • 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)
   • 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).

There is the possibility of adding the properties of an existing IoT Schema by selecting the Copy Schema Properties option in the dropdown by selecting an IoT Schema from the list.

In alternative, there is also the possibility of importing a JSON or CSV definition of the desired schema by selecting the Import JSON option in the same dropdown.

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).