Using Automation Tasks Library - Map a Task#

A Task has several important sections, the inputs and outputs, the settings, and rules for when the task can be used.

Tasks are an object defined under the array tasks:

{
  "converters": [],
  "tasks": []
}

For more information, see:

Task Metadata - AutomationTask Object#

The Automation Task Object describes a set of root level metadata, that describes the task. This is where you can configures, for example, the task name, description, icon, if it depends on any protocol, and rules of where the task should be shown. All properties should be used in camel case.

Property	Description	Notes
Name	Name of the Task, and will be used to display in the GUI, also used to identify the Runtime Class where the converter code can be located/executed.	Mandatory, String
DisplayName	Name of the task that will be used to display in the GUI, defaults to Name if not defined.	Optional, String
Type	Type of task/Functionality that it provides. Applies only to Control Flow.	Optional, from an enumeration: • Function (Default) • Start • End
Category	Category of the task as it should be placed in the toolbox control (First level). Allows you to group tasks by category in the workflow pane.	Optional, String
Section	Section of the category of the task that should be used to place the button that represents the task. Allows you to create sections inside categories to group tasks.	Optional, String
IconClass	Name of the icon if it was loaded as a font in the GUI.	Optional, String
IconSVG	Data of the SVG to draw the icon in the button and task (will be ignored if an IconClass is set).	Optional, String
IsProtocol	Flag indicating if this task is to be related with a protocol scope.	Optional, Boolean, Defaults to False
IsController	Flag indicating if this task is to be related in a controller scope. Note: It is possible for a task to be usable in both Controller and Protocol scope (Code, EntityInstance, etc.).	Optional, Boolean, Defaults to True
Lifecycle	Flag indicating the current lifecycle of this task.	Optional, from an enumeration: • Productive (Default) • Experimental • Deprecated
LifecycleMessage	Message to display when a task is marked as Deprecated indicating what you should use instead. Note: Only used when Lifecycle != Productive.	Optional, String
DependsOnProtocol	List of protocol drivers (separated by comma “,”) this task depends on to be available. Example: “@criticalmanufacturing/connect-iot-driver-oib”. Leave empty (default) for no dependency which means, available for all protocol drivers.	Optional, List of Strings
DependsOnScope	List of scopes (separated by comma “,”) this task depends on to be available. Leave empty (default) for no dependency which means, available for all scopes.	Optional, List of enumerations: • ConnectIoT • FactoryAutomation • EnterpriseIntegration
DependsOnDesignerScope	List of designer scopes (separated by comma “,”) this task depends on to be available. Leave empty (default) for no dependency which means, available for all designer scopes.	Optional, List of enumerations: • DataFlow • ControlFlow
Designer	Specific settings of the task based on the active designer.	Optional, AutomationTaskDesigner
Settings	Definition of the settings hierarchy and how they should behave and be displayed.	Optional, AutomationTaskSettings
Triggers	Predefined trigger points where scripts can be executed.	Optional, AutomationTaskTriggers (Init, BeforeSave)
Scripts	Library of common/general scripts to be used within the task.	Optional, Map

Using an example for reference.

"tasks": [
    {
      "name": "example",
      "displayName": "Example",
      "isProtocol": false,
      "isController": true,
      "lifecycle": "Experimental",
      "lifecycleMessage": "Task was migrated to use a different visual renderer. It is currently in preview mode.",
      "dependsOnProtocol": [],
      "dependsOnScope": [],
      "category": "System/MES",
      "section": "Actions",
      "dependsOnDesignerScope": [
        "DataFlow"
      ],
      "iconClass": "icon-core-tasks-connect-iot-lg-automationevent"
    }
]

The metadata, describes a task that has a name of example, display name Example and it is currently marked as Experimental. The task will also, have as an icon the automation event, and it will be grouped under the category System/MES in the section Actions. This task is also only for a workflow of type DataFlow.

Task Metadata - AutomationTask Object - Scripting#

There is a common need to use code snippets to provide actions and data transformation of tasks. These can be from removing extra information from objects, to making an HTTP REST request to retrieve information for the task. Hooks for scripting are available at multiple points, and on root level the metadata can describe scripts that can be invoked in any hook, and can also have access to executing scripts on task init and before save.

AutomationTaskTriggers (All properties should be used in camel case):

Property	Description	Notes
Init	Lifecycle hook for the task. Relates to when the task is initialized. Namely when the settings are opened and when the task is dragged and dropped to the designer.	Optional, AutomationTaskScript[]
BeforeSave	Lifecycle hook for the task. Relates to when the task settings are saved.	Optional, AutomationTaskScript[]

AutomationTaskScript Object (All properties should be used in camel case):

Property	Description	Notes
Type	Type of script represented by this entry. `Script` stands for the javascript code, and `Reference` stands for a pointer to a general script located in the “Scripts” section,	Optional, from an enumeration: •Script (default) • Reference • End
Encoding	Indication of the encoding on which the script is provided.	Optional, from an enumeration: •Base64 (default) • Plain • End
Script	The script code or the reference name depending on the type encoded using the Encoding setting.	Mandatory, String or String[]

Examples:

When a script is declared with an encoding Plain, it will support a script of javascript compressed to one line or an array of strings, each being a line of the script. With the use of the tooling provided by Critical Manufacturing for development, CLI and Generator-IoT ⧉, it is possible to declare a script as a reference to a typescript file that holds your script. This will transpile it to javascript and save it in a Base64. As such, the scripts section can be changed by the corresponding base64 of the script.

{            
    "triggers": {
        "init": [
            {
                "type": "Script",
                "encoding": "Plain",
                "script": "this.settings.ruleName = typeof this.settings.ruleName === 'string' ? { Name: this.settings.ruleName } : this.settings.ruleName;"
            }
        ],
        "beforeSave": [
            {
                "type": "Reference",
                "script": "on_before_save"
            }
        ]
    },
    "scripts": {
        "find_iot_rule": "${script(./scripts/get-configurations/find_iot_rule.ts)}",
        "on_before_save": "${script(./scripts/get-configurations/onBeforeSave.ts)}"
    }
}

To be able to create functional scripts, we made available a list of variables that you must consider when developing a script.

Variable name	Usability	Example
this.Cmf	LBOs	Cmf.Foundation.BusinessOrchestration.GenericServiceManagement.OutputObjects.GetObjectsByFilterOutput
this.System	LboService	`System.call(<any>input).then((outputRaw: any) => { ... }`
this.settings	Access to the task settings (key -> value)	`if (this.settings.EnumKey1 == Value1) { ... }'`
this.utilities	Access to Utilities	If you want to strip an AutomationEntity: `this.utilities.stripAutomationEntity(this.settings.baseEntity)`

Task Metadata - AutomationTask Object - Designer#

Due to small differences in the designers, to allow a stricter control on how the task should be designed, a separated section is to be used. Mainly focused in the Control Flow designer.

AutomationTaskDesigner (All properties should be used in camel case):

Property	Description	Notes
	Name/identifier of the designer.	Mandatory, from an enumeration: •ControlFlow (default) • DataFlow • End
	Settings of the designer specific entry.	Mandatory

AutomationTaskDesigner Settings for Control Flow (All properties should be used in camel case):

Property	Description	Notes
Type	Type of task/Functionality that it provides. It is mostly necessary for Control Flow designer.	Optional, from an enumeration: •Function (default) • Start • ControlFlow • End • End
DisplayName	Templated string representing the way the caption of the block should be rendered. Use “{{}}” token to represent an input box based on settings, inputs or outputs. If this field is missing, they system will use the base displayName field.	Optional, String
Branches	Default branches that should be available to the user when the block is rendered.	Optional, AutomationTaskDesignerBranch[]

AutomationTaskDesignerBranch Settings for Control Flow (All properties should be used in camel case):

Property	Description	Notes
Name	Name of the Branch.	Optional, String
DisplayName	Templated string representing the way the caption of the block should be rendered. Use “{{}}” token to represent an input box based on settings, inputs or outputs. If this field is missing, the system will use the base displayName field.	Optional, String
Settings	Default branches that should be available to the user when the block is rendered.	Optional, Setting[]

Example:

{
    "designer": {
        "controlFlow": {
            "type": "ControlFlow",
            "displayName": "Check {{handler.type}} {{handler.condition}}",
            "branches": [
                {
                    "name": "handler",                            
                    "displayName": "",
                    "settings": [
                        {
                            "name": "type",
                            "dataType": "Enum",
                            "defaultValue": "If",
                            "settings": {
                                "enumValues": [
                                    "If"
                                ]
                            }
                        },
                        {
                            "name": "condition",
                            "dataType": "String",
                            "displayName": "",
                            "defaultValue": "{{ true }}",
                            "infoMessage": "Set the condition to validate",
                            "settings": {},
                            "condition": "type != 'Else'"
                        }
                    ]
                },
                {
                    "name": "else",
                    "displayName": "{{type}}",
                    "settings": [
                        {
                            "name": "type",
                            "dataType": "Enum",
                            "defaultValue": "Else",
                            "settings": {
                                "enumValues": [
                                    "Else"
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    }
}