Skip to content

Function#

Using the function node, you can:

  • Transform data from other nodes
  • Implement custom functionality

Function node and function item node

Note that the Function node is different from the Function Item node. Refer to Data | Code to learn about the difference between the two.

The Function node supports:

  • Promises. Instead of returning the items directly, you can return a promise which resolves accordingly.
  • Writing to your browser console using console.log. This is useful for debugging and troubleshooting your workflows.

When working with the Function node, you need to understand the following concepts:

  • Data structure: understand the data you receive in the Function node, and requirements for outputting data from the node.
  • Item linking: learn how data items work. You need to handle item linking when the number of input and output items doesn't match.

n8n provides built-in methods and variables. These provide support for:

  • Accessing specific item data
  • Accessing data about workflows, executions, and your n8n environment
  • Convenience variables to help with data and time

Refer to methods and variables for more information.

Output items#

When using the Function node, you must return data in the format described in data structure.

This example creates 10 items with the IDs 0 to 9:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const newItems = [];

for (let i=0;i<10;i++) {
  newItems.push({
    json: {
      id: i
    }
  });
}

return newItems;

Manage item linking#

n8n's item linking allows you to access data from items that precede the current item. It also has implications when using the Function node. Most nodes link every output item to an input item. This creates a chain of items that you can work back along to access previous items. For a deeper conceptual overview of this topic, refer to Item linking concepts. This document focuses on practical usage examples.

When using the Function node, there are some scenarios where you need to manually supply item linking information if you want to be able to use $("<node-name>").item later in the workflow. These scenarios are when you:

  • Add new items: the new items aren't linked to any input.
  • Return completely new items.
  • Want to manually control the item linking.

n8n's automatic item linking handles the other scenarios.

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

1
2
3
4
5
6
7
8
[
	{
		"json": {
			. . . 
		},
		"pairedItem": 0
	}
]

pairedItem usage example#

Take this input data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
  {
    "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"
  }
]

And use it to generate new items, containing just the name, along with a new piece of data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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.

External libraries#

If you self-host n8n, you can import and use built-in and external npm modules in the Function node. To learn how to enable external modules, refer the Configuration guide.