Introduction

Scripts in iCL Designer provide a variety of ways to make content interdependent and interlinked.

You are able to change the visibility, perform calculations, or extend questions and answers.

At the same time, scripts are very approachable, as you do not need to have programming skills to use them. This is achieved by using blockly, which is an editor that allows you to define scripts similar to assembling a puzzle.

When to use scripts

There is a broad variety of use cases for blockly scripts. They are often used to create dynamic answers or to change the visibility of specific workbook areas based on input.

Another area for scripts are Content Items, which can receive data from previous inspections as well as update existing data or create new data sets.

Scripts are also used to limit, filter or sort data or lists, doing calculations or providing date and time values to work with.

Blockly script UI

All scripts will be created in a seperate window - the blockly editor. By default it is located at the bottom of the user interface.

You are able to access the blockly-editor in the properties window at every puzzle icon by clicking on it.

Now, a script can be created

1. using any of the provided blocks
   The fallback content to display on prerendering
2. or using the value of another field, by dragging and dropping that field into the blockly designer
   The fallback content to display on prerendering

The difference is the following: If you use only a constant value in your script like in the first case (1), this script will be evaluated once (when the field it belongs to is created). Thereafter it will not change anymore. Therefore, the first script creates a default value, that the user can later overwrite.

If you, however, use the value of any other field in your script, like in case (2), your script now depends on that field. That means, that whenever those other fields change (e.g. because the user enters some other value), your script will be re-evaluated.

When creating a new script, the editor will have a red border, which indicates, that the script is missing something or has unconnected elements in the script area. This will happen often when building or changing scripts, and while having a red border, the script will not work and, thus, cannot be saved.

You can close the editor at every point by hitting the X in the top right of the window. When there is still a script error while closing the blockly window, a prompt will reassure, if you want to close the window and lose current unsaved changes of this script.

Blockly window docking

You can change the position of the blockly editor by performing a drag&drop action on its colored headline. Several arrows appear in the corners and in the middle, which you can address via hovering the window over that arrow. The window will be positioned in the indicated grey area.

note

The new window position will not be saved after closing the workbook.

Scriptable properties

You can find the blockly editor at the following locations:

Property	Usable at	Allowed Output	Purpose
Title	Workbook / Checklist / Chapter / Headline / Field	Text, Number	Changes the title of that node.
Mandatory	Field	Boolean	If the output is true, this field becomes mandatory. False will disable its mandatory status.
Exists	Chapter / Headline / Field	Boolean	If the output is true, the field will exist in the iCL Filler. If it doesn't exist, all related scripts and follow-up-fields will be treated as not existent.
Hidden	Chapter / Headline Field	Boolean	If the output is true, you are not able to see this field, but the iCL Filler can still access its data and values.
Readonly	Field	Boolean	If the output is true, the field is in an readonly state, where no changes can be made. Be careful when mixing mandatory with readonly parameters.
Scripted Answer	Field	Text Number Date Time	This script automatically sets the answer of the field with or without a condition/relation.
Minimum/Maximum	Chapter / Headline	Number	Modifies the minimum and maximum occurrence of that node.
Query	Chapter / Headline / Field (Databound)	-	Creates a connection between two content types based on a matching entry.
Order by	Chapter / Headline	-	Modifies the order of this repeated section.
Filter	ContentType / Field (Content Item)	-	Sets a filter for the loaded content items of that field to restrict/limit/filter/ data.
Mappings	Field (Content Item)	depends on mapping data type	A Mapping stores data to add/modify Content Item data for Content Types.
List	Field (Databound)	List	Provides answers based on a list of data

script evaluation

To get an understanding of when and why such scripts are evaluated, see here.

Available blocks

Text blocks

Block	Function	Allowed Types
	Allows translatable and non-translatable input.	Text, numbers, special characters
	Connects several display elements together.	All
	Returns true when the two texts are the same, false otherwise.	Text
	Returns a newline character.	-
	Returns a copy of the text with the whites paces removed from one or both ends.	Text
	Displays the attached text in upper/lower case or title case.	Text
	Returns the position of the first/last occurrence of the first text in the second text. Returns 0 if text is not found.	Text
	Returns the letter at the specified position. #1 is the first item.	First input: text, Second input: number
	Returns a specified portion of the text.	First input: text, Second and third inputs: number

Math blocks

Block	Function	Allowed Types
	Enables the entry of numbers.	Number
	Creates a number from text.	Text
	Enables mathematical calculations - sum, minimum- maximum value, average.	Number, number fields
	Compares two numbers with each other.	Number
	Enables basic mathematical calculations.	Number, number fields
	Enables rounding - commercial, up, down.	Number, number fields
	Enables rounding with defined decimal places - commercial, up, down.	Number, number fields
	Calculates the root of a number.	Number
	Calculates the remainder of a division.	Number
	Returns a random number between -2,147,483,648 and 2,147,483,648.
	Returns a random number between the given minimum and maximum values. The lower limit is inclusive, while the upper limit is exclusive. This means for example: If you specify a minimum of 0 and a maximum of 3, possible values are: 0,1,2 (so 3 is not part of the result set).	Number, number fields
	Returns an array with the given amount of unique/not unique random numbers between the given minimum and maximum values. The lower limit is inclusive, while the upper limit is exclusive. This means for example: If you specify a minimum of 2 and a maximum of 5, possible values are: 2,3,4 (so 5 is not part of the result set).	Number, number fields

Date & time blocks

Block	Function	Allowed Types
	Returns the current date of the device.	Datetime
	A date field composed of the individual date components.	Number
	Adds a specified number of days/months/years to a date.	First input: number, Second input: date
	Returns either the year, month, day or weekday as a number.	Date
	Compares two date fields and returns a boolean value.	Date
	Returns given text as formatted date.	Text
	Returns given text as custom formatted date.	First input: Text, Second input: Text
	Calculates the duration between two points in time.	Timepicker

Use text field as input for date blocks/fields

When you have to use a text field as input for a date block/field, the text will be interpreted as a valid date in case it uses one of following date formats:

MM/dd/yyyy HH:mm:ss
MM/dd/yyyy HH:mm
MM/dd/yyyy
yyyy-MM-ddTHH:mm:ssZ 

The last format is an international standard called "ISO 8601" which is also used in REST interface of iCL Portal.

Logic blocks

Block	Function	Allowed Types
	A branch operator to cover different cases logically.	First input: boolean, Second and third inputs: all
	A branch operator to cover different cases logically. Allows to add additional else-if branches.	First input: boolean, Second and third inputs: all
	A logical truth operator for true and false.	-
	Enables mathematical comparisons.	Boolean
	Negates a following logical statement.	Boolean
	Returns the value null.	-
	If the result of the first block is an error, returns the second blocks value, otherwise the result of the first block	any

Lists blocks

Block	Function	Allowed Types
	Filters in a list according to certain criteria.	List
	Creates a list with 1 entry, can be extended.	All
	Creates a list with 3 entries, can be reduced/extended.	All
	Filters the given list using the provided logical block, where the logical block is used for each and every element of the list.	First input: list, Second input: boolean
	Returns the length of a list.	List
	Takes a list or single value. If it is a single value, wraps it in a list. If it is a list that contains lists, it removes those lists and, instead, moves their items into the main list.	List
	If used with text from list, it takes a list and joins it together with the specified delimiter. If used with list from text, it takes a text and splits it using the specified delimiter.	List
	Reverses the elements of the given list.	List
	Returns distinct elements of the given list.	List
	Sorts the elements of the given list ascending/descending.	List
	Sorts the elements of the given list ascending/descending by a specified expression.	First input: list, Second input: text, number, boolean, date
	Checks whether any/every element in the list fulfills the given boolean expression. Returns a boolean.	First input: list, Second input: boolean
	Creates a new list with the results of executing the provided expression on every element in the given list.	First input: list, Second input: all

Checklist field blocks

Block	Function	Allowed Types
	Compares two values with each other. Mind that you cannot compare with numbers here. Use a text-block in the 'create list with'-part for comparison or switch to math-blocks if comparing two numbers.	Text
	Checks if a field has a value or no value at all.	Fields
	Allows to resolve all input fields that match the specified pattern. You can resolve all input fields with it or you can get only specific type of input fields e.g. all text fields, all number fields, etc.	-
	Allows to resolve all option fields that match the specified pattern. You can resolve all option fields with it or you can get only specific type of option fields e.g. all checkbox fields, all dropdown fields, etc.	-

User properties blocks

Block	Function	Allowed Types
	Shows the ID of the logged in user.	-
	Shows the username of the logged in user.	-
	Shows the first name of the logged in user.	-
	Shows the last name of the logged in user.	-
	Shows the e-mail address of the logged in user.	-

Formatting blocks

Block	Function	Allowed Types
	Returns the given date as formatted text. Provides a dropdown list to select the intended format.	Date
	Returns the given time as formatted text. Provides a dropdown list to select the intended format.	Time
	Returns the given number as formatted text. Provides a dropdown list to select the intended format.	Number
	Returns the given object (can be a number/date/etc.) as formatted text using the specified format string. You can read more about format string in Microsoft Docs or in our documentation.	All

Task blocks

Block	Function	Allowed Types
	Allows to get certain properties of the task of the inspection. Properties: external ID, title, inspector, inspected object(s), description, start date and due date.	-
	Returns true if the inspection was started with a task, false otherwise.	-

Inspection blocks

Block	Function	Allowed Types
	Provides information about the current inspection. Properties: language.	-