Blockly Scripting

Blockly is a way to write scripts in Web Port in simplified way. The scripts are generated by connecting puzzle pieces together, were each piece represent logic or bigger functionality. The editor works by drag and drop from a block library to a workspace which is then saved and used to generate the actual code.

Overview

Blockly is currently available for Call scripts, Looped scripts and Triggered scripts. To use Blockly for scripting select it from the top menu after opening a new or existing script. To return to the regular script view and see the resulting code, click the Script icon in the top menu. Se image below.

Obs

When first opening a script it begins with the regular code view.

Interface layout

When opening the Blockly view the interface is consists of a top menu bar, a block library to the left and a workspace for creating the puzzle. The top menu have a few buttons seen below. The Save and Cancel buttons are hidden when there is nothing to save.

The other buttons have the following functionality:

• Run Executes the script and returns the result in a green message popup in the bottom right corner. If an exception occurs a red popup is shown with the error message.
• XML Opens a side menu to the right with the XML-code that makes up the puzzle shown in the workspace. This code can be copied and stored as a template. To restore a previous workspace paste the corresponding XML-code to the input in the side menu and press save. The workspace should now be updated with the puzzle.
• Debug Opens a side menu with all debug messages from the latest run of the script. New debug messages can be added by using the debug block under Common.

Library

The library is shown to the left and includes both basic programming blocks as well as Web Port specific blocks to interact with the system, for example tags and trend. There are also blocks to connect and request data from APIs and work with data structures such as Json. Blocks are organized into categories to make it easy to group blocks of the same type. The categories can in some cases be nested with sub categories. See further down for documentation of the different blocks.

 

Workspace

The workspace is where the puzzle is built which in turn generates the code. To add blocks to the workspace, open a category in the library and drag the desired block to the workspace. Some block can be connected either by stacking them or joining them. In some cases only a specific type of block can be connected. Blocks can be reorganized by dragging them around which will also impact how the resulting code is structured. To remove a block drag it to the recycle bin. It is possible to zoom in (+) and out (-) as well as pan the workspace. This can be done either with touch or by using the mouse and scroll wheel.

Code generation

The code generation is done when the workspace is saved. To see the result navigate to the script view by using the top menu. The resulting script is inserted between two comment lines as shown below. It is possible to combine generated code with custom code by adding it outside of the blockly area.

Custom code can go here ...

// <blockly>

Code generated by Blockly goes here. Code that is edited from script view will be replaced.

// </blockly>

Custom code can go here ...

Running code

Debug

General blocks

Logic

The logic blocks are used for comparisons and validations. For example to check if something is true of false or greater than another value. The if block can be expanded to also support else if and else by clicking the cog wheel.  The test block can be used to return different results on the left side depending on if the test is true or false.

Loops

The loop blocks are used when something should be repeated. There are different blocks that can be used to repeat something a certain number of times or for each item in a list. The break out block us used to exit a loop before completion. Blocks that should be executed for each iteration of the loop is placed inside the do area.

Math

The math blocks are used to work with numbers and preform mathematical operations. Many blocks have drop downs for different operations. Many of the block can be combined with each other to create more complex mathematical calculations.  The math library also includes a random number generator.

Text

The text category includes blocks for working with text (strings). There are also some string comparisons that can be used together with logic blocks. Obs Print and prompt are not usable with scripts in Web Port since the scripts are run on the back-end and do not enable user interaction.

Lists

The list category includes blocks for creating and working with lists. There are also blocks to select sub-sets of lists, splitting text to a list as well as sorting. Is empty can be used together with logic blocks to check if a list is empty.

Colour

These blocks can be used to create and work with colours. The values for red, green and blue are from 0-255.

Variables

Variables are a very common blocks and a foundation in many scripts. They are used to store values which can then be used together with may other blocks. Before a variable can be used it must be created. After that they can be set or changed using the respective blocks. Each created variable will appear in the same way as the cmd block to the left.

Functions

Functions can be used when the same code needs to be called from multiple locations. A function can take input parameters and / or return a value back. Use the cog wheel to configure the function according the the requirements.

Web Port blocks

Tags

Tags are central in Web Port and these blocks makes it easy to read, write, copy or loop through tags.

Trend

The above block is used to insert data into the trend database. The blocks first input is the value to be stored and can either be a fixed value or a variable. The second input is the name of the tag to insert the value for and the last input is an optional date time (if nothing is changed the current time is used).

Date / Time

The above blocks are used to work with date, time and timespans. There are blocks to convert to and from Unix timestamp as well as parsing date time strings.

Json

Json is a common data format and is often received from web services and APIs. These blocks can be used to parse the Json string and generate an appropriate Json datatype (JObject, JArray or JToken). JObjects are surrounded by {} JArrays are surrounded by [] JTokens can be any type of Json datatype. To get a value use the select token to filter the desired value from the Json input. It is also possible to iterate through all objects with the for loop, which also takes a filter expression. For more information about filtering and the different Json data types see Newtonsoft documentation.

Requests

HTTP

These blocks are used to make web requests. Most common are requests to RESTful APIs that return Json data as a response. The HTTP GET block is used for simple request where all parameters are configured in the Url. For more complex calls or for posting data to the web server use the HTTP POST block. The content is added to the right side of the block and the content type is set by the optional field. It is also possible to provide authentication for both blocks. For both HTTP GET and POST the HTTP Helper block is required.

APIs

KIONA/Spot Price - Spot Price for Electricity

The block for Spot Price needs two helper blocks

• HTTP Helper located under Requests
• Kiona API_Helper located under APIs/KIONA/Spot Price

The block needs both a region to get a price for (see bidding zones in table below). As well as a API-Key for authentication (requested from Kiona - Web Port Support).

It is also possible to set the offset for the spot price in hours via the optional filter. If the filter is disabled the full Json data is returned.

Land / Area codes	Bidding Zones
AL	10YAL-KESH-----5
AT	10YAT-APG------L
BA	10YBA-JPCC-----D
BE	10YBE----------2
BG	10YCA-BULGARIA-R
BY	10Y1001A1001A51S
CH	10YCH-SWISSGRIDZ
CZ	10YCZ-CEPS-----N
DE	10Y1001A1001A83F
DK	10Y1001A1001A65H
DK-1	10YDK-1--------W
DK-2	10YDK-2--------M
EE	10Y1001A1001A39I
ES	10YES-REE------0
FI	10YFI-1--------U
FR	10YFR-RTE------C
GB	10YGB----------A
GB-NIR	10Y1001A1001A016
GR	10YGR-HTSO-----Y
HR	10YHR-HEP------M
HU	10YHU-MAVIR----U
IE	10YIE-1001A00010
IT	10YIT-GRTN-----B
IT-NORD	10Y1001A1001A73I
IT-CNOR	10Y1001A1001A70O
IT-CSUD	10Y1001A1001A71M
IT-SUD	10Y1001A1001A788
IT-FOGN	10Y1001A1001A72K
IT-ROSN	10Y1001A1001A77A
IT-BRNN	10Y1001A1001A699
IT-PRGP	10Y1001A1001A76C
IT-SARD	10Y1001A1001A74G
IT-SICI	10Y1001A1001A75E
LT	10YLT-1001A0008Q
LU	10YLU-CEGEDEL-NQ
LV	10YLV-1001A00074
ME	10YCS-CG-TSO---S
MK	10YMK-MEPSO----8
MT	10Y1001A1001A93C
NL	10YNL----------L
NO	10YNO-0--------C
NO-1	10YNO-1--------2
NO-2	10YNO-2--------T
NO-3	10YNO-3--------J
NO-4	10YNO-4--------9
NO-5	10Y1001A1001A48H
PL	10YPL-AREA-----S
PT	10YPT-REN------W
RO	10YRO-TEL------P
RS	10YCS-SERBIATSOV
RU	10Y1001A1001A49F
RU-KGD	10Y1001A1001A50U
SE	10YSE-1--------K
SE-1	10Y1001A1001A44P
SE-2	10Y1001A1001A45N
SE-3	10Y1001A1001A46L
SE-4	10Y1001A1001A47J
SI	10YSI-ELES-----O
SK	10YSK-SEPS-----K
TR	10YTR-TEIAS----W
UA	10YUA-WEPS-----0
DE-AT-LU	10Y1001A1001A63L

SMHI

To get weather data from SMHI the above blocks can be used. The request is based from a location defined by longitude and latitude as well as a filter that gets the desired value and time offset.

The block for SMHI forecast needs two helper blocks

• HTTP Helper located under Requests
• SMHI Helper located under APIs/SMHI

Common

Return result Return a result from the script. Print to debug Prints a message combined with an input value to the debug-log. Code line Enters a custom code line if it is not possible to write with existing blocks. Code inline Enters custom inline code that can be combined with other blocks. Comment Adds a comment to the resulting code as well as block structure. Region Can be used to group code together either with curly brackets around or without. The region also includes a caption in the form of a starting and ending comment. Try-catch-finally Is used to catch errors when executing the code. The code that is monitored is put in the try sections and if an error occurs the catch section will be executed. The err variable will contain the error message. The finally section will always be executed.