Script Management
Script management is used to maintain runtime scripts for gateways. Scripts can be used for variable data conversion, memory variable calculation, data forwarding templates, dynamic SQL (custom entry statements or table structures), MQTT RPC (MQTT reverse write or query requests), and other scenarios. After saving the script, it must be compiled successfully for related functions to use the latest content.
First, look at terminology
| terminology | On-site understanding |
|---|---|
| script | Internal reusable calculation or conversion logic within the gateway is used to process variable values, generate uploaded content, or handle external requests. |
| Compile | Check whether the script can be run by the gateway. When compilation fails, relevant variables, rules, or forwards will not use new content. |
| Data Conversion | Convert the original equipment values into engineering values required on site, such as scale conversion, unit conversion, and status text conversion. |
| Memory variable scripts | Scripts for calculating internal variables of the gateway, which do not read directly from the PLC but read existing variables or internal states. |
| Dynamic models / templates | Generate uploaded content in formats specified by external systems, such as custom JSON fields, device fields, or alarm fields. |
| Dynamic SQL | Custom statements or table structures written into the database, commonly used in scenarios where fixed-width tables or special field naming are required in projects. |
| MQTT RPC | receives write, query, or control requests from external systems via MQTT, and is parsed and returned by scripts. |
| Complete code | Advanced extension methods. You need to understand C# code and its operational impact; for regular field configurations, it's not recommended to start here. |
Page Entry
After logging into GatewayRuntime Web, click the "Development Configuration → Script Management" menu on the left.
Page Structure
| Area | Description |
|---|---|
| Local Scripts | Maintains scripts saved at the current runtime, supporting addition, editing, compilation, deletion, and batch operations. |
| Loaded script | View scripts that are already accessible to the gateway, displaying information such as name, class, type, and data type in read-only. |
| Name Search | Filter the list by script name. |
| Category Filtering | Filtering by script category, local categories come from saved scripts. |
| Type Filtering | Filtering by script type, such as data transformation, memory variable, MQTT RPC. |
| Tool buttons | Order: Add, batch compile, batch delete, refresh; For the batch button, you need to check the script first. |
List Field
| Field | Description |
|---|---|
| Name | The script's unique name in the system. |
| Classification | Used to organize scripts by business, device, or purpose, which can be empty. |
| Type | Script expression type, which determines the editor template, available inputs, and subsequent references. |
| Update Time | The last time the library was saved or compiled and written. |
| Operations | Edit, compile, or delete the current script. |
Create a new script
Click the 'Add Script' button in the top right corner of the list to open the "New Script" popup.
| Configuration Items | Description |
|---|---|
| Script Name | Required. It is recommended to use English, numbers, and underscores. After saving names, they will be referenced by variables, rules, data forwarding, or RPC configurations, so frequent modifications are not recommended. |
| Script Type | Required. After selecting, a corresponding writing prompt will appear at the bottom of the pop-up window. |
| Classification | Optional. You can select an existing category or directly enter a new category. |
| Description | optional. Record script usage, citation locations, and maintenance precautions. |
| Type Description | Read-only prompt explaining the purpose and writing requirements of the current script type. |
After clicking "OK," the system will create a script and automatically enter the script editor.
Script Type
| Type | Applicable Scenarios |
|---|---|
| Data Conversion | Perform unit conversion, formatting, range mapping, or state transformation on the original values of collected variables. |
| Memory Variables | Compute memory variables, which can be read from other variables to generate derived results. |
| Dynamic Model - Variable Data | Converts variable data into custom upload objects. |
| Dynamic Model - Device Data | Converts device status into a custom upload object. |
| Dynamic Model - Alarm Variable | Transforms alarm data into a custom upload object. |
| Dynamic Model - Plugin Event | Converts plugin event into a custom upload object. |
| Dynamic SQL-* | Customizable inscription logic by variable, device, alarm, or plugin event dimension. |
| MQTT RPC | processes MQTT RPC messages, suitable for write scenarios where message parsing and organizing responses as agreed on the site are required. |
| Complete Code | Write complete C# code suitable for advanced extensions. Before use, confirm the compilation requirements and operational impact. |
Script Editor
The Script Editor includes the top operation bar, code editing area, and bottom information panel.
| Area | Description |
|---|---|
| Back Button | Return to Script List. Unsaved content should be compiled and saved first. |
| Script Name Tag | Displays the current script name, classification, and script type. |
| Compile and save the | main button on the top right. Execute the compilation, and after success, save the script and load the compilation result. |
| Code editing | Maintains C# code, supporting syntax highlighting, undo, redo, and comment switching. |
| Bottom panel | contains tabs for "Compilation," "Node Information," and "Input Parameters." |
Bottom tab
| tab | Description |
|---|---|
| Compilation log | Displays compilation process, errors, warnings, and success information. Clicking on errors or warnings can locate the corresponding code location. |
| Node information | Maintenance script names and categories. After modification, compilation and saving are required for persistence. |
| Input parameters | Only the types "Data Transformation" and "Memory Variable" are displayed. Used to define configurable parameters. |
Enter parameter field
| field | Description |
|---|---|
| Parameter name | Parameter identifier, read by this name in the script. |
| Data type | Parameter value type. For numbers, select integer or decimal type; for switches, select boolean type; for text, select string; for time, select date and time; It should match the actual input values in the script. |
| Initial value | parameter default; if left blank, it is treated by type by default. |
| Description | Parameter usage description for easier subsequent maintenance. |
Compilation Log
After clicking "Compile and Save" at the top, the "Compilation Log" tab at the bottom will display the complete process.
| Log Entries | Description |
|---|---|
| Start Compiling Scripts | Mark the start of this compilation and display the script name. |
| Script Type | Displays the current expression type, such as "Data Transformation". |
| Compilation successful | means the script has been compiled. |
| Compilation Output | Displays compiled output information for on-site troubleshooting of loading issues. |
| Error/Warning Statistics | The number of errors and warnings is displayed on the right side of the bottom panel. |
If compilation fails, the red error should be handled first; Warnings do not necessarily prevent compilation, but it is recommended to address them before going live.
Common Operations
| Operations | Steps |
|---|---|
| Edit Script | Click "Edit" in the list, enter the editor, modify code or parameters, then click "Compile and Save". |
| Single Compilation | Click "Compile" in the list, which is suitable for quickly verifying whether existing scripts can still be compiled. |
| Batch Compilation | Check multiple scripts and click the Batch Compilation button on the toolbar. Commonly used for unified verification after upgrades. |
| Delete the script | Click "Delete" and confirm. Before deletion, confirm that the script is no longer referenced in variables, data forwarding, MQTT RPC, or rules. |
| View Loaded Scripts | Switch to the "Loaded Scripts" tab to confirm the currently available expressions at runtime. |
Use Note:
| Scenarios | Recommended |
|---|---|
| Script Naming | Use stable naming and avoid frequent renaming. Variables, rules, data forwarding, and RPC configurations may be referenced by script name. |
| Production modification | Before modifying the production environment script, export the configuration or record the original script content. |
| Compilation failure | Check the first error in the compilation log; usually, subsequent errors are chain results. |
| The loaded list is empty | First confirm that the script has been successfully compiled, then refresh the "Loaded Scripts" tab. |
| AOT Release | In AOT scenarios, dynamic compilation capabilities may be limited by the release method, so script verification should be completed before release. |