--- alias: user-guide-automation-task-core-customtemplates tags: - automation tasks description: "This documentation explains how to define custom properties, events, and commands within Driver Definitions using JSON templates" --- # Custom Driver Definition :iot-codeexecution-lg:{style="font-size: 100px"} The **Custom Driver Definition** task is used to add properties, events and commands to a Driver Definition through JSON content. ![Custom Driver Templates Parameters](../images/custom_driver_templates_parameters.png) !!! info Prior to MES version 12.0 this task was named "Custom Templates Task". ## Details | Fields | Details | | -------- | --------- | | Scope | Connect IoT | | Workflow | Data flow
Control flow | | `IsProtocol` flag | :material-check:{ style="color: #4DB6AC" } | ## Inputs | Name | Data Type | Description | | -------- | --------- | ------------------ | | Activate | `any` | Activates the task. | ## Outputs | Name | Data Type | Description | | ------- | --------- | ------------------------------------------------------ | | Success | `Boolean` | Emits `true` when the command executes successfully. | | Error | `Error` | Returns error details if the command fails. | ## Settings On the General Tab, you have only the usual settings: ![Custom Driver Templates Settings](../images/custom_driver_templates_settings.png) On the Templates Tab you have the following settings: | Name | Data Type | Default Value | Description | | --------------- | ------------------------------------------------------------ | ------------- | ---------------------------------------- | | Name | `String` | | Template Name. | | Description | `String` | | The description of template value. | | Template | `any` | | Value for the template (JSON) | ![customtemplates_03][customtemplates_03] ## Behavior The **Custom Driver Definition** task is used to add properties, events and commands to a Driver Definition through JSON content. The Templates tab provides an option to create a template and enter JSON in the **Templates** section to define these elements. The templates are stored with the task in the workflow and, each time the task is activated, are registered with the driver of the running connection. The Driver Definition stored in MES is not changed. The template information loads in sequence. When two events share the same name, the most recent event replaces the earlier one. The same rule applies when a single event already exists with the same name. This task streamlines the process by removing the need to manually create properties, events, or commands on the Driver Definition page. Custom events may reference properties that already exist on the Driver Definition: an entry in `EventProperties` can name a persisted property directly, so the template does not need to redeclare it in its `properties` array. ## Remarks We recommend using this task between the **Equipment Configuration** task and the **Driver Command Connect** task. ![customtemplates_04][customtemplates_04] This task should receive a specific structure of data at **Templates** section. That structure is represented at the Example topic. When the JSON of a template is not valid, the task registers none of the templates and emits the error on `Error`. An event that references a property declared neither in the templates nor in the Driver Definition also makes the task emit an error on `Error`. ## Example Structure to add properties, events and commands: ```json { "properties": [ { "Name": "FileName", "Description": "Name of the file identified in the watched directory", "DevicePropertyId": "FileName", "DataType": "String", "IsWritable": false, "IsReadable": true, "AutomationProtocolDataType": "String", "ExtendedData": { "propertyType": "FileName", "identifierType": "None" } }, { "Name": "FullPath", "Description": "Full path of the file found in the directory", "DevicePropertyId": "FullPath", "DataType": "String", "IsWritable": false, "IsReadable": true, "AutomationProtocolDataType": "String", "ExtendedData": { "propertyType": "FullPath", "identifierType": "None" } }, { "Name": "FileSize", "Description": "Size of the file", "DevicePropertyId": "FileSize", "DataType": "Integer", "IsWritable": false, "IsReadable": true, "AutomationProtocolDataType": "Integer", "ExtendedData": { "propertyType": "Size", "identifierType": "None" } }, { "Name": "EndOfFile", "Description": "End of file reached", "DevicePropertyId": "EndOfFile", "DataType": "Boolean", "IsWritable": false, "IsReadable": true, "AutomationProtocolDataType": "Boolean", "ExtendedData": { "propertyType": "EndOfFile", "identifierType": "None" } } ], "events": [ { "Name": "OnNewFile", "Description": "Triggered when the watcher detects a file that was not previously identified appears", "DeviceEventId": "NewFile", "IsEnabled": true, "ExtendedData": { "eventTrigger": "NewFile" }, "EventProperties": [ { "Property": "FileName", "Order": 1, "ExtendedData": {} }, { "Property": "FullPath", "Order": 2, "ExtendedData": {} }, { "Property": "FileSize", "Order": 3, "ExtendedData": {} } ] }, { "Name": "OnFileChanged", "Description": "Triggered when the watcher detects a file that was already identified (and triggered the OnNewFile event), and it was changed in some way", "DeviceEventId": "ChangedFile", "IsEnabled": true, "ExtendedData": { "eventTrigger": "ChangedFile" }, "EventProperties": [ { "Property": "FileName", "Order": 1, "ExtendedData": {} }, { "Property": "FullPath", "Order": 2, "ExtendedData": {} }, { "Property": "FileSize", "Order": 3, "ExtendedData": {} } ] } ], "commands": [ { "Name": "MoreDataRequest", "Description": "After Data is processed, request for the next chunk.", "DeviceCommandId": "MoreDataRequest", "ExtendedData": { "commandType": "MoreDataRequest" }, "Parameters": [ { "Name": "path", "Description": "Path of the file", "Order": 1, "DataType": "String", "AutomationProtocolDataType": "String", "DefaultValue": "", "IsMandatory": true, "ExtendedData": {} } ] }, { "Name": "FileOrDirectoryExists", "Description": "Checks if the path location exists.", "DeviceCommandId": "Exists", "ExtendedData": { "commandType": "Exists" }, "Parameters": [ { "Name": "path", "Description": "Path of the file", "Order": 1, "DataType": "String", "AutomationProtocolDataType": "String", "DefaultValue": "", "IsMandatory": true, "ExtendedData": {} } ] } ] } ``` ### Reusing Driver Definition Properties When the referenced properties already exist on the Driver Definition, the template can define only the events. Each entry in `EventProperties` names the persisted property, and the event uses the data type and extended data defined on the Driver Definition: ```json { "events": [ { "Name": "OnJobCompleted", "Description": "Triggered when the equipment reports a completed job", "DeviceEventId": "JobCompleted", "IsEnabled": true, "ExtendedData": {}, "EventProperties": [ { "Property": "JobId", "Order": 1, "ExtendedData": {} } ] } ] } ``` ## Validation and Intellisense The **Templates** value editor validates the JSON content against a schema bundled with the task, providing inline markers, hover descriptions, and auto-completion (`Ctrl+Space`). The schema ships with the `warning` severity, which means JSON that does not conform to the schema is marked in the editor and can still be saved. The schema accepts two formats: - **Current format** (recommended) - top-level arrays use the plural names `properties`, `events`, and `commands`, and command parameters use the field name `Parameters`. - **Legacy format** - top-level arrays may also use the singular names `property`, `event`, and `command`, and command parameters may be named `CommandParameters`. The editor flags these field names as deprecated, so new templates should use the current format. Schemas can also be attached on a per-task basis from a custom task library. For instructions on attaching a schema to a setting, see [[user-guide-using-automation-tasks-library-settings#json-schema-validation-for-settings|Using Automation Tasks Library Settings]]. For more information on the editor behavior, see [[user-guide-automation-json-schema-validation-in-editors]]. [customtemplates_03]: ../images/customtemplates_03.png [customtemplates_04]: ../images/customtemplates_04.png