Custom Driver Definition#
The Custom Driver Definition task is used to add properties, events and commands to a Driver Definition through JSON content.
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 |
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:
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) |
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. 
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:
{
"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:
{
"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, andcommands, and command parameters use the field nameParameters. - Legacy format - top-level arrays may also use the singular names
property,event, andcommand, and command parameters may be namedCommandParameters. 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 Using Automation Tasks Library Settings.
For more information on the editor behavior, see JSON Schema Validation in Editors.