Data Item Linking

Each output item from a node has metadata linking it to the input item used. This allows you to trace back and access previous items. Understanding item linking is important when creating programmatic nodes or using the Code node, especially if data is split or merged.

Automatic item linking

If a node does not specify how to link inputs and outputs, Appizap Workflow Builder will attempt to link them 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:- Appizap Workflow Builder can automatically add the right information for linked items if you modify the order or remove some items. Appizap Workflow Builder connects inputs and outputs in order if they are equal in number. For example, output-1 connects to input-1, output-2 to input-2, and so forth. Appizap Workflow Builder cannot automatically link items if the number is not equal or you create new items.

Appizap Workflow Builder cannot automatically link items if the node does not handle item linking, resulting in an error displayed by Appizap Workflow Builder.

In the example below: Appizap Workflow Builder can connect an item in one node to a previous step, even if the order changes. This allows the node sorting movies alphabetically to access information from the node with famous movie actors. Accessing linked items varies based on whether you use the UI, expressions, or the code node.

Item linking in the Code node

Appizap Workflow Builder's item linking helps retrieve data from previous items. It affects the Code node as well. Nodes typically connect output items to input items, creating a chain to access earlier items.

When employing the Code node, there are certain situations in which manual provision of item linking details is necessary in order to utilize $("<node-name>").item at a later stage in the workflow. These situations only arise when multiple incoming items are present. Appizap Workflow Builder autonomously manages item linking for individual items.

These scenarios are when you:

• Add new items: the new items aren't linked to any input.

• Return new items.

• Want to manually control the item linking.

The automatic item linking handles the other scenarios.

To control item linking, set pairedItem when returning data. Example, to link to the item at index 0:

[
	{
		"json": {
			. . . 
		},
		// The index of the input item that generated this output item
		"pairedItem": 0
	}
]

pairedItem usage example

[
  {
    "id": "23423532",
    "name": "Jay Gatsby"
  },
  {
    "id": "23423533",
    "name": "José Arcadio Buendía"
  },
  {
    "id": "23423534",
    "name": "Max Sendak"
  },
  {
    "id": "23423535",
    "name": "Zaphod Beeblebrox"
  },
  {
    "id": "23423536",
    "name": "Edmund Pevensie"
  }
]

Use it to generate new items, containing just the name, along with a new piece of data.

newItems = [];
for(let i=0; i<items.length; i++){
  newItems.push(
    {
    "json":
      {
        "name": items[i].json.name,
				"aBrandNewField": "New data for item " + i
      }
    }
  )
}

return newItems;

newItems is an array of items with no pairedItem. This means there's no way to trace back from these items to the items used to generate them.

Add the pairedItem object:

newItems = [];
for(let i=0; i<items.length; i++){
  newItems.push(
    {
      "json":
        {
          "name": items[i].json.name,
					"aBrandNewField": "New data for item " + i
        },
      "pairedItem": i
    }    
  )
}
return newItems;

Each new item now links to the item used to create it.

Item linking errors

You can use data from any previous node. It doesn't have to be the immediate previous node. When referencing nodes further back, use the expression syntax $(node_name).item

Given that the preceding node may contain multiple elements, Appizap Workflow Builder is designed to determine the specific element to utilize. By employing the .item feature, Appizap Workflow Builder can automatically select the appropriate element without requiring user intervention.

If information is missing, .item fails in Appizap Workflow Builder. Appizap Workflow Builder traces back through the workflow's nodes to determine which item to use. The thread tells Appizap Workflow Builder which items in previous nodes created a specific item. Appizap Workflow Builder continues to follow this thread to locate the corresponding item in a previous node.

When using .item, Appizap Workflow Builder displays an error when:

• The thread is broken

• The thread points to more than one item in the previous node (as it's unclear which one to use)

To solve these errors, you can either avoid using .item, or fix the root cause.

You can avoid .item by using .first(), .last() or .all()[index] instead. In order to utilize the target node effectively, understanding the precise location of the item being sought is essential.

The fix for the root cause depends on the exact error.

Fix for 'Info for expressions missing from previous node'#

If you see this error message:

ERROR: Info for expression missing from previous node

There is a node in the chain that does not return pairing information. The solution here depends on the type of the previous node:

• Code nodes: Ensure you document the input items used by the node to create each output item. Check the code node for details on item linking.

• Custom or community nodes: The node creator must update the node to show which input items are used for each output item. More information can be found in the Item linking section for node creators.

Fix for 'Multiple matching items for expression'

This is the error message:

ERROR: Multiple matching items for expression

Appizap Workflow Builder can use multiple items to make a single item. Examples include Summarize, Aggregate, and Merge nodes. These nodes combine information from multiple items.

When you use .item and there are multiple possible matches, Appizap Workflow Builder doesn't know which one to use. To solve this you can either:

• Use .first(), .last() or .all()[index] instead.

• Refer a different node that contains the same information, but doesn't have multiple matching items.

Item linking for node creators

This is for programmatic-style nodes. If you use declarative style, Appizap Workflow Builder will handle paired items automatically.

Use Appizap Workflow Builder's item linking to access data from previous items. Appizap Workflow Builder requires input item information for each output item. Missing information can cause issues with expressions in other nodes. Node developers must ensure that items returned by their nodes support this requirement.

If you need to handle item linking manually, do this by setting pairedItem on each item your node returns:

// Use the pairedItem information of the incoming item
newItem = {
	"json": { . . . },
	"pairedItem": {
		"item": item.pairedItem,
		// Optional: choose the input to use
		// Set this if your node combines multiple inputs
		"input": 0
};

// Or set the index manually
newItem = {
		"json": { . . . }
		"pairedItem": {
			"item": i,
			// Optional: choose the input to use
			// Set this if your node combines multiple inputs
			"input": 0
		},
};