Item linking concepts

Each output item created by a node includes metadata that links them to the input item (or items) that the node used to generate them. This creates a chain of items that you can work back along to access previous items. This can be complicated to understand, especially if the node splits or merges data. You need to understand item linking when building your own programmatic nodes, or in some scenarios using the Code node.

This document provides a conceptual overview of this feature. For usage details, refer to:

• Item linking for node creators, for details on how to handle item linking when building a node.
• Item linking in the Code node, to learn how to handle item linking in the Code node.
• Item linking errors, to understand the errors you may encounter in the editor UI.

Ensemble's automatic item linking

If a node doesn't control how to link input items to output items, Ensemble tries to guess how to link the items automatically:

• Single input, single output: the output links to the input.
• Single input, multiple outputs: all outputs link to that input.
• Multiple inputs and outputs:
  • If you keep the input items, but change the order (or remove some but keep others), Ensemble can automatically add the correct linked item information.
  • If the number of inputs and outputs is equal, Ensemble links the items in order. This means that output-1 links to input-1, output-2 to input-2, and so on.
  • If the number isn't equal, or you create completely new items, Ensemble can't automatically link items.

If Ensemble can't link items automatically, and the node doesn't handle the item linking, Ensemble displays an error. Refer to Item linking errors for more information.

An item linking example

In this example, it's possible for Ensemble to link an item in the current node back several steps, despite the item order changing. This means the current node can access information about the linked item in the first node.