Custom Parts, Workers, Scripts, and Libraries

Description

You can create custom parts, workers, scripts, and libraries to extend the LogicNets runtime for LogicNets Version 7.1 or higher. All custom elements should be placed in the parts, workers, scripts, and library folders of your company installation. For example, if your company installation is named mycompany and the location of your LogicNets installation is c:\logicnets then the locations for custom elements should be as follows: 

• Custom Parts:  c:\logicnets\dat\bnt\mycompany\parts
• Custom (Command-line) Scripts:  c:\logicnets\dat\bnt\mycompany\scripts
• Custom Worker Scripts:  c:\logicnets\dat\bnt\mycompany\workers
• Custom Libraries:  c:\logicnets\dat\bnt\mycompany\libs

The format of a custom part or library is an uncompiled (.lua) or a compiled (.lc) Lua 4 script (https://www.lua.org/manual/4.0/).

Creating and Editing Scripts

When you have access to the server you can create or edit the custom scripts on the server-side. However, there is also a system application callled CustomFileManager that is available to support online editing. If the CustomFileManager tile is not available on your portal page you can ask your system administrator to configure this via AccessManagement.

Offline Mode

Depending on your purchased licenses, you are able to generate an offline package. The system embeds the custom parts, libs, and workers in the offline package during the publish step. The following example shows the use of a custom lib for a calculator. The part triggers a worker, and the worker uses a lib to calculate. To review this example project upload the  custom.zip custom script into your company folder and then import the CustomOfflineTest.zip example project in your workspace.

Note: It is not possible to run commandline custom scripts in offline mode, because the LogicNets commandline execution tool, called Blue, is not available.

Naming Convention

The system can only access custom parts from the package, project, and logicnets that are located in the same company installation. Choosing the right name of a part is important, since the runtime will first look in the system part folders for a part before looking in the custom-part folder. The system will therefore never use a custom part with the same name as a system part. Be aware of the following naming and use conventions for custom parts:

• The custom part name should have as a prefix the company name; for example “mycompany.mypart”.
• The name of the part must match the filename on disk, excluding the .lua or .lc extension.
• The name of the part should be in lower case. Windows is not case-sensitive but Linux can be.
• Do not place custom parts in the company sub-folders of the part folders, but you can place custom libraries in those folders.
• Custom libraries can only be accessed from custom parts, scripts, and workers or from Lua scripts that are executed via the system public lua_script part.

Custom Parts

A custom part implementation must follow a strict structure, and part scripts generally contain 3 sections:

1. Part meta definition: This describes the name of the part and all input and output parameters for that part.
2. Public part declarations: These are the functions used by the LogicNets runtime to execute the part.
3. Private part declarations (optional): These can only be accessed  from other functions in the part itself.

Download the custom_part_template.lua custom-part template as starting point for developing a custom part.

Meta Definition

The runtime uses the part meta-definition to generate a part editor in the Designer. But the system also uses it to validate all parameters set in logicnet models and to generate a data model for the project, so it is an important piece of the part script. The meta-definition contains a collection of tab definitions, and every element (tab definition) will result in a separate tab in the part editor in the Designer. The caption field is the caption of that specified tab. Items is a collection of field definitions where each field is one-part parameter. Different types of part parameters are supported: data-object (for inputs and outputs), text-input, number-input, and dropdown.

Type	Description	Example
Text input	This is a text input parameter.	{ caption= "Name", path = 'name', type='text', data_type = 'text' }
Number input	This is a number input parameter.	{ caption= "Value", path = 'value', type='text', data_type = 'number' }
Data object	This parameter allows the modeler to specify the location of the input or output data-object location in the context. All data-object parameters will be listed in the net and project data model as well.	{ caption= "Result Data Object", path = 'path', type='variable', data_type = 'text' }
Dropdown	This is a dropdown selection input parameter.	{ caption= "Operator", _name="dropdown", path = 'operator', type='option', data_type = 'text', top_choice = { caption = "-", value = "-" }, choices = {{caption = "add", value="+"},{caption = "subtract", value="-"},{caption = "multiply", value="*"},{caption = "divide", value="/"},},},

 

Every part has specific parameter settings:

Field Parameter	Type	Description
path	Text	This is the location of the part parameter in the part declaration.
caption	Text	This is the caption shown in the part editor.
type	[text|option|variable]	This is the type of the part parameter. If left empty the _name must be set.
_name	[dropdown|checkbox]	This is the name of the control used to render the part editor. If left empty the type must be set.
data_type	[number|text|collection|container]	This is the value type of the parameter.
choices	Collection	(Only for option-typed parameters.) This is the list of options for the part. Every option must have a caption and a value.
top_choice	Container	(Only for dropdown parameters.) This is the first option shown in a dropdown list.
on|off	Number	(Only for checkbox parameters.) Value set as the parameter value.

Custom (Command-line) Scripts

You can use custom (command-line) scripts to run scripts from the OS command line; e.g. as part of the Windows Scheduler or as a post-installation script. However, custom scripts can only be started when you have access to the server itself; e.g. ‘c:\logicnets\system\bin\blue.exe custom [companyname] [scriptname] <[parameters]>', c:\logicnets\system\bin\blue.exe custom demo customscript 3 2 *'.

Custom Worker Scripts

You can use custom worker scripts to run lengthy scripts, and they are executed in their own process. Worker processes can be started from a custom part, custom library, or custom command-line script. The custom script that started the worker process can retrieve the result of the worker process or the in-between status.

API

Documentation

The API documentation is part of the designer package and can be accessed via the help link on the server-side script part. You can also update it directly via this URL: 
[[your host]]/packages/designer/documents/scriptapi.html.

Custom Script Examples

customscript.lua: For example, c:\logicnets\system\bin\blue.exe custom [companyname] customscript 3 2 *

Custom Part Examples

mycompany.helloworld.lua
mycompany.calculator.lua

Custom Library Examples

mycompany.calculator.lua

Custom Worker Examples

mycompany.worker.lua: This worker can be triggered via the next custom script example.
customscript_triggersworker.lua: For example, c:\logicnets\system\bin\blue.exe custom [companyname] customscript_triggersworker 3 2 *

Additional Notes

Since Lua is a scripting language that does not include strict type checking, you should follow general rules/guidelines to avoid problems:

• Do not declare or overwrite globals. Use locals by explicitly declaring a variable as a local variable (e.g., local myvar). Globals are shared between all libraries. Although custom parts and libraries are sandboxed (they have an private global context), the execution of a custom part and library uses system declared global functions for proper results.
• Do not use script local variables to share state between different calls of a library or part. Pass all shared data via parameters.