Using the Model Editor

The model editor user interface

The model editor allows you to create analytic models graphically. It is invoked when you add or edit a model in the model manager. See also Adding a new model and Editing an existing model.

The palette on the left contains the blocks that you can add to your model. It has several expandable/collapsible categories for the different types of blocks.

The canvas in the middle is the area in which you “draw” your model. You drag the blocks from the palette onto the canvas, specify the parameters for the blocks, and wire the blocks together. The content of the canvas is aligned to a grid (see also Showing and hiding the grid).

The overview area at bottom right of the canvas shows the entire model. This is helpful if your model is too large to fit on the currently visible area of the canvas. See also Navigating large models.

The documentation pane on the right allows you to view reference information for the currently selected block. See also Viewing the documentation for a block.

CAUTION:

Changes are only saved when you click (see also Saving a model). The editor warns you if you attempt to navigate away from the editor and there are unsaved changes, however, you should always ensure that your changes are saved before disconnecting the browser from the network or suspending a laptop.

Working with models

Overview of steps for adding a model

This topic gives a brief overview of how to add and design a new model. For more detailed information, see the topics that are referenced in the steps below.

You add and design a model as follows:

  1. In the model manager, click New model. Enter a model name in the resulting dialog box. See also Adding a new model.

  2. In the model editor, drag the required blocks from the palette onto the canvas. See also Adding a block.

  3. Refer to the block documentation as necessary. See also Viewing the documentation for a block.

  4. Use the block parameter editor to specify the parameters of the block. See also Editing the parameters of a block.

  5. Connect the appropriate blocks with wires. See also Adding a wire between two blocks.

  6. Save your changes. See also Saving a model.

    Note: Only saved models are listed in the model manager. When you add a new model and then leave the model editor without saving the model, it will not be listed in the model manager, and all the edits you made will be lost.

  7. Leave the model editor. This takes you back to the model manager. See also Leaving the model editor.

  8. A newly added model is automatically set to draft mode in the model manager. If you want to test it, simulate it, or make it available in production, see Deploying a model.

For detailed background information, including restrictions, see Wires and Blocks.

Changing the name, description, and tags of a model

You can rename each model that you are currently editing in the model editor, and you can also change the description of each model.

You can also add or remove tags. Tags are helpful in the model manager, to show only the models for which a specific tag has been defined (see also Filtering the models).

To change the name, description, and tags of a model

  1. In the model editor, click on the model name which is shown at the left of the toolbar.

  2. In the resulting Model Configuration dialog box, specify a new unique name for the model, change the description, and/or change the tags.

    To add a tag, you simply type its name and press Enter or the Tab key. The tag is then shown in a colored rectangle. To remove a tag, click on the that is shown in the rectangle. The dialog prevents you from entering duplicate tags for a model; if you enter such a tag name, the duplicate tag is not added and the original tag blinks one time.

  3. Click OK.

Saving a model

When you save a model in the model editor, it is stored in the Cloud of Things inventory for your tenant, in JSON format.

Important: It may happen that you and another user are editing the same model at the same time. In this case, the changes that are saved last will be stored. So your changes might be overwritten by a later save by another user.

To save a model

Leaving the model editor

When you leave the model editor using the corresponding toolbar button, you are returned to the model manager. You can then, for example, edit a different model, or change the mode or state of the current model.

CAUTION:

All unsaved changes are lost when you navigate to a different URL or close the browser window.

To leave the model editor

Working with blocks and wires

Adding a block

The blocks in the palette are grouped into different categories. The blocks in the Input and Output categories represent devices, device groups and/or (if the search box is used) any assets that have been registered in the Cloud of Things inventory (visualized in the Device Management application). Other categories contain blocks, for example, for adding logic to the model or for adding calculations.

When you move the mouse pointer over a block in the palette, a tooltip appears which briefly explains the purpose of the block. The tooltip also shows the entire name of the block.

Horizontal scrollbars are available in both the Input or Output categories, below the tree. These scrollbars - and also the tooltip - are helpful when the name of a device, device group or asset is not fully shown in the palette.

Detailed information for each block is available in the block reference, which is shown in the documentation pane. See also Viewing the documentation for a block.

To add a block

  1. In the palette of the model editor, expand the category which contains the block that you want to add.

  2. When you expand the Input or Output category, the devices and device groups that are registered in the Cloud of Things inventory are initially shown.

    By default, up to 10 devices and 10 device groups are shown, sorted alphabetically. With a large inventory, you will have to click Load more to display any devices or device groups that are not shown initially.

    The palette reflects the parent/child hierarchy in the Cloud of Things inventory. The list of devices includes any defined child devices, and the list of device groups includes any defined sub-groups. These are available from expandable/collapsible nodes.

    The Input and Output categories both have a search box. These search boxes can be used to show any assets in the Cloud of Things inventory which match your search criteria. This includes devices, device groups and also managed objects. The search is case-sensitive. You can enter a name or part of a name. The characters that you type in may be contained at any position within the name. For example, enter the word “test” to show only the assets that have this word in their names. You need not press Enter; the list is updated with each character that you type. The search result is sorted alphabetically. With a large search result, you will have to click Load more to display any assets that are initially not shown.

    The maximum number of shown devices, device groups and/or assets depends on a tenant option. For more information, see Configuring the number of shown devices, device groups and/or assets.

    The assets that are shown when searching also depend on a tenant option. You can restrict the search to show only assets of a specific type. For more information, see Searching for input and output assets.

    When you expand a different category, your search criteria are remembered.. This is helpful if you want to have shorter lists for the Input and Output categories, both with individual contents as defined by your search criteria.

    The Output category offers for selection a special block, the Trigger Device. This sends the output back to the device which triggered the output.

  3. Drag the block from the palette and drop it on the canvas.

    When you drop the block on an existing block on the canvas, the new block is created on top of that block. When you drop the block on a collapsed group, the new block is created below that group. In both cases, you should move the new block to a free space of the canvas. See also Moving a block.

    When you drop the block on an expanded group (where the contents of the group are visible), the new block is added to that group. For more information on groups, see Working with groups.

    Note: Even though the Output category shows device groups, it is not possible to drag them onto the canvas because group output is not allowed.

  4. Specify all required parameters for the block. See Editing the parameters of a block.

    Note: The block parameter editor is automatically shown when you add a block for which parameters need to be specified. It is not shown, however, if the block does require any parameters (such as the OR block).

Editing the parameters of a block

Most blocks (but not all) have parameters that you have to set according to your requirements.

When “Missing” is shown on an input or output block on the canvas, this means that the defined device, device group or asset cannot be found in the Cloud of Things inventory. You should then either go to the Cloud of Things inventory and make sure that this device is registered or that the device group or asset exists, or you should select a different, existing device, device group or asset in the block parameter editor (see below).

The labels of some blocks on the canvas show the value of the most important parameter. For example, the Expression block shows the defined expression, and the Time Delay block shows the defined delay in seconds.

The block parameter editor also contains commands for duplicating and deleting the currently selected block. See Duplicating a block and Deleting a block or wire for detailed information.

For the input and output blocks, you can globally replace the devices, device groups or assets that are used. See Replacing devices, device groups and assets for detailed information.

To edit the parameters of a block

  1. On the canvas of the model editor, click the block that you want to edit using the left mouse button.

    The block parameter editor appears, providing input fields for all parameters that can be specified for that block.

  2. For some blocks (such as an input block or output block for a device), the block parameter editor shows a Block Type drop-down list box. Select the type of block that is appropriate for your requirements.

    Note: The following applies when you change the block type for a block that is already wired to one or more other blocks: if the new block type has different port names (for example, if the port name changes from Value to Value 1), the existing wires to/from the changed ports are removed. This is done because a changed port name would make the existing wiring invalid.

  3. For the input and output blocks, you can select a different device (for input or output), device group (for input only) or an asset (if the search box is used) from a dialog box.

    By default, 10 devices and 10 device groups are shown, sorted alphabetically. With a large inventory, you will have to click Load more to display any devices or device groups that are not shown initially.

    The tree in the dialog box reflects the parent/child hierarchy in the Cloud of Things inventory. The list of devices includes any defined child devices, and the list of device groups includes any defined sub-groups. These are available from expandable/collapsible nodes. For output blocks, you can also select a Trigger Device.

    The search box can be used to show any assets in the Cloud of Things inventory which match your search criteria. This includes devices, device groups and also managed objects. The search is case-sensitive. The characters that you type in may be contained at any position within the name. The tree is updated with each character that you type. With a large search result, you will have to click Load more to display any assets that are initially not shown.

    Click the Use button (this is shown when you move the mouse over an entry) to select the device, device group or asset that you want to use. For output blocks, you cannot select a device group, but you can select any device within that group.

    The maximum number of shown devices, device groups and/or assets depends on a tenant option. For more information, see Configuring the number of shown devices, device groups and/or assets.

    The assets that are shown when searching also depend on a tenant option. You can restrict the search to show only assets of a specific type. For more information, see Searching for input and output assets.

  4. For some blocks (such as the Range Lookup block), the block parameter editor shows text boxes for specifying key-value pairs. If you need to specify more key-value pairs, click Add row. The key-value pair in the first row is processed first. You can drag a row to a different position using the control that is shown next to that row, and you can delete a row that you do not need any more by clicking next to that row. Empty rows are automatically removed when you leave the block parameter editor.

  5. Specify all required parameters.

    Detailed reference information for each block (and block type) is available from the documentation pane. See also Viewing the documentation for a block.

    Your input is kept in memory when you leave the block parameter editor (for example, when you click on another block or the canvas).

    Note: Keep in mind that your changes are only written to the inventory when you save the model. See also Saving a model.

Viewing the documentation for a block

The documentation pane allows you to view detailed information for the currently selected block. It shows the so-called Block Reference which provides documentation of a block’s parameters, input ports and output ports. You can resize the documentation pane, and you can also toggle its display.

To view the documentation for a block

  1. In the model editor, click the block for which you want to view the documentation. You can do this in the palette or on the canvas.

  2. When a Block Type drop-down list box is shown in the block parameter editor, select the block type for which you want to view the documentation.

  3. If the documentation pane is currently not shown, click the area that contains the icon (shown at the right of the canvas) to display the documentation pane. Clicking that area again hides the documentation pane.

  4. If you want to resize the documentation pane (for example, to make it larger), move the mouse pointer over the area that contains the icon. When the mouse pointer changes to show the resize icon (), click and hold down the mouse button and drag the mouse to the left or right (to make the documentation pane wider or smaller).

Selecting blocks and wires

If you want to move, duplicate or delete one or more blocks that are currently shown on the canvas of the model editor, you first have to select the required blocks.

To select a single block on the canvas, you just need to click the block. With a block, the resulting behavior depends on the mouse button that you use:

To select a single wire, you just need to click the wire (you can use either mouse button in this case).

To select several blocks and/or wires at the same time, do one of the following:

To deselect your selection:

Moving a block

You can move each block that is currently shown on the canvas to different location. When one or more wires are attached to a block that is moved, the wires are also moved.

To move a block

Duplicating a block

You can duplicate each block that is currently shown on the canvas. The original block and its copy will then both have the same parameters.

When you duplicate a single block, the attached wires are not automatically duplicated. When you duplicate several blocks at the same time, however, the attached wires between the selected blocks are automatically duplicated.

To duplicate a block

Adding a wire between two blocks

The blocks on the canvas can be wired together to indicate that the output from one block is used as the input for the other block.

The wires are attached to ports, that is, to the circles that are shown to the left and/or right of a block. Each block can have zero, one or more of the following:

To see the labels of the ports, click the block to select it. Or move the mouse pointer over a port to see the label in a tooltip.

See Wires and Blocks for detailed information on the types of values that can be sent between two blocks, the processing order of wires, restrictions, and more.

To add a wire between two blocks

Changing a wire

You can change the path that a wire takes to the block to which it is currently connected. And you can also rewire a block so that it is connected to a different block or to a different port of the same block.

Wires cannot create cycles. See Wire restrictions for detailed information.

To change a wire

  1. On the canvas of the model editor, click the wire that you want to change.

    The port names of the attached blocks are then shown, and the ports attached to each end of the wire are highlighted.

  2. To change the path that a wire takes between two blocks, drag one of the resize icons () that are now shown on the selected wire to a different position.

    Or to move the wire to a different port, drag the move icon () that is now shown at the input or output port (a hand pointer is shown in this case) to a different port.

Deleting a block or wire

You can delete each block or wire that is currently shown on the canvas. When you delete a block, all wires that are attached to this block are automatically deleted.

To delete a block or wire

Undoing and redoing an operation

You can undo and redo each change that has been applied to the canvas. For example, you can undo the deletion of blocks, undo changed parameter values, or undo the rerouting of a wire.

It is not possible to undo/redo the change to a model name or its description.

Note: To use the key combinations mentioned below, the canvas must have the focus. When the documentation pane or the palette currently has the focus, the change on the canvas is not undone/redone.

To undo or redo an operation

The above toolbar buttons are only enabled when there is an operation that can be undone or redone.

Replacing devices, device groups and assets

You can search the input and output blocks for the devices, device groups and assets that are used in the current model and replace them with other devices, device groups or (if the search box is used) assets that are currently registered in the Cloud of Things inventory (visualized in the Device Management application).

Note: In the rules below, the term device refers to a device or other asset (but not to a device group).

The following rules apply:

After you have replaced the devices, you need to verify that the measurements that are used by the input and output blocks of the current model still refer to the appropriate measurements. The Cloud of Things fragment and series are not changed by the replacement, which may or may not apply to the newly defined device.

To replace devices, device groups and assets

  1. In the toolbar of the model editor, click . This toolbar button is only enabled when at least one device, device group or asset has been defined in the current model. Any defined trigger devices are not considered in this case.

  2. In the Current device and device group drop-down list box of the resulting dialog box, select the device, device group or asset that you want to replace. All devices, device groups and assets that are used in the model are available for selection.

  3. Click the Replace with box to display a dialog box. The dialog box is the same as when selecting a different device, device group or asset in the block parameter editor. See Editing the parameters of a block for more information on this dialog box. Click the Use button (this is shown when you move the mouse over an entry) to select the device, device group or (if the search box is used) asset that you want to use instead.

    The maximum number of shown devices, device groups and/or assets depends on a tenant option. For more information, see Configuring the number of shown devices, device groups and/or assets.

    The assets that are shown when searching also depend on a tenant option. You can restrict the search to show only assets of a specific type. For more information, see Searching for input and output assets.

  4. If you want to replace further devices, device groups or assets, click Add row. This is only shown if more than one device, device group or asset has been defined in the current model.

    A new row is shown, containing additional Current device and device group and Replace with drop-down list boxes, and you can now select one more device, device group or asset to be replaced. Any devices, device groups and asset that you have previously selected for replacement are no longer offered for selection in the Current device and device group drop-down list box.

    Repeat this step until all required devices, device groups and assets have been selected for replacement. You can add as many rows as there are devices, device groups or assets in the current model.

  5. If you want to remove a row (for example, when you no longer want to replace a selected device), click next to that row. This is only available if the dialog box currently shows more than one row.

  6. Click Replace.

Copying items to a different model

You can copy any items on the canvas (blocks, groups, and attached wires) and paste them in a different model. The prerequisite for this is that all is done in the same session. It will not work if you try to paste the items in a different tab or in a different browser.

CAUTION:

There may be performance issues if you copy many input blocks and output blocks. This is because this operation requires access to the inventory service of Cloud of Things to get the information about the devices that are represented by these blocks.

To copy items to a different model

  1. On the canvas of the model editor, select all items that you want to copy and press Ctrl+C.

    This also works if the model is currently in read-only mode.

  2. Leave the model editor. See also Leaving the model editor.

  3. In the model manager, switch to the model into which you want to paste the copied items. This can be an existing model (see also Editing an existing model) or a new model that you first have to create (see also Adding a new model).

  4. When the model editor is shown, press Ctrl+V to paste the copied items into the model.

Working with groups

What is a group?

You can arrange blocks and their attached wires in a group. A group is a special type of block which can be collapsed and expanded. When a group is expanded, you can change its contents in the same way as you would on the canvas, for example, you can add wires or edit the block parameters. You can also add more blocks to the group or remove blocks from the group. When a group is collapsed, it occupies less space on the canvas, however, the blocks and wiring within the group are not visible in this case.

Groups are helpful if commonly required functionality needs to be made available in multiple places. You can give each group a name by which it can be identified. You can copy a group and paste it in either the same model or in a different model.

Note: Do not confuse this type of group with a device group. A device group is a special input block that is offered for selection from the palette. See also Adding a block.

The size of the box that is shown for a group is determined by its contents. If you move a block within the group to a different position, the box size is automatically adapted (that is, the box is made larger or smaller). The same applies if you change the path that a wire takes to another block within the same group.

You move a group on the canvas in the same way as you move a block (see also Moving a block). When you move a group, the group is always shown on top of all other items on the canvas. As the group box is transparent, you can easily see which blocks belong to the group and which are just overlayed by the box.

It is not possible to nest groups.

Note: There is one exception when managing the contents of a group: When you copy one or more blocks that are contained in a group using Ctrl+C and Ctrl+V or if you use the Duplicate command in the block parameter editor, the copy is not added to the group. It is added to the canvas instead. However, when you press Ctrl and then drag the blocks to be duplicated, you can place the copy either within the group (this can be the same or a different group) or on the canvas. See also Duplicating a block.

Adding a group

You can add any blocks that are currently shown on the canvas (including the wires between the blocks) to a group.

It is not possible to create an empty group. You first have to add a group as described below. Once the group exists, you can add more blocks to the group, either from the palette or from the canvas, as described in Adding a block and Moving blocks into a group.

To add a group

  1. On the canvas of the model editor, select one or more blocks that you want to add to a group. You need not select wires; all existing wires are retained. See also Selecting blocks and wires.

  2. In the toolbar of the model editor, click .

    Or press Ctrl+G.

Collapsing and expanding a group

If you need more space on the canvas and do not need the group contents to be visible, you can collapse the group.

When a group is collapsed, a number is shown on the collapsed group indicating the number of blocks in that group. For example:

If you want to make the group contents visible again (for example, to edit block parameters or to add wires), you have to expand the group.

When you save the model, the state of each group (that is, whether it is currently collapsed or expanded) is stored. The next time you edit the model, its contents will be shown as after the last save.

To collapse or expand a group

Renaming a group

When you add a group, its default name is “Group”. You can rename each group and give it a unique name.

If a group name is longer than can be shown in the group label, move the mouse pointer over the group name to view the entire name in a tooltip.

It is not possible to have groups without names. If you delete a group name, the previous name is automatically used again.

To rename a group

  1. In the model editor, select the group and then click on the group name. You can either do this when the group is collapsed or expanded (see also Collapsing and expanding a group). This selects the entire name for editing.

  2. Specify a new group name and press Enter.

Moving blocks into a group

You can move one or more blocks from the canvas into an existing group. All existing wires are retained.

You can also drag a block from the palette into an existing group. See Adding a block.

You can only move/drag blocks into a group when its contents are visible, that is, when the group is currently expanded. See also Collapsing and expanding a group.

To move blocks into a group

  1. Make sure that the group into which you want to move the blocks is not collapsed.

  2. On the canvas of the model editor, select the blocks that you want to move into the group (see also Selecting blocks and wires). You need not select the wires between the blocks; they are automatically moved together with the blocks.

  3. Do one of the following:

    • Drag the selection into the group and drop it there.
    • Or select the group into which you want to move the blocks. Then click in the toolbar of the model editor, or press Ctrl+G.

Removing blocks from a group

When you remove a block from a group, the block is moved to the canvas. It is not deleted. All existing wires are retained.

When the last item of a group has been removed, the group is automatically deleted. If you want to remove all items from a group at the same time, you can simply ungroup the entire group. See Ungrouping a group.

To remove blocks from a group

Deleting blocks and wires from a group

You delete blocks and wires from a group in the same way as deleting them directly on the canvas. The only prerequisite is that the group is currently expanded. See Deleting a block or wire.

If the last item in a group is deleted, the group is automatically deleted.

Copying a group

You can copy each group that is currently shown on the canvas. The original group and its copy will then both have the same contents.

Wires coming in from blocks outside of the group or going from the group to blocks outside of the group are not copied.

You can also copy a group into a different model, see Copying items to a different model.

To copy a group

Ungrouping a group

When you ungroup a group, the group is removed and all the blocks from that group are shown directly on the canvas. All attached wires are retained.

You can ungroup several groups at the same time. In this case, it is important that no block or wire is selected either within or without the selected groups, otherwise ungrouping is not possible.

To ungroup a group

  1. On the canvas of the model editor, select one or more groups that you want to ungroup. It does not matter whether a group is currently collapsed or expanded.

  2. In the toolbar of the model editor, click .

    Or press Ctrl+Shift+G.

Deleting a group

You can delete each group that is currently shown on the canvas.

CAUTION:

When you delete a group, all blocks and wires within this group are also deleted.

To delete a group

Managing the canvas

Navigating large models

If your model is too large to fit onto the visible part of the canvas, you can use the mouse to drag the parts of the model into view that are currently outside of the window. You can do this either directly on the canvas or in the overview area. The overview area always shows the entire model. If the overview area is currently not shown, see Showing and hiding the overview.

To navigate in a large model

  1. In the model editor, position the mouse over a free spot of the canvas (which does not contain a block or wire) or anywhere over the overview area.

  2. Click and hold down the mouse button, and immediately drag the mouse into the desired direction. Release the mouse button when the required area is visible on the canvas.

    Note: When you hold down the mouse button for a longer time over a free spot of the canvas, the mouse pointer changes and you can select an area instead (for example, several blocks and attached wires). See also Selecting blocks and wires.

Showing and hiding the overview

The overview area, which shows the entire model, is shown at bottom right of the canvas. If you do not need the overview, you can hide it.

To show or hide the overview

Zooming the canvas

The toolbar of the model editor indicates the current zoom percentage for the canvas. The zoom buttons in the toolbar allow you to

Note: When you use the key combinations mentioned below, the currently selected area defines what is to be zoomed. When the canvas has the focus (for example, when you have just selected a block or wire), only the content of the canvas is zoomed. When the documentation pane or the palette currently has the focus, the browser’s zoom functionality is used and all of the browser content is zoomed (and the zoom percentage in the toolbar remains unchanged).

To zoom the canvas

Showing and hiding the grid

The blocks, wires and groups on the canvas always snap to a grid. You can decide whether the grid is to be shown or not. The grid is not shown by default. When you zoom the canvas, the grid is zoomed accordingly.

To show or hide the grid