Skip to content

Manage input mapping

Introduction

Some components of a workflow expect to receive JSON input with a specific format and do not work if they receive an unrecognized input. In the reference section of this manual you will find the description of the JSON keys that components' blocks recognize in their input.

The first block of a data flow has as its default input the entire workflow input, that is, the JSON payload of the analysis request transmitted to the workflow via its API or with the interactive test interface.
Such input must contain a valid combination of keys among those that the block expects.
The presence of other keys in the input can be tolerated (excess keys are ignored) or not, depending on the type of component and the keys themselves. For example, it is not tolerated if a block expects one of two alternative combinations of keys and both are present in the input (ambiguous input).

Any other block in a flow except the first, depending on its type, may allow and need input mapping.
Input mapping consists of indicating, by editing the properties of the block, which keys present in the JSON produced by upstream blocks must be "read" by the block. The keys can be among those produced by the previous block in the flow, but not necessarily: they can also be keys from other upstream blocks, including the first block. This means that the JSON received from a block other than the first can be a collage constructed on the fly by NL Flow immediately before executing the block, drawing on different sources upstream of the block itself.

Info

Mapped keys must be of the same type: an object must be mapped to an input property if the Object type, an array to a property of the Array type, a string to a String input property, etc.

Read the following articles to know about the input of built-in components:

Also, to know about the expected input of a component, you can use the component guide.

Note

Also a custom component may need input mapping, to have more information ask to the administrator of your installation.

Fully automatic mapping

The editor tries to automatically map input properties when the block is connected to a previous block. The editor searches exact matches—type and name—between the output keys of the block from which the connection originates and the input properties of the block that receives the connection. If matches are found, the block's input properties are set automatically.

Assisted mapping

Fully automatic mapping cannot happen if the names and the types of the direct input to a block don't exactly coincide with the input keys the block expects. In this case you can try assisted mapping, which looks for type only correspondence:

  • Edit the block.
  • Go to the Input tab of the block's properties dialog.
  • Select Map properties automatically on the right in the tabs' strip.

The editor will then use a smart assistant to try again to automatically map input properties to output keys of the previous block, this time without requiring the name of the output key to match the name of an input property, only data types have to match.

Manual mapping

If automatic and assisted mapping cannot be done or as an alternative, also when you want to map input properties to the output keys of upstream blocks other than the previous, you have to perform mapping manually.

For most blocks, you do it in the Input tab of the block properties dialog which opens up when you edit the block, the exceptions being the Map block, for which mapping is considered a functional feature and hence is set through functional properties, under the Functional tab.
Follow the links in the introduction above to read the articles about the peculiarities of input mapping for each component.

If the workflow's input JSON has been described to the editor, its top-level keys can be mapped to the input properties of any block.
Mapping to the keys of the workflow's input is done as above, the keys of the workflow's input can be recognized because they have the conventional prefix $nlflow_input.