mirror of
https://github.com/n8n-io/n8n-docs.git
synced 2026-03-27 09:28:43 +07:00
Merge pull request #2183 from n8n-io/DOC-894
DOC-894: Update look and feel of Node base file page
This commit is contained in:
Deborah
@@ -1,415 +0,0 @@
|
||||
---
|
||||
contentType: reference
|
||||
---
|
||||
|
||||
# Node base file
|
||||
|
||||
The node base file contains the core code of your node. All nodes must have a base file. The contents of this file are different depending on whether you're building a declarative-style or programmatic-style node. For guidance on which style to use, refer to [Choose your node building approach](/integrations/creating-nodes/plan/choose-node-method/).
|
||||
|
||||
This document gives short code snippets to help understand the code structure and concepts. For full walk-throughs of building a node, including real-world code examples, refer to [Build a declarative-style node](/integrations/creating-nodes/build/declarative-style-node/) or [Build a programmatic-style node](/integrations/creating-nodes/build/programmatic-style-node/).
|
||||
|
||||
You can also explore the [n8n-nodes-starter](https://github.com/n8n-io/n8n-nodes-starter){:target=_blank .external-link} and n8n's own [nodes](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes){:target=_blank .external-link} for a wider range of examples. The starter contains basic examples that you can build on. The n8n [Mattermost node](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Mattermost) is a good example of a more complex programmatic-style node, including versioning.
|
||||
|
||||
|
||||
## Structure of the node base file
|
||||
|
||||
The node base file follows this basic structure:
|
||||
|
||||
1. Import statements
|
||||
2. Create a class for the node
|
||||
3. Within the node class, create a `description` object, which defines the node.
|
||||
|
||||
A programmatic-style node also has an `execute()` method, which reads incoming data and parameters, then builds a request. The declarative style handles this using the `routing` key in the `properties` object, within `descriptions`.
|
||||
|
||||
### Outline structure for a declarative-style node
|
||||
|
||||
This code snippet gives an outline of the node structure.
|
||||
|
||||
```js
|
||||
import { INodeType, INodeTypeDescription } from 'n8n-workflow';
|
||||
|
||||
export class ExampleNode implements INodeType {
|
||||
description: INodeTypeDescription = {
|
||||
// Basic node details here
|
||||
properties: [
|
||||
// Resources and operations here
|
||||
]
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Outline structure for a programmatic-style node
|
||||
|
||||
This code snippet gives an outline of the node structure.
|
||||
|
||||
```js
|
||||
import { IExecuteFunctions } from 'n8n-core';
|
||||
import { INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
|
||||
|
||||
export class ExampleNode implements INodeType {
|
||||
description: INodeTypeDescription = {
|
||||
// Basic node details here
|
||||
properties: [
|
||||
// Resources and operations here
|
||||
]
|
||||
};
|
||||
|
||||
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
|
||||
// Process data and return
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Standard parameters
|
||||
|
||||
These parameters are the same for all node types.
|
||||
|
||||
### `displayName`
|
||||
|
||||
_String_ | _Required_
|
||||
|
||||
This is the name users see in the n8n GUI.
|
||||
|
||||
### `name`
|
||||
|
||||
_String_ | _Required_
|
||||
|
||||
The internal name of the object. Used to reference it from other places in the node.
|
||||
|
||||
### `icon`
|
||||
|
||||
_String_ or _Object_ | _Required_
|
||||
|
||||
Specifies an icon for a particular node. n8n recommends uploading your own image file.
|
||||
|
||||
You can provide the icon file name as a string, or as an object to handle different icons for light and dark modes.
|
||||
If the icon works in both light and dark modes, use a string that starts with `file:`, indicating the path to the icon file. For example:
|
||||
|
||||
```
|
||||
icon: 'file:exampleNodeIcon.svg'
|
||||
```
|
||||
To provide different icons for light and dark modes, use an object with `light` and `dark` properties. For example:
|
||||
```
|
||||
icon: {
|
||||
light: 'file:exampleNodeIcon.svg',
|
||||
dark: 'file:exampleNodeIcon.dark.svg'
|
||||
}
|
||||
```
|
||||
|
||||
--8<-- "_snippets/integrations/creating-nodes/node-icons.md"
|
||||
|
||||
### `group`
|
||||
|
||||
_Array of strings_ | _Required_
|
||||
|
||||
Tells n8n how the node behaves when the workflow runs. Options are:
|
||||
|
||||
* `trigger`: node waits for a trigger.
|
||||
* `schedule`: node waits for a timer to expire.
|
||||
* `input`, `output`, `transform`: these currently have no effect.
|
||||
* An empty array, `[]`. Use this as the default option if you don't need `trigger` or `schedule`.
|
||||
|
||||
### `description`
|
||||
|
||||
_String_ | _Required_
|
||||
|
||||
A short description of the node. n8n uses this in the GUI.
|
||||
|
||||
### `defaults`
|
||||
|
||||
_Object_ | _Required_
|
||||
|
||||
Contains essential brand and name settings.
|
||||
|
||||
The object can include:
|
||||
|
||||
* `name`: String. Used as the node name on the canvas if the `displayName` is too long.
|
||||
* `color`: String. Hex color code. Provide the brand color of the integration for use in n8n.
|
||||
|
||||
### `forceInputNodeExecution`
|
||||
|
||||
_Boolean_ | _Optional_
|
||||
|
||||
When building a multi-input node, you can choose to force all preceding nodes on all branches to execute before the node runs. The default is `false` (requiring only one input branch to run).
|
||||
|
||||
### `inputs`
|
||||
|
||||
_Array of strings_ | _Required_
|
||||
|
||||
Names the input connectors. Controls the number of connectors the node has on the input side. If you need only one connector, use `input: ['main']`.
|
||||
|
||||
|
||||
### `outputs`
|
||||
|
||||
_Array of strings_ | _Required_
|
||||
|
||||
Names the output connectors. Controls the number of connectors the node has on the output side. If you need only one connector, use `output: ['main']`.
|
||||
|
||||
### `requiredInputs`
|
||||
|
||||
_Integer_ or _Array_ | _Optional_
|
||||
|
||||
Used for multi-input nodes. Specify inputs by number that must have data (their branches must run) before the node can execute.
|
||||
|
||||
### `credentials`
|
||||
|
||||
_Array of objects_ | _Required_
|
||||
|
||||
This parameter tells n8n the credential options. Each object defines an authentication type.
|
||||
|
||||
The object must include:
|
||||
|
||||
* `name`: the credential name. Must match the `name` property in the credential file. For example, `name: 'asanaApi'` in [`Asana.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Asana/Asana.node.ts){:target=_blank .external-class} links to `name = 'asanaApi'` in [`AsanaApi.credential.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/credentials/AsanaApi.credentials.ts){:target=_blank .external-class}.
|
||||
* `required`: Boolean. Specify whether authentication is required to use this node.
|
||||
|
||||
### `requestDefaults`
|
||||
|
||||
_Object_ | _Required_
|
||||
|
||||
Set up the basic information for the API calls the node makes.
|
||||
|
||||
This object must include:
|
||||
|
||||
* `baseURL`: The API base URL.
|
||||
|
||||
You can also add:
|
||||
|
||||
* `headers`: an object describing the API call headers, such as content type.
|
||||
* `url`: string. Appended to the `baseURL`. You can usually leave this out. It's more common to provide this in the `operations`.
|
||||
|
||||
### `properties`
|
||||
|
||||
_Array of objects_ | _Required_
|
||||
|
||||
This contains the resource and operations objects that define node behaviors, as well as objects to set up mandatory and optional fields that can receive user input.
|
||||
|
||||
#### Resource objects
|
||||
|
||||
A resource object includes the following parameters:
|
||||
|
||||
* `displayName`: String. This should always be `Resource`.
|
||||
* `name`: String. This should always be `resource`.
|
||||
* `type`: String. Tells n8n which UI element to use, and what input type to expect. For example, `options` results in n8n adding a dropdown that allows users to choose one option. Refer to [Node UI elements](/integrations/creating-nodes/build/reference/ui-elements/) for more information.
|
||||
* `noDataExpression`: Boolean. Prevents using an expression for the parameter. Must always be `true` for `resource`.
|
||||
|
||||
#### Operations objects
|
||||
|
||||
The operations object defines the available operations on a resource.
|
||||
|
||||
* `displayName`: String. This should always be `Options`.
|
||||
* `name`: String. This should always be `option`.
|
||||
* `type`: String. Tells n8n which UI element to use, and what input type to expect. For example, `dateTime` results in n8n adding a date picker. Refer to [Node UI elements](/integrations/creating-nodes/build/reference/ui-elements/) for more information.
|
||||
* `noDataExpression`: Boolean. Prevents using an expression for the parameter. Must always be `true` for `operation`.
|
||||
* `options`: Array of objects. Each objects describes an operation's behavior, such as its routing, the REST verb it uses, and so on. An `options` object includes:
|
||||
* `name`. String.
|
||||
* `value`. String.
|
||||
* `action`: String. This parameter combines the resource and operation. You should always include it, as n8n will use it in future versions. For example, given a resource called `"Card"` and an operation `"Get all"`, your action is `"Get all cards"`.
|
||||
* `description`: String.
|
||||
* `routing`: Object containing request details.
|
||||
|
||||
#### Additional fields objects
|
||||
|
||||
These objects define optional parameters. n8n displays them under **Additional Fields** in the GUI. Users can choose which parameters to set.
|
||||
|
||||
The objects must include:
|
||||
|
||||
```js
|
||||
displayName: 'Additional Fields',
|
||||
name: 'additionalFields',
|
||||
// The UI element type
|
||||
type: ''
|
||||
placeholder: 'Add Field',
|
||||
default: {},
|
||||
displayOptions: {
|
||||
// Set which resources and operations this field is available for
|
||||
show: {
|
||||
resource: [
|
||||
// Resource names
|
||||
],
|
||||
operation: [
|
||||
// Operation names
|
||||
]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
For more information about UI element types, refer to [UI elements](/integrations/creating-nodes/build/reference/ui-elements/).
|
||||
|
||||
|
||||
|
||||
## Declarative-style parameters
|
||||
|
||||
### `methods` and `loadOptions`
|
||||
|
||||
_Object_ | _Optional_
|
||||
|
||||
`methods` contains the `loadOptions` object. You can use `loadOptions` to query the service to get user-specific settings, then return them and render them in the GUI so the user can include them in subsequent queries. The object must include routing information for how to query the service, and output settings that define how to handle the returned options. For example:
|
||||
|
||||
```js
|
||||
methods : {
|
||||
loadOptions: {
|
||||
routing: {
|
||||
request: {
|
||||
url: '/webhook/example-option-parameters',
|
||||
method: 'GET',
|
||||
},
|
||||
output: {
|
||||
postReceive: [
|
||||
{
|
||||
// When the returned data is nested under another property
|
||||
// Specify that property key
|
||||
type: 'rootProperty',
|
||||
properties: {
|
||||
property: 'responseData',
|
||||
},
|
||||
},
|
||||
{
|
||||
type: 'setKeyValue',
|
||||
properties: {
|
||||
name: '={{$responseItem.key}} ({{$responseItem.value}})',
|
||||
value: '={{$responseItem.value}}',
|
||||
},
|
||||
},
|
||||
{
|
||||
// If incoming data is an array of objects, sort alphabetically by key
|
||||
type: 'sort',
|
||||
properties: {
|
||||
key: 'name',
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
### `routing`
|
||||
|
||||
_Object_ | _Required_
|
||||
|
||||
`routing` is an object used within an `options` array in operations and input field objects. It contains the details of an API call.
|
||||
|
||||
The code example below comes from the [Declarative-style tutorial](/integrations/creating-nodes/build/declarative-style-node/). It sets up an integration with a NASA API. It shows how to use `requestDefaults` to set up the basic API call details, and `routing` to add information for each operation.
|
||||
|
||||
```js
|
||||
description: INodeTypeDescription = {
|
||||
// Other node info here
|
||||
requestDefaults: {
|
||||
baseURL: 'https://api.nasa.gov',
|
||||
url: '',
|
||||
headers: {
|
||||
Accept: 'application/json',
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
},
|
||||
properties: [
|
||||
// Resources here
|
||||
{
|
||||
displayName: 'Operation'
|
||||
// Other operation details
|
||||
options: [
|
||||
{
|
||||
name: 'Get'
|
||||
value: 'get',
|
||||
description: '',
|
||||
routing: {
|
||||
request: {
|
||||
method: 'GET',
|
||||
url: '/planetary/apod'
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<!--
|
||||
|
||||
TODO: more info on the routing object
|
||||
### routing.output
|
||||
|
||||
include postReceive actions, including ability to dynamically disable - see DOC-400
|
||||
|
||||
### routing.request
|
||||
|
||||
### routing.send
|
||||
|
||||
-->
|
||||
|
||||
### `version`
|
||||
|
||||
_Number_ or _Array_ | Optional
|
||||
|
||||
If you have one version of your node, this can be a number. If you want to support more than one version, turn this into an array, containing numbers for each node version.
|
||||
|
||||
n8n supports two methods of node versioning, but declarative-style nodes must use the light versioning approach. Refer to [Node versioning](/integrations/creating-nodes/build/reference/node-versioning/) for more information.
|
||||
|
||||
## Programmatic-style parameters
|
||||
|
||||
|
||||
### `defaultVersion`
|
||||
|
||||
_Number_ | _Optional_
|
||||
|
||||
Use `defaultVersion` when using the full versioning approach.
|
||||
|
||||
n8n support two methods of node versioning. Refer to [Node versioning](/integrations/creating-nodes/build/reference/node-versioning/) for more information.
|
||||
|
||||
### `methods` and `loadOptions`
|
||||
|
||||
_Object_ | _Optional_
|
||||
|
||||
Contains the `loadOptions` method for programmatic-style nodes. You can use this method to query the service to get user-specific settings (such as getting a user's email labels from Gmail), then return them and render them in the GUI so the user can include them in subsequent queries.
|
||||
|
||||
For example, n8n's [Gmail node](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Google/Gmail/Gmail.node.ts) uses `loadOptions` to get all email labels:
|
||||
|
||||
```js
|
||||
methods = {
|
||||
loadOptions: {
|
||||
// Get all the labels and display them
|
||||
async getLabels(
|
||||
this: ILoadOptionsFunctions,
|
||||
): Promise<INodePropertyOptions[]> {
|
||||
const returnData: INodePropertyOptions[] = [];
|
||||
const labels = await googleApiRequestAllItems.call(
|
||||
this,
|
||||
'labels',
|
||||
'GET',
|
||||
'/gmail/v1/users/me/labels',
|
||||
);
|
||||
for (const label of labels) {
|
||||
const labelName = label.name;
|
||||
const labelId = label.id;
|
||||
returnData.push({
|
||||
name: labelName,
|
||||
value: labelId,
|
||||
});
|
||||
}
|
||||
return returnData;
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### `version`
|
||||
|
||||
_Number_ or _Array_ | _Optional_
|
||||
|
||||
Use `version` when using the light versioning approach.
|
||||
|
||||
If you have one version of your node, this can be a number. If you want to support multiple versions, turn this into an array, containing numbers for each node version.
|
||||
|
||||
n8n support two methods of node versioning. Programmatic-style nodes can use either. Refer to [Node versioning](/integrations/creating-nodes/build/reference/node-versioning/) for more information.
|
||||
|
||||
## Programmatic-style: The execute() method
|
||||
|
||||
The main difference between the declarative and programmatic styles is how they handle incoming data and build API requests. The programmatic style requires an `execute()` method, which reads incoming data and parameters, then builds a request. The declarative style handles requests using the `routing` key in the `operations` object.
|
||||
|
||||
The `execute()` method creates and returns an instance of `INodeExecutionData`.
|
||||
|
||||
/// warning | Paired items
|
||||
You must include input and output item pairing information in the data you return. For more information, refer to [Paired items](/integrations/creating-nodes/build/reference/paired-items/).
|
||||
///
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: Declarative-style parameters
|
||||
description: A reference document listing the declarative-style parameters of the node base file.
|
||||
contentType: reference
|
||||
---
|
||||
|
||||
# Declarative-style parameters
|
||||
|
||||
These are the parameters available for [node base file](/integrations/creating-nodes/build/reference/node-base-files/) of declarative-style nodes.
|
||||
|
||||
This document gives short code snippets to help understand the code structure and concepts. For a full walk-through of building a node, including real-world code examples, refer to [Build a declarative-style node](/integrations/creating-nodes/build/declarative-style-node/).
|
||||
|
||||
Refer to [Standard parameters](/integrations/creating-nodes/build/reference/node-base-files/standard-parameters/) for parameters available to all nodes.
|
||||
|
||||
## `methods` and `loadOptions`
|
||||
|
||||
_Object_ | _Optional_
|
||||
|
||||
`methods` contains the `loadOptions` object. You can use `loadOptions` to query the service to get user-specific settings, then return them and render them in the GUI so the user can include them in subsequent queries. The object must include routing information for how to query the service, and output settings that define how to handle the returned options. For example:
|
||||
|
||||
```js
|
||||
methods : {
|
||||
loadOptions: {
|
||||
routing: {
|
||||
request: {
|
||||
url: '/webhook/example-option-parameters',
|
||||
method: 'GET',
|
||||
},
|
||||
output: {
|
||||
postReceive: [
|
||||
{
|
||||
// When the returned data is nested under another property
|
||||
// Specify that property key
|
||||
type: 'rootProperty',
|
||||
properties: {
|
||||
property: 'responseData',
|
||||
},
|
||||
},
|
||||
{
|
||||
type: 'setKeyValue',
|
||||
properties: {
|
||||
name: '={{$responseItem.key}} ({{$responseItem.value}})',
|
||||
value: '={{$responseItem.value}}',
|
||||
},
|
||||
},
|
||||
{
|
||||
// If incoming data is an array of objects, sort alphabetically by key
|
||||
type: 'sort',
|
||||
properties: {
|
||||
key: 'name',
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## `routing`
|
||||
|
||||
_Object_ | _Required_
|
||||
|
||||
`routing` is an object used within an `options` array in operations and input field objects. It contains the details of an API call.
|
||||
|
||||
The code example below comes from the [Declarative-style tutorial](/integrations/creating-nodes/build/declarative-style-node/). It sets up an integration with a NASA API. It shows how to use `requestDefaults` to set up the basic API call details, and `routing` to add information for each operation.
|
||||
|
||||
```js
|
||||
description: INodeTypeDescription = {
|
||||
// Other node info here
|
||||
requestDefaults: {
|
||||
baseURL: 'https://api.nasa.gov',
|
||||
url: '',
|
||||
headers: {
|
||||
Accept: 'application/json',
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
},
|
||||
properties: [
|
||||
// Resources here
|
||||
{
|
||||
displayName: 'Operation'
|
||||
// Other operation details
|
||||
options: [
|
||||
{
|
||||
name: 'Get'
|
||||
value: 'get',
|
||||
description: '',
|
||||
routing: {
|
||||
request: {
|
||||
method: 'GET',
|
||||
url: '/planetary/apod'
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<!--
|
||||
|
||||
TODO: more info on the routing object
|
||||
### routing.output
|
||||
|
||||
include postReceive actions, including ability to dynamically disable - see DOC-400
|
||||
|
||||
### routing.request
|
||||
|
||||
### routing.send
|
||||
|
||||
-->
|
||||
|
||||
## `version`
|
||||
|
||||
_Number_ or _Array_ | _Optional_
|
||||
|
||||
If you have one version of your node, this can be a number. If you want to support more than one version, turn this into an array, containing numbers for each node version.
|
||||
|
||||
n8n supports two methods of node versioning, but declarative-style nodes must use the light versioning approach. Refer to [Node versioning](/integrations/creating-nodes/build/reference/node-versioning/) for more information.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
contentType: overview
|
||||
---
|
||||
|
||||
# Node base file
|
||||
|
||||
The node base file contains the core code of your node. All nodes must have a base file. The contents of this file are different depending on whether you're building a declarative-style or programmatic-style node. For guidance on which style to use, refer to [Choose your node building approach](/integrations/creating-nodes/plan/choose-node-method/).
|
||||
|
||||
These documents give short code snippets to help understand the code structure and concepts. For full walk-throughs of building a node, including real-world code examples, refer to [Build a declarative-style node](/integrations/creating-nodes/build/declarative-style-node/) or [Build a programmatic-style node](/integrations/creating-nodes/build/programmatic-style-node/).
|
||||
|
||||
You can also explore the [n8n-nodes-starter](https://github.com/n8n-io/n8n-nodes-starter){:target=_blank .external-link} and n8n's own [nodes](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes){:target=_blank .external-link} for a wider range of examples. The starter contains basic examples that you can build on. The n8n [Mattermost node](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Mattermost) is a good example of a more complex programmatic-style node, including versioning.
|
||||
|
||||
For all nodes, refer to the:
|
||||
|
||||
* [Structure of the node base file](/integrations/creating-nodes/build/reference/node-base-files/structure/)
|
||||
* [Standard parameters](/integrations/creating-nodes/build/reference/node-base-files/standard-parameters/)
|
||||
|
||||
For declarative-style nodes, refer to the:
|
||||
|
||||
* [Declarative-style parameters](/integrations/creating-nodes/build/reference/node-base-files/declarative-style-parameters/)
|
||||
|
||||
For programmatic-style nodes, refer to the:
|
||||
|
||||
* [Programmatic-style parameters](/integrations/creating-nodes/build/reference/node-base-files/programmatic-style-parameters/)
|
||||
* [Programmatic-style execute() method](/integrations/creating-nodes/build/reference/node-base-files/programmatic-style-execute-method/)
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Programmatic-style execute() method
|
||||
description: A reference document for the programmatic-style execute() method of the node base file.
|
||||
contentType: reference
|
||||
---
|
||||
|
||||
# Programmatic-style execute() method
|
||||
|
||||
The main difference between the declarative and programmatic styles is how they handle incoming data and build API requests. The programmatic style requires an `execute()` method, which reads incoming data and parameters, then builds a request. The declarative style handles requests using the `routing` key in the `operations` object.
|
||||
|
||||
The `execute()` method creates and returns an instance of `INodeExecutionData`.
|
||||
|
||||
/// warning | Paired items
|
||||
You must include input and output item pairing information in the data you return. For more information, refer to [Paired items](/integrations/creating-nodes/build/reference/paired-items/).
|
||||
///
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Programmatic-style parameters
|
||||
description: A reference document listing the programmatic-style parameters of the node base file.
|
||||
contentType: reference
|
||||
---
|
||||
|
||||
# Programmatic-style parameters
|
||||
|
||||
These are the parameters available for [node base file](/integrations/creating-nodes/build/reference/node-base-files/) of programmatic-style nodes.
|
||||
|
||||
This document gives short code snippets to help understand the code structure and concepts. For a full walk-through of building a node, including real-world code examples, refer to [Build a programmatic-style node](/integrations/creating-nodes/build/programmatic-style-node/).
|
||||
|
||||
Programmatic-style nodes also use the `execute()` method. Refer to [Programmatic-style execute method](/integrations/creating-nodes/build/reference/node-base-files/programmatic-style-execute-method/) for more information.
|
||||
|
||||
Refer to [Standard parameters](/integrations/creating-nodes/build/reference/node-base-files/standard-parameters/) for parameters available to all nodes.
|
||||
|
||||
## `defaultVersion`
|
||||
|
||||
_Number_ | _Optional_
|
||||
|
||||
Use `defaultVersion` when using the full versioning approach.
|
||||
|
||||
n8n support two methods of node versioning. Refer to [Node versioning](/integrations/creating-nodes/build/reference/node-versioning/) for more information.
|
||||
|
||||
## `methods` and `loadOptions`
|
||||
|
||||
_Object_ | _Optional_
|
||||
|
||||
Contains the `loadOptions` method for programmatic-style nodes. You can use this method to query the service to get user-specific settings (such as getting a user's email labels from Gmail), then return them and render them in the GUI so the user can include them in subsequent queries.
|
||||
|
||||
For example, n8n's [Gmail node](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Google/Gmail/Gmail.node.ts) uses `loadOptions` to get all email labels:
|
||||
|
||||
```js
|
||||
methods = {
|
||||
loadOptions: {
|
||||
// Get all the labels and display them
|
||||
async getLabels(
|
||||
this: ILoadOptionsFunctions,
|
||||
): Promise<INodePropertyOptions[]> {
|
||||
const returnData: INodePropertyOptions[] = [];
|
||||
const labels = await googleApiRequestAllItems.call(
|
||||
this,
|
||||
'labels',
|
||||
'GET',
|
||||
'/gmail/v1/users/me/labels',
|
||||
);
|
||||
for (const label of labels) {
|
||||
const labelName = label.name;
|
||||
const labelId = label.id;
|
||||
returnData.push({
|
||||
name: labelName,
|
||||
value: labelId,
|
||||
});
|
||||
}
|
||||
return returnData;
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## `version`
|
||||
|
||||
_Number_ or _Array_ | _Optional_
|
||||
|
||||
Use `version` when using the light versioning approach.
|
||||
|
||||
If you have one version of your node, this can be a number. If you want to support multiple versions, turn this into an array, containing numbers for each node version.
|
||||
|
||||
n8n support two methods of node versioning. Programmatic-style nodes can use either. Refer to [Node versioning](/integrations/creating-nodes/build/reference/node-versioning/) for more information.
|
||||
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: Standard parameters
|
||||
description: A reference document listing the standard parameters of the node base file.
|
||||
contentType: reference
|
||||
---
|
||||
|
||||
# Standard parameters
|
||||
|
||||
These are the standard parameters for the [node base file](/integrations/creating-nodes/build/reference/node-base-files/). They're the same for all node types.
|
||||
|
||||
## `displayName`
|
||||
|
||||
_String_ | _Required_
|
||||
|
||||
This is the name users see in the n8n GUI.
|
||||
|
||||
## `name`
|
||||
|
||||
_String_ | _Required_
|
||||
|
||||
The internal name of the object. Used to reference it from other places in the node.
|
||||
|
||||
## `icon`
|
||||
|
||||
_String_ or _Object_ | _Required_
|
||||
|
||||
Specifies an icon for a particular node. n8n recommends uploading your own image file.
|
||||
|
||||
You can provide the icon file name as a string, or as an object to handle different icons for light and dark modes.
|
||||
If the icon works in both light and dark modes, use a string that starts with `file:`, indicating the path to the icon file. For example:
|
||||
|
||||
```
|
||||
icon: 'file:exampleNodeIcon.svg'
|
||||
```
|
||||
To provide different icons for light and dark modes, use an object with `light` and `dark` properties. For example:
|
||||
```
|
||||
icon: {
|
||||
light: 'file:exampleNodeIcon.svg',
|
||||
dark: 'file:exampleNodeIcon.dark.svg'
|
||||
}
|
||||
```
|
||||
|
||||
--8<-- "_snippets/integrations/creating-nodes/node-icons.md"
|
||||
|
||||
## `group`
|
||||
|
||||
_Array of strings_ | _Required_
|
||||
|
||||
Tells n8n how the node behaves when the workflow runs. Options are:
|
||||
|
||||
* `trigger`: node waits for a trigger.
|
||||
* `schedule`: node waits for a timer to expire.
|
||||
* `input`, `output`, `transform`: these currently have no effect.
|
||||
* An empty array, `[]`. Use this as the default option if you don't need `trigger` or `schedule`.
|
||||
|
||||
## `description`
|
||||
|
||||
_String_ | _Required_
|
||||
|
||||
A short description of the node. n8n uses this in the GUI.
|
||||
|
||||
## `defaults`
|
||||
|
||||
_Object_ | _Required_
|
||||
|
||||
Contains essential brand and name settings.
|
||||
|
||||
The object can include:
|
||||
|
||||
* `name`: String. Used as the node name on the canvas if the `displayName` is too long.
|
||||
* `color`: String. Hex color code. Provide the brand color of the integration for use in n8n.
|
||||
|
||||
## `forceInputNodeExecution`
|
||||
|
||||
_Boolean_ | _Optional_
|
||||
|
||||
When building a multi-input node, you can choose to force all preceding nodes on all branches to execute before the node runs. The default is `false` (requiring only one input branch to run).
|
||||
|
||||
## `inputs`
|
||||
|
||||
_Array of strings_ | _Required_
|
||||
|
||||
Names the input connectors. Controls the number of connectors the node has on the input side. If you need only one connector, use `input: ['main']`.
|
||||
|
||||
|
||||
## `outputs`
|
||||
|
||||
_Array of strings_ | _Required_
|
||||
|
||||
Names the output connectors. Controls the number of connectors the node has on the output side. If you need only one connector, use `output: ['main']`.
|
||||
|
||||
## `requiredInputs`
|
||||
|
||||
_Integer_ or _Array_ | _Optional_
|
||||
|
||||
Used for multi-input nodes. Specify inputs by number that must have data (their branches must run) before the node can execute.
|
||||
|
||||
## `credentials`
|
||||
|
||||
_Array of objects_ | _Required_
|
||||
|
||||
This parameter tells n8n the credential options. Each object defines an authentication type.
|
||||
|
||||
The object must include:
|
||||
|
||||
* `name`: the credential name. Must match the `name` property in the credential file. For example, `name: 'asanaApi'` in [`Asana.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Asana/Asana.node.ts){:target=_blank .external-class} links to `name = 'asanaApi'` in [`AsanaApi.credential.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/credentials/AsanaApi.credentials.ts){:target=_blank .external-class}.
|
||||
* `required`: Boolean. Specify whether authentication is required to use this node.
|
||||
|
||||
## `requestDefaults`
|
||||
|
||||
_Object_ | _Required_
|
||||
|
||||
Set up the basic information for the API calls the node makes.
|
||||
|
||||
This object must include:
|
||||
|
||||
* `baseURL`: The API base URL.
|
||||
|
||||
You can also add:
|
||||
|
||||
* `headers`: an object describing the API call headers, such as content type.
|
||||
* `url`: string. Appended to the `baseURL`. You can usually leave this out. It's more common to provide this in the `operations`.
|
||||
|
||||
## `properties`
|
||||
|
||||
_Array of objects_ | _Required_
|
||||
|
||||
This contains the resource and operations objects that define node behaviors, as well as objects to set up mandatory and optional fields that can receive user input.
|
||||
|
||||
### Resource objects
|
||||
|
||||
A resource object includes the following parameters:
|
||||
|
||||
* `displayName`: String. This should always be `Resource`.
|
||||
* `name`: String. This should always be `resource`.
|
||||
* `type`: String. Tells n8n which UI element to use, and what input type to expect. For example, `options` results in n8n adding a dropdown that allows users to choose one option. Refer to [Node UI elements](/integrations/creating-nodes/build/reference/ui-elements/) for more information.
|
||||
* `noDataExpression`: Boolean. Prevents using an expression for the parameter. Must always be `true` for `resource`.
|
||||
|
||||
### Operations objects
|
||||
|
||||
The operations object defines the available operations on a resource.
|
||||
|
||||
* `displayName`: String. This should always be `Options`.
|
||||
* `name`: String. This should always be `option`.
|
||||
* `type`: String. Tells n8n which UI element to use, and what input type to expect. For example, `dateTime` results in n8n adding a date picker. Refer to [Node UI elements](/integrations/creating-nodes/build/reference/ui-elements/) for more information.
|
||||
* `noDataExpression`: Boolean. Prevents using an expression for the parameter. Must always be `true` for `operation`.
|
||||
* `options`: Array of objects. Each objects describes an operation's behavior, such as its routing, the REST verb it uses, and so on. An `options` object includes:
|
||||
* `name`. String.
|
||||
* `value`. String.
|
||||
* `action`: String. This parameter combines the resource and operation. You should always include it, as n8n will use it in future versions. For example, given a resource called `"Card"` and an operation `"Get all"`, your action is `"Get all cards"`.
|
||||
* `description`: String.
|
||||
* `routing`: Object containing request details.
|
||||
|
||||
### Additional fields objects
|
||||
|
||||
These objects define optional parameters. n8n displays them under **Additional Fields** in the GUI. Users can choose which parameters to set.
|
||||
|
||||
The objects must include:
|
||||
|
||||
```js
|
||||
displayName: 'Additional Fields',
|
||||
name: 'additionalFields',
|
||||
// The UI element type
|
||||
type: ''
|
||||
placeholder: 'Add Field',
|
||||
default: {},
|
||||
displayOptions: {
|
||||
// Set which resources and operations this field is available for
|
||||
show: {
|
||||
resource: [
|
||||
// Resource names
|
||||
],
|
||||
operation: [
|
||||
// Operation names
|
||||
]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
For more information about UI element types, refer to [UI elements](/integrations/creating-nodes/build/reference/ui-elements/).
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Structure of the node base file
|
||||
description: A reference document detailing the basic structure of the node base file.
|
||||
contentType: reference
|
||||
---
|
||||
|
||||
# Structure of the node base file
|
||||
|
||||
The node base file follows this basic structure:
|
||||
|
||||
1. Add import statements.
|
||||
2. Create a class for the node.
|
||||
3. Within the node class, create a `description` object, which defines the node.
|
||||
|
||||
A programmatic-style node also has an `execute()` method, which reads incoming data and parameters, then builds a request. The declarative style handles this using the `routing` key in the `properties` object, within `descriptions`.
|
||||
|
||||
## Outline structure for a declarative-style node
|
||||
|
||||
This code snippet gives an outline of the node structure.
|
||||
|
||||
```js
|
||||
import { INodeType, INodeTypeDescription } from 'n8n-workflow';
|
||||
|
||||
export class ExampleNode implements INodeType {
|
||||
description: INodeTypeDescription = {
|
||||
// Basic node details here
|
||||
properties: [
|
||||
// Resources and operations here
|
||||
]
|
||||
};
|
||||
}
|
||||
```
|
||||
Refer to [Standard parameters](/integrations/creating-nodes/build/reference/node-base-files/standard-parameters/) for information on parameters available to all node types. Refer to [Declarative-style parameters](/integrations/creating-nodes/build/reference/node-base-files/declarative-style-parameters/) for the parameters available for declarative-style nodes.
|
||||
|
||||
## Outline structure for a programmatic-style node
|
||||
|
||||
This code snippet gives an outline of the node structure.
|
||||
|
||||
```js
|
||||
import { IExecuteFunctions } from 'n8n-core';
|
||||
import { INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
|
||||
|
||||
export class ExampleNode implements INodeType {
|
||||
description: INodeTypeDescription = {
|
||||
// Basic node details here
|
||||
properties: [
|
||||
// Resources and operations here
|
||||
]
|
||||
};
|
||||
|
||||
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
|
||||
// Process data and return
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
Refer to [Standard parameters](/integrations/creating-nodes/build/reference/node-base-files/standard-parameters/) for information on parameters available to all node types. Refer to [Programmatic-style parameters](/integrations/creating-nodes/build/reference/node-base-files/programmatic-style-parameters/) and [Programmatic-style execute method](/integrations/creating-nodes/build/reference/node-base-files/programmatic-style-execute-method/) for more information on working with programmatic-style nodes.
|
||||
@@ -1127,7 +1127,13 @@ nav:
|
||||
- Code standards: integrations/creating-nodes/build/reference/code-standards.md
|
||||
- Versioning: integrations/creating-nodes/build/reference/node-versioning.md
|
||||
- File structure: integrations/creating-nodes/build/reference/node-file-structure.md
|
||||
- Base files: integrations/creating-nodes/build/reference/node-base-files.md
|
||||
- Base files:
|
||||
- integrations/creating-nodes/build/reference/node-base-files/index.md
|
||||
- Structure: integrations/creating-nodes/build/reference/node-base-files/structure.md
|
||||
- Standard parameters: integrations/creating-nodes/build/reference/node-base-files/standard-parameters.md
|
||||
- Declarative-style parameters: integrations/creating-nodes/build/reference/node-base-files/declarative-style-parameters.md
|
||||
- Programmatic-style parameters: integrations/creating-nodes/build/reference/node-base-files/programmatic-style-parameters.md
|
||||
- Programmatic-style execute method: integrations/creating-nodes/build/reference/node-base-files/programmatic-style-execute-method.md
|
||||
- Codex files: integrations/creating-nodes/build/reference/node-codex-files.md
|
||||
- Credentials files: integrations/creating-nodes/build/reference/credentials-files.md
|
||||
- HTTP request helpers: integrations/creating-nodes/build/reference/http-helpers.md
|
||||
|
||||
Reference in New Issue
Block a user