Task Templates

Overview

Task templates provide a way for users to easily edit and deploy commonly used tasks with little to no knowledge of tasking required.

Task Templates are tasks that are formatted with special uses of comments and 'constants' to allow the user to edit them from a front end dashboard outside of the task editor.

Although writing a task template requires advanced programming skills, commissioning engineers can use task templates again and again without any additional coding. After selecting a template in the Tasks tab on the device, SB will display a list of configurable properties and parameters on the left and a list of included tasks on the right.

Selecting a task template will overwrite all tasks and events on a device.

Using Task Templates

The Tasks toolbar includes the following icons:

Edit - Open the Task Editor window.
Select Task Template - Open the Select Task Template dialog.
Export to a New Task Template - Save a copy of the current .evt file to the User Task Template Library

The special comment tag //@ must be used in the file.
Copy - Copy the .evt file to the clipboard.
Paste - Paste the copied .evt file from the clipboard.
Clear - Delete the entire task.
Goto - Open the selected task.
Start - Run the selected task from SB.
Stop - Stop a running task.
Pause - Pause a running task.

The Clear button on the task tab cannot be undone and will even remove the default structural task making it harder to write new tasks.

Selecting a Task Template

Click the sb icon task select template Select Task Template icon on the toolbar to open the Select Task Template dialog, then select task template from one of the two libraries:

System Task Templates - Included in SB and updated when a new version of SB is installed.
User Task Templates - Specific to each user and stored on the user’s hard drive as individual .evt files. The default location is:

…\Documents\Dynalite\EnvisionProject\TaskTemplates

You can edit this location in File > Settings > System Settings > Default > Task template library path.

The Select Task Template dialog includes the following functions:

Import - Copies the selected task template to the user task templates library folder.
Export - Saves the selected user or system task template to the specified file location.
Add Folder - Adds a new folder under the selected user task templates library folder.
Rename - Renames the selected user defined task template or task template folder.
Delete - Deletes a user defined task templates or task template folders.
Move - User defined task templates or task template folders can be moved into or out of folders by dragging and dropping.

Templates can be configured to automatically update themselves to the "native" area on the device allowing for swift deployment.
If a task template area parameter is configured to an area outside of its bridge’s logical translation range, the device will show a logical translation error.

Task Template Front End

If the user has selected a task template for a device the input parameters are displayed in the Tasks tab. When a user changes the input parameter values then the task will typically update and recompile automatically.

Once you have loaded a task template onto a device you can now use the fields and/or drop down menus to edit the parameters. This allows you to safely customise the task without the worry that you may be breaking the code by manual editing.

This interface is spearated into two blocks: General and Settings

General Block

The general block tells you information about deploying the task template and includes up to three subsections:

Name - The name of the task template.
Description - The description of what it does.
Configuration Prerequisites - Any requirements on device configurations or logical structure to make the task template work.

Settings Block

The settings block of the task template is where you will actually edit the parameters of the task. It will be broken into one or more sections where you are able to use fields, and drop down menus to customise the task parameters. The name of these sections is configurable as part of the task template and often have names like "Parameters", "Areas", "Task Controls", etc.

While some parameters provide an empty dialog box you can freely enter data, others will show a specific menu of options related to the data type and the project data. For example an "Area" field will open a popup with all the areas on the project. Some parameters are linked such as a channel parameter dropdown changing what is available based on which area is selected.

For basic tasks, when you are done adjusting the settings, you can simply save to device without any additional editing within the task editor. The Configuration Prerequisites in the general block should communicate any other requirements.

Creating a Task Template

Task templates can be created by advanced commissioning engineers or the System Expert team by adding special comment tags into an .evt text file.

Task templates are essentially a set of 'constants' with structured comments.

These comments are proceeded by "//@". This tells system builder that these comments and any proceeding 'constants' should be part of the front end of the task template.

Configuring the General Block

First you set up the general block. It consists of a name, description, and configuration prerequisites. Each of these is a structured comment proceeded by "//@" but are not by a constant, as they are not parameters but merely informational.

For example:

//@ name="The Name of the Task Template"
//@ description="What this template does."
//@ prerequisites="How your devices should be configured, constraints and limitations of the template."

Any restrictions such as maximum number of supported channels or limitations on the type of DyNet messages supported by the task template should be in the configuration prerequisite section of the general block.

Configuring the Settings Block

The parameters in the settings blocks are the part of the task template that show up as drop down menus or fields that can be used to customise the code without manual editing.

Each parameter is a 'constant' and will be proceeded by "#const" as such. However, unlike a normal constant they will additionally have structured comments to tell SB to make them visible outside of the task editor. These comments are proceeded by "//@" like the general block.

That structured comment will contain a description and if necessary additional tags to tell SB what type of data it is or how to display it.

Each parameter can contain a "Category=" tag. This will determine which settings block it is grouped inside of. Parameters will default to the "Parameters" block if this is omitted.

All the available options for formatting Task Templates are demonstrated in the "Sample Task Template" included with System Builder.

Grouping tags for parameters:

Modifier	Description	Category=
Creates/adds the parameter to a group to put this parameter into.	SubCateory=	Creates/adds the parameter to a nested subcategory under a main category.

Modifier

Description

Category=

Creates/adds the parameter to a group to put this parameter into.

SubCateory=

Creates/adds the parameter to a nested subcategory under a main category.

Data Tags for Task Templates:

Tag	Description	Display Type
Boolean	A boolean variable	A drop down menu with True and False as the options. The values will still be processed as 1 & 0.
Area	A logical area	Area field with a change button that opens a popup of available areas. You can also manually enter an area number.
Channel	A logical channel	Channel field with a drop down menu of logical channels in the associated area. You can also manually enter a channel number.
Preset	A logical preset	Preset field with a drop down menu of presets in the associated area. You can also manually enter a preset number.
ChannelLevel	A level percentage	Blank field that can be any whole number from 0-100.
Join	A join value	Hex value with a change button that opens a bit selector popup.
FadeTime	A fade time	Fade time field with up and down arrows for manual adjustments. Can also manually enter a number in seconds.
DelayTime	A delay time	Delay time field with up and down arrows for manual adjustments. Can also manually enter a number in seconds.
Byte	A single byte	Blank field where you can enter a decimal value that can be any number from 0-255. Can also be configured to display hexadecimal values.
Word	A single word	Blank field where you can enter any decimal value from 0-9999.
HighByte	The first half of a split word	A decimal field where you can enter any decimal value from 0-9999. The value is split on the backend into a high and a low byte. Can also be configured to display hexadecimal values.
LowByte	The second half of a split word	This parameter is not displayed but is calculated on the backend by the value in the HightByte field.
HighByteFadeTime	The first half of a 16bit fade time	Fade time field with up and down arrows for manual adjustments. Can also manually enter a number in seconds. The value is split on the backend into a high and a low byte.
ChannelZeroBased	The second half of a 16bit fade time	This parameter is not displayed but is calculated on the backend by the value in the HighByteFadeTime field.
PresetZeroBased	A logical preset	Preset field with a drop down menu of presets in the associated area. You can also manually enter a preset number. On the backend this value is reduced by one.
ChannelLevelInverted	A level percentage	Blank field that can be any whole number from 0-100. On the backend this value is inverted converting it to the proper values for a channel level message.
DeviceName	Device name	Displays a read only value of the device the task template resides in. The value of the constant is unused.
Text	A string of text	Blank field where you can enter any string of quoted or unquoted text.

Tag

Description

Display Type

Boolean

A boolean variable

A drop down menu with True and False as the options. The values will still be processed as 1 & 0.

Area

A logical area

Area field with a change button that opens a popup of available areas. You can also manually enter an area number.

Channel

A logical channel

Channel field with a drop down menu of logical channels in the associated area. You can also manually enter a channel number.

Preset

A logical preset

Preset field with a drop down menu of presets in the associated area. You can also manually enter a preset number.

ChannelLevel

A level percentage

Blank field that can be any whole number from 0-100.

Join

A join value

Hex value with a change button that opens a bit selector popup.

FadeTime

A fade time

Fade time field with up and down arrows for manual adjustments. Can also manually enter a number in seconds.

DelayTime

A delay time

Delay time field with up and down arrows for manual adjustments. Can also manually enter a number in seconds.

Byte

A single byte

Blank field where you can enter a decimal value that can be any number from 0-255. Can also be configured to display hexadecimal values.

Word

A single word

Blank field where you can enter any decimal value from 0-9999.

HighByte

The first half of a split word

A decimal field where you can enter any decimal value from 0-9999. The value is split on the backend into a high and a low byte. Can also be configured to display hexadecimal values.

LowByte

The second half of a split word

This parameter is not displayed but is calculated on the backend by the value in the HightByte field.

HighByteFadeTime

The first half of a 16bit fade time

Fade time field with up and down arrows for manual adjustments. Can also manually enter a number in seconds. The value is split on the backend into a high and a low byte.

ChannelZeroBased

The second half of a 16bit fade time

This parameter is not displayed but is calculated on the backend by the value in the HighByteFadeTime field.

PresetZeroBased

A logical preset

Preset field with a drop down menu of presets in the associated area. You can also manually enter a preset number. On the backend this value is reduced by one.

ChannelLevelInverted

A level percentage

Blank field that can be any whole number from 0-100. On the backend this value is inverted converting it to the proper values for a channel level message.

DeviceName

Device name

Displays a read only value of the device the task template resides in. The value of the constant is unused.

Text

A string of text

Blank field where you can enter any string of quoted or unquoted text.

You can use additional modifiers to automate or adjust some of the way data is displayed. Each of these will have the modifier name followed by "=True", e.g. MatchDevice=True

Additional modifiers for parameters:

Modifier	Parameter Type	Description
MatchDevice	Area	Automatically changes the area parameter to match the devices native area when it is loaded onto a device for the first time. This allows it to auto configure when deployed in new areas.
Hex	Byte or Word	Changes a decimal field to a hexadecimal field.
HighByteParam	LowByte or LowByteFadeTime	Tells the system which highbyte field to reference.
MasterParam	Any	Matches this parameter to the referenced parameter.
ReadOnly	Any	Tells the system this is a read only field and cannot be modified from the front end.

Modifier

Parameter Type

Description

MatchDevice

Area

Automatically changes the area parameter to match the devices native area when it is loaded onto a device for the first time. This allows it to auto configure when deployed in new areas.

Hex

Byte or Word

Changes a decimal field to a hexadecimal field.

HighByteParam

LowByte or LowByteFadeTime

Tells the system which highbyte field to reference.

MasterParam

Any

Matches this parameter to the referenced parameter.

ReadOnly

Any

Tells the system this is a read only field and cannot be modified from the front end.

The input parameter after a special comment tag must be on a single line. Even if it is really long and goes off the screen.

Visibility

Parameters can be made visible or hidden based on the state of other parameters. This is done with the "Visible=" tag.

The "Visible" tag uses some math symbols to determine the logic used to determine visibility.

It can even compare multiple other parameters at once to determine visibility.

Example: Visible="Feature1==True" will hide a parameter if the boolean parameter "Feature1" is set to false.

Visibility modifiers for parameters:

Modifier	Description
==	Make visible if there is a perfect match.
>	Make visible if greater than.
<	Make visible if less than.
>=	Make visible if greater than or equal.
<=	Make visible if less than or equal.
!=	Make visible if not equal.
&&	Compare to an additional parameter. Both must match for visibility.
\|\|	Compare to an additional parameter. Either can match for visibility.

Modifier

Description

Make visible if there is a perfect match.

Make visible if greater than.

Make visible if less than.

Make visible if greater than or equal.

Make visible if less than or equal.

Make visible if not equal.

Compare to an additional parameter. Both must match for visibility.

Compare to an additional parameter. Either can match for visibility.

Task Template Sample

                                //@ name="Task Template Sample"
                                //@ description="This is a sample to show the available task template parameters"

#const Feature10                //@ Name="Enable Feature 1" Type=Boolean Description="This is a boolean parameter that can be used to show or hide other parameters (0=False, 1=True)"

#const PrimaryArea 1            //@ Name="Primary Area" Type=Area MatchDevice=True Description="Areas are displayed as trunk Areas and translated to spur Areas when the task is compiled"

#const PrimaryChannel 1         //@ Name="Primary Channel" Type=Channel AreaParam=PrimaryArea Description="Displays the logical channels for the Area specified in the Primary Area parameter"

#const PrimaryPreset 1          //@ Name="Primary Preset" Type=Preset AreaParam=PrimaryArea Description="Displays the presets for the Area specified in the Primary Area parameter"

#const PrimaryChannelLevel 1    //@ Name="Primary Channel Level" Type=ChannelLevel Description="Displayed as a percentage and converted into inverted channel level when task is compiled"

#const PrimaryJoin 0xFF         //@ Name="Primary Join" Type=Join

#const DecimalByte 1            //@ Name="Decimal Byte" Type=Byte Category="Basic Parameters"

#const HexByte 0xAB             //@ Name="Hex Byte" Type=Byte Hex=True Category="Basic Parameters" Description="Parameters will also be displayed as hex if the value is preceded by an 0x"

#const DecimalWord 1234         //@ Name="Decimal Word" Type=Word Category="Basic Parameters"

#const HexWord 0xABCD           //@ Name="Hex Word" Type=Word Hex=True Category="Basic Parameters" Description="Parameters will also be displayed as hex if the value is preceded by an 0x"

#const SplitWordHigh 0          //@ Type=HighWord Description="Details of the low word are used when displaying the split word"

#const SplitWordLow 7           //@ Name="Split Word" Type=LowWord HighWordParam=SplitWordHigh Category="Basic Parameters" Description="Word parameters in tasks are often required to be split into high and low bytes"

#const SplitWordHighHex 0xAB    //@ Type=HighWord Description="Details of the low word are used when displaying the split word"

#const SplitWordLowHex 0xCD     //@ Name="Split Word Hex" Type=LowWord HighWordParam=SplitWordHighHex Category="Basic Parameters" Description="Word parameters in tasks are often required to be split into high and low bytes"

#const PresetWithoutArea 1      //@ Name="Preset without Area" Type=Preset Category="Basic Parameters" Description="Users can enter any preset and the dropdown will display presets 1 - 16"

#const ChannelWithoutArea 1     //@ Name="Channel without Area" Type=Channel Category="Basic Parameters" Description="Users can enter any channel and the dropdown will display channels 0 - 64"

#const ChannelZeroBased 0           Name="Channel zero based" Type=ChannelZeroBased Category="Basic Parameters" Description="Channels will be converted to be 0 based when task is compiled"

                                // Text not yet supported by the task compiler #const Text Sample //@ Type=Text

#const Feature1NumberChannel 1  //@ Name="Number of Channels (0 - 4)" Type=Byte Category="Feature 1" Visible="Feature1==1"

#const Feature1Area 1           //@ Name="Area" Type=Area Category="Feature 1" Visible="Feature1==1"

#const Feature1Channel1 0       //@ Name="Channel 1" Type=Channel AreaParam=Feature1Area Category="Feature 1" Visible="Feature1==1&&Feature1NumberChannel>=1"

#const Feature1Channel2 1       //@ Name="Channel 2" Type=Channel AreaParam=Feature1Area Category="Feature 1" Visible="Feature1==1&&Feature1NumberChannel>=2"

#const Feature1Channel3 2       //@ Name="Channel 3" Type=Channel AreaParam=Feature1Area Category="Feature 1" Visible="Feature1==1&&Feature1NumberChannel>=3"

#const Feature1Channel4 3       //@ Name="Channel 4" Type=Channel AreaParam=Feature1Area Category="Feature 1" Visible="Feature1==1&&Feature1NumberChannel>=4"

#const Feature1Join 0xFF        //@ Name="Dependent Join Parameter" Type=Join MasterParam=PrimaryJoin Category="Feature 1" Visible="Feature1==1" Description="Value will be automatically updated when the value of the MasterParam is changed"

#const ReadOnly 1               //@ Name="Read Only" Type=Byte Category="Advanced Parameters" ReadOnly=True

#const ReadOnlyExpression 1     //@ Name="Read Only Expression" Type=Byte Category="Advanced Parameters" ReadOnly="(DecimalByte==1&&HexByte!=2)||HexWord<0x12"

#const Visible 1                //@ Name="Visible" Type=Byte Category="Advanced Parameters" Visible=True

#const VisibleExpression 1      //@ Name="Visible Expression" Type=Byte Category="Advanced Parameters" Visible="(DecimalByte==1&&HexByte!=2)||HexWord<0x12"

#const NoName 1                 //@ Category="Advanced Parameters" Description="Name will default to the #const name"

#const NoType 1                 //@ Name="No Type" Category="Advanced Parameters" Description="Type will default to either byte (or word if value is greater than 255)"

#const DependentChannel 1       //@ Name="Dependent Channel" Type=Channel AreaParam=Feature1Area MasterParam=PrimaryChannel Category="Advanced Parameters" Description="Value will be automatically updated when the value of the MasterParam is changed"

            Task1()
            {
                Name="Send Preset"
                Preset(A=PrimaryArea,P=PrimaryPreset,J=PrimaryJoin)
              }