Edit the workflow

Introduction

You can see and edit a workflow in its editor, that is the Editor tab of the workflow's workspace.

The central part of the editor is a canvas.

The definition, or diagram, of the workflow consists of the blocks and optional connections between blocks that are put inside the canvas.

The canvas contains an hexagonal grid that reveals itself when you hover over it as you add or move blocks. All the building blocks of the workflow snap to this grid.

Understand components

A workflow block, represented in the diagram by a hexagon, is a copy of a component taken from an inventory that is shown in the left panel of the editor.

The inventory of components is divided in the following groups:

• Predictive models, comprising symbolic models, ML models and Knowledge Models.
• Processors
• Operators
• Splitters
• Remappers
• Reducers
• Possible custom components.

Understand flows

Every workflow is made of at least one flow.
A flow can be as simple as a block or be made of multiple connected blocks.

It is possible to have a workflow with multiple, independent—that is, without connections between them—flows that are executed in parallel when the published workflow is used.

Each flow receives the same input, that is the workflow's input.
The workflow's output is the concatenation of the outputs of all the flows.

Add blocks

• To add to the workflow a block for a model component:

  1. Select the model type on the strip at the top of the components' list in the left panel, choosing between:

     • Symbolic models
     • ML models
     • Knowledge models

     This will automatically choose the latest version of the component hosting service¹. If instead you want to select a model type and a specific version of its hosting service (when more versions are available), hover over the model type and select the version of the hosting service.

  2. Move the symbol of the model type to the desired position on the canvas.

  3. Click to place the symbol: the list of available models appears.

  4. For a ML model, turn on Advanced mode if you want a block without NL Core, that is a block that will only execute the ML algorithm, skipping the preliminary text analysis and feature extraction step that ML models perform in basic mode.

     If you chose the ML models type and hosting service version 1.0.0 in step a, then models that are not compatible with advanced mode are listed with a gray icon and their version. If you turn on advanced mode, incompatible models are not listed anymore.
     If you are using the latest version of the hosting service, only compatible models are listed.

  5. Select the model from the list then select Confirm.
     You can use the search box inside the list to find a model: enter characters in the box to list only models with matching names.

  Or:

  1. Select the model from the My Models bar on the right side of the page.
  2. Move the corresponding block to the desired position on the canvas.
  3. Click to drop the block in place.

  Or:

  • Drag a model from the My Models bar on the right side of the page to the desired position on the canvas.

  Info

  If you use one of the last two methods above to place an ML model, it will be set to basic mode.

  To know about a model listed in the My Models bar, hover over the model's icon.

• To add to the workflow a block for any component except models:

  1. Select the component on the left panel.
  2. Move the corresponding block to the desired position on the canvas.
  3. Click to drop the block in place.

  Or:

  • Drag the component from the left panel to the desired position on the canvas.

  If there is an arrow to the right of the component name in the left panel it means that multiple versions¹ of the component are available. If you select or drag the component as described above, the latest version of the component is automatically chosen. If instead you want to choose the version of the component:

  1. Hover over the component on the left panel: a pop-up list of available versions is displayed.
  2. Choose the version.
  3. Move the corresponding block to the desired position on the canvas.
  4. Click to drop the block in place.

You cannot put a block adjacent to another, there must be at least an empty grid hexagon between any two blocks.

Connect blocks

Connecting two blocks makes them part of the same flow and establishes the order of execution: at runtime, the block from which the connection starts will be executed first.

The connection can be simple or, if it originates from a Switch block, conditional.
A conditional connection is activated—and therefore the block at the end of it is executed—only if the condition associated with the connection is true.

To connect two blocks:

1. Hover over the block from which you want the connection to start. A plus icon will appear on the right of the hexagon.
2. Drag the plus icon to the other block.

Info

It is the direction of the connection, indicated by the arrow icon, and not the reciprocal position of the connected blocks that determines the order of execution of the flow.

Conditional connections are identified by the the gear icon that appears midway along the connection.
To set the condition associated with the connection:

1. Select Configure condition along the connection. A pop-up list with all the conditions defined in the Switch block appears.
2. Select the condition from the list.

When you connect a block to another block that has input variables, the editor attempts to automatically configure the input properties of the downstream block by mapping its input variables to top-level keys of the declared output of the upstream block.
When fully automatic mapping is not possible, a notification from the editor assistant appears and you can edit the downstream block to set input properties manually or via the smart assistant.

Edit block properties

The properties of a block are all the features and settings of the block, configurable or not.
They derive from the properties of the component that the block is a copy of, but are unique and specific to the block.

To edit the properties of a block:

• Double-click the block on the canvas.

Or:

• Right-click the block on the canvas and select Edit component on the context menu.

Or:

• Select the block on the canvas, then select Edit component on the canvas toolbar.

Or:

1. Select the ellipsis to the right of the canvas toolbar then choose Show components map. A dialog appears showing the list of components used in the workflow.
2. Select Edit component in the component's row.

The edit dialog is displayed. Depending on the component, a block has specific properties. In the reference section of this manual you will find the description of the properties for all the components:

• Models
• Processors
• Operators
• Splitters
• Remappers
• Reducers
• Possible custom components.

Also in the article dedicated to the description of each component you will find the explanation of the peculiarities about setting the input properties.

Inside the editor you can use the component guide to have information about components' properties.

Use the component guide

In the editor you have guides to some of the properties of the components.
To toggle the guides, select the question mark icon at the top right of the left panel.

When guides are turned on, if you hover over a component in the list, a pop-up panel containing the guide to the component is displayed.
The panel contains a description of the component and additional contents organized in tabs:

• Input: lists the input variables of component's blocks expect. This can help setting block's input properties.
• Output: lists the top-level keys of the JSON that component's blocks produce as their output. This helps understanding the block's output properties.
• Functional: lists the functional properties.

Move blocks

To move a block, drag and drop it where you wish.

Change conditional connections

To change the condition of a conditional connection originating from a Switch bloc:

1. Select Configure condition along the connection. A pop-up list with all the conditions defined in the Switch block appears.
2. Select the new condition from the list.

Disconnect blocks

To remove the connection between two blocks:

• Select the connection and press Del.

Or:

• Select the connection then select Delete selected component on the canvas toolbar.

Or:

• Hover over the arrow icon in the middle of the connection and select Remove Connection.

Warning

Please note that when you disconnect two blocks you are effectively breaking one flow and creating two independent flows.

Remove blocks

To remove a block:

• Select it, then select Del.

Or:

• Right-click the block and select Delete selected component on the context menu.

Or:

• Select it, then select Delete selected component on the canvas toolbar.

Info

When you remove a block, all its inbound and outbound connections are removed as well.

Find a block

In complex workflows it can be difficult to locate a block based on a specific component. To find it easily, select the ellipsis to the right of the canvas toolbar then choose Show components map. A dialog appears showing the list of components used in the workflow.

• To select and highlight a block in the canvas, select Select component in the component's row.
• To filter the list of components based on component name or block ID, type at least three characters in the search box and press Enter. The list will only show components with names or block IDs that match what you typed.
  To clear the filter select the X icon in the search box or clear the search box and press Enter.

Undo and redo changes

Select Undo or Redo on the canvas toolbar to undo or redo changes to the diagram.

Pan and zoom

To pan the diagram, drag an empty point of the canvas.

To recenter the diagram in the canvas when is partially or fully panned out of sight, select Recenter in the lower right corner of the canvas.

To zoom in and out, select Zoom in or Zoom out on the canvas toolbar or use the mouse wheel.

Clear the canvas

To clear the canvas, so deleting the workflow, select Clear workflow on the canvas toolbar. The workflow is actually deleted only if you save the changes.

Optimize layout

To optimize the layout of complex workflows select Optimize layout on the canvas toolbar.
The editor will automatically rearrange the blocks so that the layout is as compact as possible.

Validate the workflow

A workflow is invalid if it contains inconsistencies, such as a Join block without at least two inbound connections or a Fork block without at least two outbound connections.

To validate the workflow, select Validate current workflow on the canvas toolbar.

If validation fails, the Validate current workflow icon shows a red alert sign and the Validation failed dialog is displayed. Expand Show detail to know more about errors.

Track and save changes

The changes made since the last save are listed in the drop-down on the canvas toolbar.

• To save changes, select Save on the canvas toolbar.
• To discard changes, select Discard on the canvas toolbar.

Customize the editor

Left panel

The left panel can be hidden to have more space for the drawing canvas. In order to be hidden, the left panel must first be undocked.

To undock the left panel select the undock icon inside the panel.

To hide the left panel:

1. If the panel is docked, undock it (see above).
2. Select the blue X icon on the canvas toolbar.

To unhide the left panel select the blue plus icon on the canvas toolbar.

To dock the left panel, select the dock icon inside the panel.

My Models bar

The My Models bar on the right side of the page lists the most recently used models so that they can be quickly reused. The bar can the turned off to have more space in the canvas or if not needed.

To turn off the bar select the ellipsis to the right of the canvas toolbar then choose Show "My Models" bar. Repeat to turn the bar on again.

Use the editor assistant

The editor assistant automatically shows up in the lower right corner of the canvas to display useful—sometimes actionable—suggestions for the correct construction of the workflow, like:

• Auto-complete the workflow by adding missing components.
• Notify an issue with a block's properties and let you edit a block to fix the issue.
• Give tips about the component behavior.

Select the expanding and collapsing arrows to expand and collapse the panel.

The default version of the component—or hosting service—is the latest, however in these cases it may be useful to use previous versions:

• Backward compatibility issues with workflows designed with an old version of NL Flow.
• In the case of JavaScript Interpreter, the need to publish the workflow in synchronous mode, which is only possible using version 1.0.0 of the component.

---

1. Some components can have multiple versions. In the case of models, the version refers to the hosting service, a software layer that encapsulates the model, which has its own version. ↩↩