Edit a workflow

The canvas

A workflow is designed in the Editor tab inside the workflow's workspace, which opens at the end of the creation wizard or when opening an existing workflow from the Workflows dashboard.

The central part of the editor is a canvas: the workflow corresponds to the blocks you place (and connect) 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.

Components

The Components panel on the left shows the building blocks you can choose from to compose a workflow.

Components are:

• Processors
• Operators
• Symbolic and ML models
• Knowledge models
• Custom components

Symbolic and ML models are NLU models that have been previously published from the Platform's authoring application or uploaded from the Models view of the main dashboard.
Knowledge Models are built-in models. Custom components are installation specific components.

Data flows

A workflow is made of one or more data flows.

A data flow can be a single block or multiple connected blocks.
At runtime and during tests, each data flow is evaluated from left to right: the input request enters the workflow and is submitted to the leftmost block of each data flow. The output of each data flow is that of its rightmost block. The overall output of the workflow is the concatenation of the outputs of all the data flows.
Given the direction of the data flow, when multiple blocks are needed they must be laid down from left to right. The relative position of a block with respect to the previous must be chosen between those highlighted in blue in the following picture.

After being added to the canvas, the block must be connected.

Add blocks

To add a block to the workflow, select the component from the left menu and place the corresponding block in the canvas.
You cannot put a block adjacent to another.

Info

A block corresponding to a model that:

• Was created with the Platform authoring application using the Pdf document view to annotate extractions.

Or:

• Was created with expert.ai Studio and relies on document layout information (because, for example, has rules that use the TITLELEVEL attribute).

must be preceded by an Extract Converter processor block.

Pan and zoom

To pan the diagram drag any point on the canvas.

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

Move blocks

To move a block, select it in the canvas then:

1. Right-click the block and select Move selected component on the context menu.
2. Move the block.
3. Click to confirm the new position.

Or:

1. Select the block.
2. Select Move selected component on the canvas toolbar.
3. Move the block.
4. Click to confirm the new position.

If you move a block too far from a block is was connected to, a notification warns you that the connection will be lost.

Connect blocks

Two blocks can be connected if their relative positions allows for the creation of a data flow between them.

To connect two blocks:

• Right-click the first block and select Connect selected component on the context menu, then select the second block.

Or:

1. Select the first block.
2. Select Connect selected component on the canvas toolbar.
3. Select the second block.

If the block are as close as possible, you can also connect them by simply selecting the segment between the two hexagons.

Arrows in connections help remind the direction of the data flow, from left to right.

Output-input mapping

In order for the data to "flow" between two connected blocks, the block on the right must recognize the output of the block of the left—or a part of that output—as its input, to process it.
Given the variety of components and the differences between their outputs, it's not always obvious or unambiguous which parts of the output of a block must become the input to the next block.

Info

In the reference section of this manual you will find the description of the input expected by model blocks, processor blocks and operator blocks.

When connecting two blocks, the editor automatically tries to determine mapping.

When automatic mapping is not possible, a dashed line is drawn around the right block and a warning message is displayed.

The output of any block is an object represented with JSON. When mapping is needed, one or more top-level properties of the output object must be mapped to corresponding input properties of the next block.
To check the result of automatic mapping or the set mapping manually, edit the right block (see below) and go to the Input tab.

Info

A top-level property of the output JSON of a block can only be mapped to an input property of the same type (e.g., an object to object, an array to array, a string to string), while the names can differ.

Edit a block

To edit the properties of a block:

• Double-click the block.

Or:

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

Or:

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

The edit dialog is displayed. In the reference section of this manual you will find the description of the editable properties for model blocks, processor blocks and operator blocks.

Use the Input tab to check or set output-input mapping.
To map a property of the previous block's output to an input property of the current block select the output property from the drop-down list of the input property.

To get suggested mapping, select Map properties automatically .

Disconnect blocks

To remove the connection between two blocks, select the connection and:

• Press the Del key.

Or:

• Select Delete selected component on the canvas toolbar.

Note

Disconnected blocks are still a valid workflow made of independent flows.

Remove blocks

To remove a block, select it in the canvas and:

• Press Del.

Or:

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

Or:

• Select Delete selected component on the canvas toolbar.

Replace model blocks

To replace a model block, select it in the canvas and:

• Right-click and select Replace component on the context menu.

Or:

• Select Replace component on the canvas toolbar.

The Replace component dialog is displayed.

• Select the new component from the drop-down list, then select Replace.

Undo and redo changes

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

Clear the canvas

To clear the canvas, select Clear workflow on the drawing area toolbar.

Optimize layout

To optimize the layout of complex workflows select Optimize layout on the canvas toolbar.

Validate the workflow

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

Info

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.

Changes are also visualized with blue dots and blue outlines inside the diagram.

To save changes, select Save on the canvas toolbar.

Workflow information

Load

Information about the load represented by the workflow when published in the NL Flow runtime is shown in the main toolbar next to the workflow name. The runtime must have sufficient capacity to accommodate the workflow: find more information about this in the description of the dashboard's Runtime view.

• The empty hexagon icon corresponds to the number of blocks in the workflow.
• The hexagon with a gear inside corresponds to the number of Javascript blocks in the workflow.
• The gauge icon corresponds to the number of CPUs or the thousandths of a CPU that need to be allocated to the workflow ("m" stands for "milli").
• The chip icon corresponds to the amount of RAM that needs to be allocated to the workflow, expressed in mibibytes or gibibytes.

When a workflow has been published, numbers in parenthesis refer to the saved version of the workflow and are displayed if they differ from the published workflow.

Identifying information

To view the identifying information needed to use the workflow via the NL Flow API, select Workflow settings of the main toolbar, then select Information in the dialog.

Here you can find the workflow ID, the API endpoint for analyzing documents and the API endpoint for determining the status of the workflow. To have more information on any API keys linked to the workflow, use the Runtime view of the dashboard.
To copy information to the clipboard select the button to the right of the field.

Change workflow name and description

To change the name or the description of the workflow:

1. Select Workflow settings on the main toolbar.
2. Select the General tab.
3. Change information.
4. Select Save.

Define the input format

When:

• The are multiple data flows starting with blocks of different types (for example a URL Converter processor and a TikaTesseract Converter processor) and the input to the workflow must be "split" between the starting blocks.

Or:

• The workflow input JSON has top-level properties that conceptually correspond to the input properties of some workflow blocks, but with different names.

the formal definition of the workflow input allows specifying the name and the type of the top level properties of the input JSON so that they can be mapped to the input of workflow blocks—no matter their position in the flow—by editing the block and setting its input properties to the keys of the $nlflow_input pseudo block.

In the reference section of this manual you will find the description of the input properties for models, processors and operators.

To define the workflow input format, select the ellipsis then Input format definition. The Input format definition window appears.

Use the Basic tab to define the format interactively:

In input format definition, inputs correspond to top level properties of the workflow's input JSON.

• To define a new input, select the plus button . A couple of boxes appears below the list. Enter the name of the new input in the left box and click elsewhere, then select the type from the drop-down box on the right.
• To modify an input change its name and/or type.
• To delete an input select it and then select Delete

Alternatively, use the text editor in Advanced tab to define the format by writing a JSON template.

The entire template must be enclosed in curly braces. The syntax of the definition for a input is:

"name": type

where name is the name of the input. type represents the type of the key and can be:

• {} for an object
• [] for an array
• "" for a string
• 0 for a number
• false for a boolean

Use the comma , to separate multiple inputs.

To delete all the inputs select Clear text .
To save the definition select Save.

Publish the workflow

Publishing a workflow means instantiating it to make it testable and—if linked to at least one API key—usable with the NL Flow API to analyze documents.
You can find more information about this in the description of the dashboard's Runtime view, which, by the way, is another place on the NL Flow dashboard where you can publish a workflow.

To publish an unpublished workflow:

1. Select Publish on the main toolbar. The Runtime load dialog appears, showing the impact of publishing the workflow on the runtime capacity.

   

   If the NL Flow runtime doesn't have enough capacity, a warning message is displayed. In this case, you can change the workflow or the functional properties of its blocks so that the workflow requires less resources, or you can unpublish unused workflows to free up space inside the runtime. Talk to your system administrator if, instead, the only solution appears increasing the capacity of the NL Flow runtime.

2. If the NL Flow runtime has enough capacity to host the workflow, select Next.

3. If you want to use the workflow through the NL Flow API, select a key from the API Key drop-down list.
   If you want to link more API keys to the same workflow:

   1. Select Add API key: a new drop-down list appears.
   2. Select the key from the new drop-down list. Repeat from the previous step to link more keys.

   To remove an API key from the list, select the trash can button on the right of the key item.

An orange dot on the main toolbar means the workflow is being published and it's still not usable.
To have summary information about the publishing operation, hover over the colored dot.

To have more detailed information, select the info icon .

In case of a workflows with blocks requiring replicas, the dot becomes yellow when usable because not all the replicase of all the blocks have been instantiated, but there is already one instance for each block.

When all the blocks have been fully instantiated, the dot becomes green.

If you change a published workflow, a notification appears in the main toolbar, suggesting to update the published version.

Unpublish a workflow

To unpublish a workflow, select Unpublish on the main toolbar.

Download the Postman collection

To download a Postman collection with which you can test a published workflow through the NL Flow API, select the ellipsis then Download Postman collection.

Once you have imported the collection into Postman, for each request you must set the X-API-KEY header with the value of one of the API key linked with the published workflow. You can find more information about workflow-key association in the description of the Runtime view of the dashboard.

Export the workflow

To export the workflow, select the ellipsis then Export workflow.

Upload a model

To upload a new model, select the upload button beside the component type in the left panel.

Inside the dialog:

1. Select the model type.
2. Select Browse files and locate the previously exported file.
3. Enter the model name.
4. Select Upload.

Info

The maximum allowed file size is 4GB.

It is also possible to upload a model also in the Models view of the dashboard.